What the file is for
A coding agent starts every task knowing nothing about your repository except what it can read. It can open files and search, but it cannot know that the real test command needs a flag or that you want to be asked before a migration runs. Without those facts it guesses, and a guess that is wrong once tends to be wrong on every task.
AGENTS.md (or CLAUDE.md) is where those facts live. Think of it as the page you would hand a contractor on their first morning: how to run things, where things are, the house rules and what you expect at the end. The task itself, the bug or the feature, goes in the brief you write each time. The file holds what every brief would otherwise have to repeat.
- Ask before a migration: True for every task 9/10, Hard to work out from the code 8/10
- The full test command: True for every task 8/10, Hard to work out from the code 7/10
- Steps to reproduce this bug: True for every task 1/10, Hard to work out from the code 8/10
- Which framework it uses: True for every task 8/10, Hard to work out from the code 2/10
- How the project began: True for every task 2/10, Hard to work out from the code 2/10
Illustrative: placed by judgment, not measured. A line earns its place when it holds for every task and the agent could not work it out by reading the code.
AGENTS.md or CLAUDE.md
The content is the same; the file name depends on the agent. AGENTS.md is an open format with no required fields, just Markdown with whatever headings you like, and many coding agents look for it at the root of a repository. Claude Code reads CLAUDE.md, and its /init command drafts one from your codebase.
If your team uses more than one agent, keep the facts in one place. Write AGENTS.md, then add a CLAUDE.md beside it whose first line imports it. Claude Code supports imports with an @ and a path, so both tools read the same facts and nobody has to keep two copies in step.
@AGENTS.md ## Claude Code only - For a change that touches both apps/web and apps/api, write a plan first and wait for my yes.
In a monorepo, a package with its own commands or rules can carry its own short file. The guidance for AGENTS.md is that the file nearest the code being changed wins, and that an instruction you type in the chat overrides the file. Claude Code similarly picks up a CLAUDE.md in a subfolder when it works on files there. Keep the root file for what holds everywhere.
1. Commands first
The most useful lines in the file are the exact commands to install, test, lint, type-check and build. They are what lets an agent check its own work before it tells you it is finished. Write them the way you would type them, including the flags that matter and how to run a single test file, because running the whole suite after every small edit is slow.
If the tests need a database or a service running first, say how to start it. An agent that cannot run the tests will either skip them or report a failure that has nothing to do with its change.
2. Where things are
A short map saves the agent a search and keeps it from changing the wrong copy of something. Name the main folders and what each holds. Say where new code goes, and which existing file is the best one to copy. Point out the traps too: generated code that must never be edited by hand, a vendored library, a config file nothing reads any more, an old folder kept only for a migration.
3. Conventions the code does not show
Only write down conventions an agent could not infer from reading a few files, or that the code breaks in places. “Money is integer cents, never floats” belongs here. “Use two spaces” does not if a formatter already enforces it; let the tool do that job, since a rule a program checks never drifts.
Be specific enough that the agent can obey without judgment. “Write clean code” changes nothing. “New endpoints follow routes/invoices.ts, with the test beside it” changes a lot.
4. What needs your yes
Agents act on their own, so the file should list the actions where they must stop and ask: deleting data, writing or running a migration, changing a database schema, adding a dependency, force-pushing or rewriting history, and touching anything that handles money or permissions. These rules matter most for what cannot be undone. A brief can be misread; a standing rule to stop before DROP TABLE is the backstop.
Keep this list honest. If everything needs a yes, the agent asks about everything and the list stops meaning anything.
5. What to hand back
Say what a finished task looks like from your side: the checks it ran and their results, what changed and why, what it left undone, and anything it noticed along the way. Add the rule that the change stays inside the task, with other problems noted instead of fixed. That one line keeps a bug fix from arriving with a reformatted folder attached.
Before
2/10 Needs work
- Has: What to make
- Missing: Who it's for
- Missing: Background facts
- Missing: Length
- Missing: Format
- Missing: What to avoid
- Has: What good looks like
- Missing: An example
- Missing: If unsure
- Missing: Layout
After, with what was added marked
10/10 Excellent
- Has: What to make
- Has: Who it's for
- Has: Background facts
- Has: Length
- Has: Format
- Has: What to avoid
- Has: What good looks like
- Has: An example
- Has: If unsure
- Has: Layout
Scores from the Grader’s free checks, with the coding agent target. The first version reads like advice; the second gives the agent facts it can act on and a way to check its work.
What to leave out
- Secrets. No keys or passwords, ever. The file is committed and shared, and the agent reads it into its context, where it can end up in logs or be repeated in a commit. Say where keys come from (“read keys from the environment;
.envis not in git”) and keep the values out. The guide to API keys covers the habits. - Long documentation. Every line is read on every task. Link to
docs/architecture.mdinstead of pasting it, and the agent can open it when a task needs it. - Instructions for one task. “Fix the date bug before Friday” goes stale the moment it is fixed, and until then the agent may apply it to unrelated work. Put it in the brief.
- History and wishes. How the project started, and rules nobody follows, cost attention and teach the agent that the file is not quite true.
Fix the rounding bug in invoices.ts before Friday's release.
Not quite. That is one task. Put it in the brief, or it lingers in the file and gets applied to work it has nothing to do with.
Run pnpm test before you say a task is done.
Yes. It holds for every task, and the agent cannot know which command you trust without being told.
PAYMENT_API_KEY=… for the payment tests.
Not quite. Never put a key in the file. Say where keys come from, and keep the value in the environment.
Our full architecture document, pasted in.
Not quite. Link to it instead. The agent reads every line of the file on every task, and can open the document when it needs it.
Open an option to see why.
Keep it short and current
A file that is mostly true is worse than a short one that is entirely true, because the agent cannot tell which lines went stale. A few habits keep it honest:
- Change it in pull requests, like code, so the team sees and reviews every rule.
- Update it with the thing it describes. A pull request that renames the test command changes the file in the same commit.
- Add a line when an agent makes the same mistake twice, and word it as a fact or a rule, not a complaint.
- Test it. Start a fresh session and ask the agent how to run one test file and what it must ask you about. If the answers are wrong, the file is unclear.
You do not need a length target. If the file runs past a couple of screens, look for documentation that should be a link and rules that a linter or a test could enforce instead.
A complete example
Here is a full AGENTS.md for a made-up invoicing app with a web front end and an API in one repository. The names and commands are examples; swap in your own.
# AGENTS.md Invoicing web app. Next.js front end in apps/web, Node API in apps/api, shared types in packages/shared. pnpm workspaces. ## Commands - Install: pnpm install - Test everything: pnpm test - Test one file: pnpm test apps/api/src/billing/totals.test.ts - Lint and types: pnpm lint && pnpm typecheck - Build: pnpm build - The API tests need the database: docker compose up -d db, then pnpm --filter api db:migrate ## Where things are - apps/api/src/routes: one file per endpoint - apps/api/src/billing: totals and tax; every change needs a test - apps/web/app: pages and layouts - packages/shared: types used by both apps; change them in the same commit as their callers - apps/api/src/generated: generated by pnpm codegen, never edit ## Conventions - Money is integer cents everywhere. Never use floats for amounts. - Dates are stored in UTC and shown in the customer's time zone. - New endpoints follow apps/api/src/routes/invoices.ts. - Tests sit next to the code as name.test.ts. ## Ask before you - Delete data, or write or run a migration. - Add or upgrade a dependency. - Force-push or rewrite history. - Change anything under apps/api/src/billing/tax-rates. ## Never - Write keys or passwords into code or this file. Read them from the environment; .env is not in git. - Edit files in apps/api/src/generated by hand. ## When you finish - Run pnpm lint, pnpm typecheck, pnpm test and pnpm build. - Report which passed, and paste the output of any that failed. - Summarize what changed and why, and list anything left undone. - Keep the change to the task. Note other problems; do not fix them.
Notice what is missing. There is no description of the product, no list of the libraries in package.json, no style rules a formatter already applies and no mention of any one bug. Everything left is a fact the agent needs on its next task, whatever that task is. When you write that task, the guide to briefing a coding agent covers what each kind needs on top.
Key takeaways
- AGENTS.md and CLAUDE.md hold the standing facts a coding agent reads before each task; the task itself goes in the brief.
- Many agents read AGENTS.md; Claude Code reads CLAUDE.md, which can import AGENTS.md so one file serves both.
- Lead with exact commands for install, test, lint and build, including how to run one test.
- Add a map of the folders and the conventions the code does not show.
- List the actions that need your yes, and say what to hand back.
- Keep secrets, pasted documents, history and one-off instructions out, and change the file in pull requests like code.
Questions
What is the difference between AGENTS.md and CLAUDE.md?
Only the name and which agent reads it. Both are Markdown files of standing instructions for a coding agent. AGENTS.md is an open format that many agents look for, including Codex and Cursor; CLAUDE.md is the file Claude Code reads. The content that works is the same in both: commands, where things are, conventions, what needs your approval and what to hand back.
How do I use one file for Claude Code and other agents?
Keep the facts in AGENTS.md and add a CLAUDE.md next to it that starts with the line @AGENTS.md. Claude Code reads imported files as part of CLAUDE.md, so every agent sees the same commands and rules, and you only update one file. Put anything meant for Claude Code alone below the import.
Where should AGENTS.md go?
At the root of the repository, committed to git so the whole team and every agent see the same version. In a monorepo, a package with its own commands can have its own short AGENTS.md; the file nearest the code being changed applies. Personal preferences belong in your own settings, such as ~/.claude/CLAUDE.md for Claude Code, not in the shared file.
How long should AGENTS.md or CLAUDE.md be?
As short as it can be while staying complete. There is no line count to aim for, but every line is read on every task, so a long file costs attention and tokens and is more likely to hold something stale. Link to longer documents instead of pasting them, and let linters and tests enforce what they can.
Can AI write my AGENTS.md?
It can write the first draft. Claude Code’s /init command drafts a CLAUDE.md from the codebase, and the Agent Brief Check writes a starter AGENTS.md or CLAUDE.md from a task and the facts you give it. Then edit it yourself: cut what the code already says and add the rules only your team knows, such as what must never run without asking.
Prompts to use with this
- Have a coding agent write an AGENTS.md or CLAUDE.md for your repositoryYou want a short instructions file that tells coding agents how to build, test and work in your repository, checked against commands that actually run.
- Brief a coding agent to remove a feature flag after full rolloutA feature flag has been on for everyone long enough, and you want the flag and the old code path deleted cleanly, with tests updated to match.
- Brief a coding agent to fix a bugYou are handing a bug to Claude Code, Codex or another coding agent and want a root-cause fix with proof, not a guess.
- Brief a coding agent to build a small featureYou are handing a well-defined feature to Claude Code, Codex or another coding agent and want a plan first, code that fits the codebase, and tests as proof.