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.

By

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 reportedResult
AGENTS.md onlyAGENTS tokenRead natively
CLAUDE.md onlyCLAUDE tokenRead
CLAUDE.md and AGENTS.md, no importCLAUDE token onlyAGENTS.md ignored
CLAUDE.md containing @AGENTS.md, plus AGENTS.mdBoth tokensImported (hook log: include)
CLAUDE.local.md and AGENTS.mdLOCAL token onlyAGENTS.md ignored
Same, with Project instructions set to claude-md-and-agents-mdBoth tokensBoth read
.claude/CLAUDE.md and AGENTS.mdDOTCLAUDE token onlyAGENTS.md ignored
AGENTS.md in a parent directory, session started in sub/AGENTS tokenRead from above
Root and sub/AGENTS.md, nothing read from sub/Root token onlySubdirectory file not loaded yet
Same, after Claude read sub/note.txtRoot and sub tokensSubdirectory file loaded on demand
Root CLAUDE.md and sub/AGENTS.md, after reading sub/note.txtCLAUDE token onlysub/AGENTS.md ignored
CLAUDE.md with 400 lines, canary on line 400Token reportedNo truncation at 200 lines
CLAUDE.md with a canary inside <!-- ... -->Only the visible tokenBlock comments stripped
.claude/rules/r.md alongside CLAUDE.mdCLAUDE and RULE tokensRules 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.md files the model’s report is the only witness. Claude Code emitted InstructionsLoaded events for CLAUDE.md, CLAUDE.local.md and rules files, but none for AGENTS.md in any run, so we could not cross-check those with the hook log.
  • The setting row used a --settings file with pluginConfigs / 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 /config panel 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.

ToolReads AGENTS.mdReads CLAUDE.mdSource
CodexYes: AGENTS.override.md first, then AGENTS.md, one file per directory from the repository root down to the working directory, 32 KiB by defaultOnly if you list it as a fallback filenameCodex AGENTS.md guide
GitHub CopilotYes, anywhere in the repository; the nearest file winsA single CLAUDE.md at the repository rootCopilot repository instructions
CursorYes, at the root and in subdirectoriesNot mentioned on its rules pageCursor rules
Claude CodeYes, with the conditions in the table aboveYesMemory 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.md loads next to CLAUDE.md. In our test it did not. Without an import or the setting, the content of AGENTS.md never reached Claude.
  • A personal CLAUDE.local.md that silently turns AGENTS.md off. Confirmed in our test; the import fixes it.
  • Putting maintainer notes where they cost context. Block HTML comments in CLAUDE.md are 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.md files but not for AGENTS.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 /config panel.
  • Managed policy files, user-level ~/.claude/CLAUDE.md, --add-dir and the managed-only setting.
  • 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.