AGENTS.md and CLAUDE.md for coding agents

Every coding agent starts each session knowing nothing about your repository. An instruction file is how you tell it, once, the things it cannot work out by reading the code: the commands that build and test the project, the conventions reviewers enforce, the directories that are generated, and the mistakes it will otherwise make. Two names dominate: AGENTS.md, an open format that many agents read, and CLAUDE.md, the file Claude Code reads.

This article covers which agents read which file, how to keep one source of truth across tools, what belongs in the file and what does not, how to check that an agent loaded it when the agent seems to ignore it, and why the rules you most need followed should not live in the file at all. It reflects each tool's documentation as it stood on 25 October 2026.

Recent changes

• Claude Code reads AGENTS.md itself. From version 2.1.277 (18 September 2026), a repository with only an AGENTS.md works in Claude Code without a CLAUDE.md, and a new Project instructions setting decides what loads when a repository has both.
• Claude Code can audit your instruction files. /doctor prompt-audit, added in version 2.1.283 (25 September 2026), reports instructions written for older models, references to files or commands that no longer exist, and files that contradict each other.
• Subdirectory instructions load more often. Claude Code now loads a subdirectory's CLAUDE.md when it writes or edits a file there (version 2.1.288, 2 October 2026), or reads one with a single-file shell command such as cat (version 2.1.293, 7 October 2026), not only when it opens a file with its Read tool.
• Codex ignores AGENTS.md in projects you have not trusted. Since version 0.150.0 (26 August 2026), an untrusted project supplies no project-level instructions.
• Claude Code cuts oversized subdirectory files. From version 2.1.309 (22 October 2026), a CLAUDE.md that loads on demand, such as one in a subdirectory, and runs past the per-file limit loads only its opening part, with a note telling Claude to read the rest.

What the files are

AGENTS.md is plain Markdown with no required fields, described by its maintainers as a README for agents. It is stewarded by the Agentic AI Foundation under the Linux Foundation. OpenAI Codex, Cursor, GitHub Copilot's cloud agent, code review and CLI, and a long list of other agents read it. Google's Gemini CLI is the main exception: it reads GEMINI.md unless you set its context.fileName to AGENTS.md. Antigravity CLI, which replaced Gemini CLI for unpaid-tier and Google One users on 18 June 2026, reads both AGENTS.md and GEMINI.md.

CLAUDE.md is Claude Code's equivalent. Claude Code loads it at the start of every session from several places: a project file (./CLAUDE.md or ./.claude/CLAUDE.md) shared with the team through version control, a personal file in ~/.claude/, a CLAUDE.local.md for your own notes on one project, which you add to .gitignore yourself, and an organisation-wide managed file. Files in subdirectories load when Claude works with files there. Larger projects can also split instructions into topic files under .claude/rules/, and give a file a paths list so that it loads only when Claude works on matching files.

One file for every agent

Many teams use more than one agent, and nobody wants to maintain the same instructions twice. The two files now interact like this.

• Claude Code reads AGENTS.md on its own from version 2.1.277, but by default only when the working directory and the directories above it contain no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md. If one of those exists, it reads the CLAUDE.md files instead.
• The Project instructions setting changes that default. In /config it is set to claude-md-or-agents-md. Choose claude-md-and-agents-md to load both kinds of file, each directory's CLAUDE.md first and its AGENTS.md after; claude-md for CLAUDE.md alone; or managed-only to load only your organisation's managed CLAUDE.md and auto memory when a session starts.
• CLAUDE.md can still import AGENTS.md. A line containing @AGENTS.md pulls the file in, imports can nest up to four hops deep, and Claude Code never loads an imported AGENTS.md twice, whatever the setting.
• Cursor and Copilot read both names. Cursor reads a CLAUDE.md in the project root the same way it reads AGENTS.md, and Copilot's cloud agent and CLI read AGENTS.md, CLAUDE.md or GEMINI.md.

So the reliable pattern for a mixed team is still an AGENTS.md with the real content and a CLAUDE.md that imports it, plus anything that genuinely applies only to Claude Code. It works in every Claude Code version and in every setting except managed-only, which leaves project files out, and it covers the sessions that cannot read AGENTS.md directly, such as some first sessions after an upgrade. If your CLAUDE.md would hold nothing but the import and everyone runs version 2.1.277 or later, you can delete it. Stride's own repository keeps the one line:

@AGENTS.md

Codex, Cursor and Copilot then read AGENTS.md natively, and Claude Code reads the same content through the import.

Gemini CLI needs a setting instead of a file. To have it read AGENTS.md as well as GEMINI.md, add this to .gemini/settings.json in the repository root; Antigravity CLI reads AGENTS.md without it:

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

Three older set-ups need attention now. A CLAUDE.md that asks Claude in words to read AGENTS.md only works when Claude decides to open the file, so replace the sentence with the @AGENTS.md import. A SessionStart hook that prints AGENTS.md now adds a second copy to the context, so remove it. And a CLAUDE.local.md counts as a CLAUDE.md: adding one to a project that relies on Claude reading AGENTS.md directly stops Claude from reading it, unless you switch the setting to claude-md-and-agents-md.

Most projects that have both files already join them, but not all. In our census of the 7,370 most-starred active repositories on GitHub, 1,013 have both files. In 74.1% of them the two are joined by an import, a symlink or a copy; in the other 25.9%, Claude Code reads a separate CLAUDE.md and, at its default setting, does not load the AGENTS.md written for every other agent.

How agents combine nested files

In a monorepo, one instruction file at the root is rarely enough; the web app and the data pipeline have different commands and different rules. Agents that follow the AGENTS.md convention read the file nearest to the code they are editing, so a file in apps/web/ refines the root file for everything under it. The agents.md guidance is explicit that the closest file wins, and that an explicit instruction in the chat overrides every file.

Codex documents its version of this precisely. It reads a global file from its home directory, then walks from the project root down to the current directory, taking at most one file per directory: AGENTS.override.md if there is one, otherwise AGENTS.md, otherwise a name you have listed in project_doc_fallback_filenames. Other names are ignored, so Codex reads a CLAUDE.md only if you list it. It joins the files root first, so the closest file comes last and wins, and by default it stops adding files once the combined instructions reach 32 KiB, a practical ceiling worth knowing when your root file grows.

Claude Code loads the CLAUDE.md files above the working directory when a session starts, and those in subdirectories as Claude works there. Cursor combines a nested AGENTS.md with the files in the directories above it.

What belongs in the file

Anthropic's guidance for CLAUDE.md applies to any agent's instruction file. For each line, ask whether removing it would make the agent make mistakes; if not, cut it. That test keeps:

• Commands the agent cannot guess: how to install, build, run a single test, run the whole suite, lint and type-check, with any flags your setup needs.
• Conventions that differ from the defaults: naming, error handling, where new files go, which library to use for what.
• Repository etiquette: branch names, commit message format, what a pull request description must contain.
• Architecture decisions that constrain everyday changes, such as "every read filters out soft-deleted rows" or "server routes return data, not translated text".
• Gotchas: generated directories not to edit, environment variables that must be set, the test that needs a running database.

And it cuts what the agent can work out itself: standard language conventions, file-by-file descriptions of the codebase, long tutorials, and anything that changes often. Anthropic suggests keeping each CLAUDE.md under about 200 lines, because longer files take more context and are followed less reliably, and moving instructions that matter for one part of the codebase into path-scoped rules.

A skeleton that covers most repositories:

# Project name
 
## Commands
- Install: `pnpm install`
- Run one test file: `pnpm test path/to/file.test.ts`
- Before any commit: `pnpm lint && pnpm typecheck && pnpm test`
 
## Conventions
- Server routes return structured data; the client formats it.
- New UI strings go in the message catalogue, never inline.
 
## Rules that are easy to break
- Every database read filters out soft-deleted rows.
- Never edit files under `src/generated/`; run `pnpm codegen` instead.
 
## Pull requests
- One story per pull request, with the commands you ran and their output.

What does not belong in the file

• The work itself. Stories, acceptance criteria and priorities change daily and belong in your tracker. An instruction file that lists this sprint's tasks is stale by Wednesday. Give the agent access to the backlog instead; see backlog access for coding agents over MCP.
• Secrets. The file is committed and read into a model's context. Credentials belong in the environment, and the agent should be told where they come from, not what they are.
• Rules that must never be broken. See the next section.

When an agent ignores the file

Most reports of an agent ignoring AGENTS.md or CLAUDE.md have one of two causes: the file never loaded, or it loaded and lost out to something else. Check which before rewriting anything.

Check that the file loaded

• Claude Code: run /context. Its memory files list shows each CLAUDE.md and CLAUDE.local.md loaded when the session started, and a file that is not listed is a file Claude cannot see. Subdirectory files load later, when Claude works there, and print a Loaded line with their path when they do. A session that reads AGENTS.md directly prints a line saying it loaded the file, and /memory lists it. A notice that an instruction file was not loaded means the file exists but was withheld: by a Read deny rule, by permissions.blockReadsOutsideWorkingDirectories, or because a link to it could not be resolved.
• Codex: from the repository root, run codex --ask-for-approval never "Summarize the current instructions.", and Codex should repeat its global guidance, then the project's, in order. Add --cd with a subdirectory to check a nested file, or run codex debug prompt-input to print the exact input the model receives. Codex builds the instruction chain once per run, so restart it after editing a file, and if it follows the wrong guidance, look for an AGENTS.override.md higher up the tree.
• GitHub Copilot: Copilot Chat lists .github/copilot-instructions.md under a response's references when it used your repository instructions, and the Copilot CLI's /instructions command lists the files it found and lets you switch each one on or off.
• Gemini CLI: /memory show prints the combined instructions, and /memory reload reads the files again.
• Cursor documents no view of which rules applied to a chat. Check that each rule's type matches how it should load (a rule that applies intelligently needs a description, one for specific files needs a pattern that matches them), and remember that rules apply to Agent chats, not to Tab completions.

Why a loaded file is still ignored

• It is too long. Anthropic suggests keeping each CLAUDE.md under about 200 lines, and says that a rule Claude keeps breaking usually means the file is too long. Cursor suggests keeping rules under 500 lines, and GitHub suggests keeping a Copilot instruction file to about 1,000.
• It was cut off. Claude Code skips a CLAUDE.md larger than 4 MiB, and since version 2.1.309 it loads only the opening part of a file that loads on demand, such as a subdirectory CLAUDE.md, past a per-file limit: 40,000 characters for a model with a 200K-token context window. Codex stops adding instruction files once they reach 32 KiB by default.
• Two instructions conflict. Claude Code joins its instruction files rather than letting one override another, and when two contradict each other it may follow either. Under the AGENTS.md convention, the file nearest the code wins, and an instruction in the chat overrides every file.
• It is vague. Write instructions that can be checked, such as "use 2-space indentation" rather than "format code properly". If the agent asks questions the file already answers, the wording is ambiguous.
• It fell out of context. After /compact, Claude Code reads the project-root CLAUDE.md again from disk, but subdirectory files and path-scoped rules come back only when Claude next works in their directory, and instructions you gave only in the chat are summarised away. Put anything that must survive in the root file, and run /clear between unrelated tasks.

For one instruction that Claude keeps skipping, Anthropic suggests marking that line alone with "IMPORTANT"; emphasise many lines and none stands out. Beyond that, the fix is the one in the next section.

Instructions are advice; enforce what matters elsewhere

An instruction file is context, not configuration. Claude Code's documentation says so directly: CLAUDE.md is advisory, and to block an action regardless of what the agent decides you use a hook, which runs deterministically. The same is true of every agent's instruction file. The more a rule matters, the less it should depend on being read, remembered and obeyed.

Our own AGENTS.md shows the trade-off. It runs to about 2,500 lines, far past Anthropic's suggested size, because it records the checklists our codebase depends on, organised by task ("When you add a new API route", "When you add a new MCP tool") so that an agent can find the section for the change it is making. That works for guidance. It does not work for invariants: the rules we most need kept, such as that a count stated on the website matches the data behind it, live in tests that fail the build, not in paragraphs an agent might not reach.

The practical rule: if breaking an instruction would ship a bug, turn it into a test, a lint rule or a hook, and keep a one-line pointer to it in the file.

Keep the file true

A wrong instruction is worse than none, because an agent follows it with confidence. Instruction files drift like any documentation: a command gets renamed, a directory moves, a rule is relaxed and nobody edits the paragraph.

• Review the file when an agent makes the same mistake twice. Either the rule is missing, or it is buried or ambiguous.
• Change it in the same pull request as the code it describes.
• Ask agents to check claims in the file against the code when the two disagree, and to report the disagreement rather than pick one silently.
• Audit it now and then. In Claude Code, /doctor prompt-audit reads your CLAUDE.md, CLAUDE.local.md and AGENTS.md files and your rules, and lists stale references and contradictions with proposed edits.

Sources

Documentation and release notes, checked on 25 October 2026:

• AGENTS.md: the format, its stewardship and its guidance on nested files and conflicts.
• Claude Code memory documentation: where CLAUDE.md loads from, AGENTS.md support and the Project instructions setting, imports, rules, the prompt audit, size limits and troubleshooting.
• Claude Code best practices: keeping CLAUDE.md short, emphasis for a rule Claude keeps skipping, and clearing context between tasks.
• Claude Code context window: what survives /compact.
• Claude Code errors: the notice for an instruction file that was not loaded.
• Claude Code changelog: the versions and dates above.
• Codex AGENTS.md guide: discovery order, overrides, fallback names, the 32 KiB default and how to verify what loaded. The untrusted-project change is in the Codex 0.150.0 release notes, and codex debug prompt-input in the Codex command reference.
• Cursor rules help and Cursor rules documentation: AGENTS.md, nested AGENTS.md and CLAUDE.md support, rule types and rule length.
• GitHub Copilot custom instructions support: which files each Copilot surface reads; repository instructions and the Copilot CLI's instructions: how to check which files were used; customizing code review: instruction file length.
• Gemini CLI: GEMINI.md: the default file name, the context.fileName setting, /memory and the move to Antigravity CLI; Gemini CLI configuration: where the project settings file lives; moving from Gemini CLI to Antigravity CLI.