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, and why the rules you most need followed should not live in the file at all.

What the files are

AGENTS.md is plain Markdown with no required fields, described by its maintainers as a README for agents. It is now stewarded by the Agentic AI Foundation under the Linux Foundation. OpenAI Codex, Cursor, GitHub Copilot's cloud agent and code review, and a long list of other agents read it.

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 git-ignored CLAUDE.local.md for your own project notes, and an organisation-wide managed file. Files in subdirectories load when Claude works with files there.

One file for every agent

Many teams use more than one agent, and nobody wants to maintain the same instructions twice. The two files interact in a specific way.

• Claude Code reads AGENTS.md directly in recent versions, but only when the working directory and the directories above it contain no CLAUDE.md or CLAUDE.local.md. If both kinds of file exist, it reads the CLAUDE.md files by default.
• CLAUDE.md can import AGENTS.md. A line containing @AGENTS.md pulls the file in, and imports can nest up to four levels deep.

So the reliable pattern for a mixed team is an AGENTS.md with the real content and a CLAUDE.md that imports it, plus anything that genuinely applies only to Claude Code. Stride's own repository does exactly this: its CLAUDE.md is a single line.

@AGENTS.md

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

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 and joining them root first, so the closest file comes last and wins. By default it stops at 32 KiB of combined instructions, a practical ceiling worth knowing when your root file grows.

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.

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.

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.