Write and test an AGENTS.md file with Claude Code

The same tasks, run before and after, are the fairest way to tell if the file helps.

1. 1Choose 3 to 5 small, real tasks, such as a bug fix, a new endpoint or a missing test.
2. 2Give each one a clear pass check: the tests pass, the build runs or the output matches.
3. 3Include one task in the part of the code where agents slip up most.
4. 4Commit your work, so every run starts from the same point.

You should see a short list of tasks, each with a pass check you can run.

The baseline shows what the agent gets wrong on its own, and that's what the file should fix.

1. 1If the repo has an AGENTS.md or CLAUDE.md, rename it for now, for example to AGENTS.md.off.
2. 2Start claude in the repo and run /context all. Check that no project file shows under Memory files.
3. 3Paste a task, let it finish, then run /usage and note the session cost. Write down every wrong guess and question.
4. 4Run git stash -u to set the changes aside, and /clear before the next task.

[YOUR TEST TASK]. When you're done, run [YOUR TEST COMMAND] and tell me if it passes.

You should see a note for each task: pass or fail, the cost, and every wrong guess or question.

Agents follow what the file says, so every line steers them, for better or worse.

1. 1Turn each wrong guess in your notes into one short line that can be checked.
2. 2Add facts the code doesn't show: the exact test command, a rate limit, a banned library, where generated files live.
3. 3Leave out repo overviews, general coding advice and anything already in the README.
4. 4Save it as AGENTS.md in the repo root, and keep it well under 200 lines.

# AGENTS.md

## Commands
- Run all tests: `[TEST COMMAND]`
- Run one test file: `[SINGLE TEST COMMAND]`

## Rules the code doesn't show
- [A LIMIT, e.g. The payments API allows 10 requests a second. Batch calls.]
- [A CONVENTION, e.g. New API handlers go in src/api/handlers/.]
- Never edit files in [GENERATED FOLDER]. [BUILD COMMAND] rebuilds them.

## Before you finish
- Run [LINT COMMAND] and fix every error.

You should see a short AGENTS.md where every line traces back to a mistake from your baseline.

Never put API keys or passwords in AGENTS.md. It's committed and shared with your code.

A file the agent never reads can't help, and a CLAUDE.md quietly takes its place.

1. 1Start a new claude session in the repo.
2. 2Look for a line such as no CLAUDE.md found; AGENTS.md loaded.
3. 3Run /context all and find AGENTS.md under Memory files.

You should see AGENTS.md listed under Memory files.

Codex reads the same file from the repo root. Its default size limit for all instruction files together is 32 KiB.

Only the same tasks, from the same starting point, show what the file changed.

1. 1Run each test task again in a fresh session, with the same wording as before.
2. 2Note pass or fail, the cost from /usage, and any wrong guesses that are left.
3. 3Put the two sets of notes side by side.

You should see a before and after table with pass or fail and the cost for each task.

Every line is read on every task, so a line that changes nothing only adds cost.

1. 1For each line, check if it fixed a baseline mistake. If it didn't, delete it.
2. 2If a rule must hold every time, back it with a test or a hook. The file is advice, not a lock.
3. 3Run /doctor prompt-audit to find lines that are out of date or contradict each other.

You should see a shorter file where every line matches a fixed mistake, plus an audit report.

A 2026 study from ETH Zurich found that context files written by an AI didn't raise success rates and added about 20% to cost.