Lab · Beginner · 45 min
Write a Context File That Stops Invented Conventions
Measure how often an agent invents commands or patterns in your repo, then write a short AGENTS.md that fixes it — and prove it with before/after runs.
Cursor · Claude Code · OpenAI Codex · GitHub Copilot
Show all 4 stepsHide list
Step 1 of 4
Lab brief
Goal
A root AGENTS.md under ~80 lines plus thin CLAUDE.md / Cursor rule pointers, with measurably fewer invented conventions.
Failure mode
Agent runs npm test in a pnpm repo, creates utils/ when the project uses lib/, and adds a new HTTP client instead of the existing one.
Staff move
Treat memory files as prompts under test: baseline, change, re-measure, and keep only lines that moved the result.
Step 2 of 4
1. Baseline
- Pick 3 small real tasks (add an endpoint, add a test, fix a lint error)
- Temporarily move existing memory files aside and run each task in a fresh session
- Record every invented convention: wrong command, wrong folder, duplicate utility, wrong style
Step 3 of 4
2. Write the file
# Project guide for agents ## Commands - Install: pnpm install - Test: pnpm test:unit (must pass before finishing) - Lint: pnpm lint --fix ## Layout - src/lib/ shared logic (no React) - src/app/ routes only; keep pages thin ## Conventions - HTTP: use src/lib/http.ts, never add axios - Errors: throw AppError; never swallow with empty catch ## Never - Edit generated files in src/gen/ - Add dependencies without asking
- Add CLAUDE.md containing @AGENTS.md so Claude Code reads the same source
- For Cursor, AGENTS.md is read directly; add a glob-scoped .mdc rule only for folder-specific detail
Step 4 of 4
3. Verify
Rerun the same 3 tasks in fresh sessions. Count invented conventions again. Delete any line in the file that did not change behavior — shorter files get read more reliably.
Stretch
Add a nested AGENTS.md in one package with a different test command and confirm Codex and Cursor pick the nearer file when working there.