CLAUDE.md and AGENTS.md: an annotated example and what each tool loads
An annotated AGENTS.md and CLAUDE.md pair you can copy, plus a load test of which instruction files Claude Code 2.1.314 reads, with the Codex, Copilot and Cursor rules from their docs.
Short answer: write your project instructions once in AGENTS.md, and make a two-line CLAUDE.md that imports it. That setup is read by Claude Code in every layout we tried, and by the other tools that read AGENTS.md. This page gives the files to copy, a reason for each section, and a test of which files Claude Code actually loads.
Who ran the tests. An AI agent procedure ran every Claude Code test below on 2026-10-30, with Claude Code 2.1.314 and the model claude-sonnet-5-5, headless (claude -p), on Linux. No person ran them by hand. Codex, GitHub Copilot and Cursor were not run. Every statement about those tools is documented behavior with its source, marked “documented”, and has not been tested here. Inputs, scripts and raw transcripts are kept in our evidence archive.
Which file does Claude Code read?
Claude Code reads AGENTS.md natively since version 2.1.277 (the changelog dates it September 18, 2026), but with a catch: by default it reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or any directory above it. If any of those exists, AGENTS.md is ignored unless something imports it or you change the Project instructions setting.
We checked this with canary tokens. Each file in a throwaway project held a unique string such as CANARY-ROOTAGENTS-1001. We started a fresh session and asked Claude, without tools, to list every canary token in its context. Where Claude Code can report it, we also logged the InstructionsLoaded hook event, which comes from Claude Code and not from the model.
| Layout (all in the project root unless noted) | What Claude reported | Result |
|---|---|---|
AGENTS.md only | AGENTS token | Read natively |
CLAUDE.md only | CLAUDE token | Read |
CLAUDE.md and AGENTS.md, no import | CLAUDE token only | AGENTS.md ignored |
CLAUDE.md containing @AGENTS.md, plus AGENTS.md | Both tokens | Imported (hook log: include) |
CLAUDE.local.md and AGENTS.md | LOCAL token only | AGENTS.md ignored |
Same, with Project instructions set to claude-md-and-agents-md | Both tokens | Both read |
.claude/CLAUDE.md and AGENTS.md | DOTCLAUDE token only | AGENTS.md ignored |
AGENTS.md in a parent directory, session started in sub/ | AGENTS token | Read from above |
Root and sub/AGENTS.md, nothing read from sub/ | Root token only | Subdirectory file not loaded yet |
Same, after Claude read sub/note.txt | Root and sub tokens | Subdirectory file loaded on demand |
Root CLAUDE.md and sub/AGENTS.md, after reading sub/note.txt | CLAUDE token only | sub/AGENTS.md ignored |
CLAUDE.md with 400 lines, canary on line 400 | Token reported | No truncation at 200 lines |
CLAUDE.md with a canary inside <!-- ... --> | Only the visible token | Block comments stripped |
.claude/rules/r.md alongside CLAUDE.md | CLAUDE and RULE tokens | Rules loaded |
Notes on how to read this table:
- The results match the memory documentation line for line. We found no disagreement in this run.
- For
AGENTS.mdfiles the model’s report is the only witness. Claude Code emittedInstructionsLoadedevents forCLAUDE.md,CLAUDE.local.mdand rules files, but none forAGENTS.mdin any run, so we could not cross-check those with the hook log. - The setting row used a
--settingsfile withpluginConfigs/cc-plugin-agents-md@builtin/instructionFiles: "claude-md-and-agents-md", which is the form the documentation gives for user and flag settings. The interactive/configpanel was not tried. - These are single runs of a model that was asked to repeat what it sees. A token the model did not list was also absent from the hook log in every case where a hook event exists.
- The 200-line figure is documented guidance (“target under 200 lines per CLAUDE.md file”), not a cutoff. Our 400-line file loaded to the end. Long files still cost context and, per the docs, reduce adherence.
- We ran headless sessions only. The documentation says an interactive session shows a line such as
no CLAUDE.md found; AGENTS.md loaded: ...; we did not see that.
The setup we recommend
Keep one source of truth, and let Claude Code reach it through an import:
repo/
├── AGENTS.md # all shared instructions
├── CLAUDE.md # imports AGENTS.md, adds Claude-only notes
└── CLAUDE.local.md # optional, personal, gitignored
With a CLAUDE.md present, Claude Code ignores a bare AGENTS.md, so the import line is what connects them. It also means a personal CLAUDE.local.md does not switch AGENTS.md off for you, because the import already pulled it in. The cost is one extra file. The alternative, setting Project instructions to claude-md-and-agents-md in your own settings, works for you but not for teammates who did not set it. The shared file is also the place for rules every agent must follow, such as the budget for the checks agents may add. Procedures that matter only on some tasks do not belong there: make them skills, which load only when used.
CLAUDE.md
@AGENTS.md
## Claude Code
- Run the type checker after edits: `npm run typecheck`.
- Never edit `src/generated/`; see AGENTS.md for how it is produced.
The first line imports AGENTS.md into the context at launch. Imports are expanded in place and do not shrink the context cost, so this saves maintenance, not tokens. Import syntax inside code spans and fenced blocks is skipped, so write @AGENTS.md as plain text on its own line.
AGENTS.md, with notes
The file below is for an invented sample project, a small recipe-sharing web app. Replace each fact with your own. The notes after each block say why it is there.
# Recipe Box
Recipe sharing web app. TypeScript, Node 22, Postgres, React front end.
## Commands
- Install: `npm ci`
- Dev server: `npm run dev` (port 3000)
- Tests: `npm test` (run a single file with `npm test -- path/to/file.test.ts`)
- Lint and types: `npm run lint && npm run typecheck`
Why: Commands are the highest-value lines. An agent cannot guess that tests need npm test -- for one file. Only list commands you have run.
## Layout
- `src/api/`: HTTP handlers, one file per route
- `src/db/`: queries and migrations; never write SQL outside this folder
- `src/generated/`: produced by `npm run codegen`, do not edit by hand
Why: A map of three or four folders beats a full tree. State prohibitions as facts with a reason (“produced by codegen”) so the agent can apply them to cases you did not list.
## Conventions
- Use named exports. No default exports.
- New API routes need a test that covers the error path.
- Dates are ISO 8601 strings in UTC everywhere in storage and JSON.
Why: Only rules that differ from common defaults. “Write clean code” adds nothing; “no default exports” changes behavior. Keep them checkable.
## Do not
- Do not run `npm run db:reset`: it drops the local database.
- Do not commit `.env` or anything under `secrets/`.
Why: Short list of actions with a cost. This is guidance, not enforcement. An instruction file is context the model may follow; if a mistake would be expensive, enforce it with a hook (see Claude Code hooks: recipes we ran) or with permission rules.
## Pull requests
- Branch from `main`, one change per PR, describe what you ran to verify it.
Why: Process the agent would otherwise guess at. Skip this section if you have no preference.
The whole file is about 25 lines. Size targets from the docs: Claude Code recommends under 200 lines per file; Codex reads up to 32 KiB of instructions by default (documented, not tested). If you outgrow that, split by directory with nested AGENTS.md files or, for Claude Code, path-scoped files in .claude/rules/.
What other tools read (documented, not tested)
We did not run these tools. Treat this table as a summary of their documentation as checked on 2026-10-29 (the Codex page and agents.md could not be reached from the test sandbox on 2026-10-30), and recheck before relying on it.
| Tool | Reads AGENTS.md | Reads CLAUDE.md | Source |
|---|---|---|---|
| Codex | Yes: AGENTS.override.md first, then AGENTS.md, one file per directory from the repository root down to the working directory, 32 KiB by default | Only if you list it as a fallback filename | Codex AGENTS.md guide |
| GitHub Copilot | Yes, anywhere in the repository; the nearest file wins | A single CLAUDE.md at the repository root | Copilot repository instructions |
| Cursor | Yes, at the root and in subdirectories | Not mentioned on its rules page | Cursor rules |
| Claude Code | Yes, with the conditions in the table above | Yes | Memory documentation, tested above |
The practical effect: an AGENTS.md reaches all four tools. A CLAUDE.md that only imports it adds nothing for Codex and Cursor, so keep real content in AGENTS.md.
Mistakes we hit or avoided
- Assuming
AGENTS.mdloads next toCLAUDE.md. In our test it did not. Without an import or the setting, the content ofAGENTS.mdnever reached Claude. - A personal
CLAUDE.local.mdthat silently turnsAGENTS.mdoff. Confirmed in our test; the import fixes it. - Putting maintainer notes where they cost context. Block HTML comments in
CLAUDE.mdare stripped before injection, so use them for notes to humans. We confirmed that a token inside one was not seen by the model. - Believing the 200-line number is a limit. It is a recommendation. The file loaded in full.
- Trusting a model’s own report as a measurement. The hook log gave a second witness for
CLAUDE.mdfiles but not forAGENTS.md, and a model can report what it sees wrong. We label the AGENTS rows as model-reported.
What we did not test
- Codex, Copilot, Cursor and any tool other than Claude Code.
- Whether any instruction in a file is actually followed. We tested loading, not adherence.
- Interactive sessions,
/context, and the/configpanel. - Managed policy files, user-level
~/.claude/CLAUDE.md,--add-dirand themanaged-onlysetting. - Repeat runs of each layout. Each ran once.
Keeping this page honest
Claude Code changed how it reads AGENTS.md within a month of this writing, and the other tools’ pages move too. The results above are for Claude Code 2.1.314 on 2026-10-30. Rerun evidence/claude-md-agents-md/matrix.sh after any release that mentions AGENTS.md, CLAUDE.md, rules or Project instructions.