AGENTS.md and CLAUDE.md: One Context File for Every Agent

The moment you run more than one vendor’s agent on a repository, a small problem appears: they don’t all read the same file. Codex reads AGENTS.md. Claude Code reads CLAUDE.md. Gemini CLI reads GEMINI.md unless you tell it otherwise. Copilot CLI reads several of them at once.

The obvious response — write the instructions once per tool — is the wrong one. Three files drift, and you end up debugging why one agent keeps using the wrong test command while another doesn’t.

The setup that holds up: AGENTS.md as the single source of truth, and a thin per-tool file that points at it. This guide covers what each agent actually reads today, how to wire that up, what belongs in the file, and what changes when several agents run in parallel worktrees. For the wider workflow around two vendors on one repository, see using Claude Code and Codex together.

What each agent actually reads

Agent	Reads by default	Reads AGENTS.md?	Hierarchy	Size guidance
Codex	AGENTS.md, AGENTS.override.md	Natively	~/.codex/ then git root down to cwd	32 KiB combined cap (project_doc_max_bytes)
Claude Code	CLAUDE.md, CLAUDE.local.md, .claude/rules/	No — import or symlink it	Managed policy, user, project, local; root down to cwd	Target under 200 lines; files over 4 MiB are skipped
Gemini CLI	GEMINI.md	Only if you add it to context.fileName	~/.gemini/, workspace, and just-in-time as files are read	Not documented as a hard cap
Copilot CLI	.github/copilot-instructions.md, AGENTS.md, CLAUDE.md, GEMINI.md	Natively	User-level and repository-level	Not documented as a hard cap

Three things are worth pulling out of that table.

AGENTS.md now has institutional backing, not just adoption. It is stewarded by the Agentic AI Foundation under the Linux Foundation, came out of collaboration between OpenAI, Google, Cursor, Factory, Amp and others, and is read by a long list of tools including Codex, Copilot, Cursor, Jules, Aider, Zed, and VS Code. If you are standardizing on one filename, that is the argument for this one.

Claude Code is the notable holdout, and it says so explicitly. Anthropic’s memory documentation — the source for every Claude Code behavior described below — states that Claude Code reads CLAUDE.md, not AGENTS.md, and recommends importing one from the other rather than duplicating.

Copilot CLI reads everything and ranks nothing. GitHub’s documentation says it de-duplicates identical copies of user-level, repository-wide, and agent instruction files, but “does not define a general precedence order between these files.” If your AGENTS.md and CLAUDE.md disagree, Copilot CLI has no rule for which wins. That alone is a good argument for making sure they never disagree.

The setup: one file, three pointers

Write the real content in AGENTS.md at the repository root. Then wire each tool to it.

Claude Code

Create a CLAUDE.md whose first line imports AGENTS.md, and put Claude-specific instructions underneath:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Claude Code expands @path imports at session start, up to four hops deep, and appends the rest of the file after the imported content. If you have nothing Claude-specific to add, a symlink works too:

ln -s AGENTS.md CLAUDE.md

Use the import rather than the symlink on Windows, where creating symlinks needs Administrator rights or Developer Mode. Either way, run /context in a session and check that CLAUDE.md appears under Memory files — that is the difference between “the file exists” and “the agent read it.”

Codex

Nothing to do. Codex reads AGENTS.md natively, walking from ~/.codex/AGENTS.md through the git root down to your current directory, concatenating what it finds with files closer to the working directory appearing last. It stops adding files once the combined size hits project_doc_max_bytes, 32 KiB by default — the tightest limit of any agent here, and the one your file should be sized against.

Codex also supports AGENTS.override.md, which takes precedence over AGENTS.md in the same directory. OpenAI’s own example commits one — a nested services/payments/AGENTS.override.md that swaps in a team-specific test command. The global ~/.codex/AGENTS.override.md is the one meant as a temporary personal override.

Gemini CLI

Add AGENTS.md to the context filename list in .gemini/settings.json:

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

Listing both means an existing GEMINI.md keeps working while AGENTS.md becomes the shared file.

Copilot CLI

Nothing to do — it already reads AGENTS.md. Given the lack of a defined precedence order, the thing to avoid is a CLAUDE.md that contains a copy of AGENTS.md rather than an import of it. An import leaves one authoritative copy on disk; a copy leaves two files that will drift apart.

One wrinkle specific to Copilot CLI: it reads AGENTS.md and CLAUDE.md, and it also expands @ references inside them. The recommended setup therefore probably puts your instructions into its context twice, since its de-duplication covers identical files rather than a file and an expansion of it. Duplicated identical guidance is wasted context rather than a correctness problem — but it is a reason to keep the file short, and a reason not to also paste the content into .github/copilot-instructions.md.

What belongs in the file

The file is a briefing for someone competent who has never seen the repository. Useful content:

• Build, test, and lint commands, written as exact invocations. npm test runs the build and the suite, not just the suite — that kind of detail.
• Conventions that differ from the language’s defaults. Nobody needs to be told to write tests; they need to be told your tests live next to the source and end in .test.mjs.
• Layout facts that aren’t obvious, especially where generated code lives and what regenerates it.
• Non-obvious pitfalls. The migration that must run before the seed script. The one directory that is vendored and must not be reformatted.
• What not to touch, and why.

What to leave out:

• Anything derivable from the code. Directory listings and dependency inventories consume context every session to tell the agent something it can read in two seconds. Recent Claude Code versions will actively propose trimming these when you run /doctor.
• Task-specific requirements. Those belong in the prompt — see the AI coding agent prompt template for the shape.
• Multi-step procedures used occasionally. Those are better as a skill or a path-scoped rule that loads on demand.

Keep it short. Anthropic’s guidance is under 200 lines per file, and Codex’s 32 KiB default cap is shared across every AGENTS.md in the walk — raise it with project_doc_max_bytes if you must, but the limit is a hint about the right size, not an obstacle. Long files cost context on every session, and both vendors tie length to how reliably instructions get followed.

Nested files for monorepos

Every agent here supports per-directory instruction files, and Codex, Claude Code, and Gemini CLI resolve them the same way: walk from the repository root down toward the working directory, concatenate what you find, and let the file closest to the work have the last word. Copilot CLI is again the exception — it combines what it finds and documents no ordering at all.

repo/
├── AGENTS.md              # shared: language, commit format, review rules
├── CLAUDE.md              # @AGENTS.md + Claude-specific notes
├── services/api/
│   └── AGENTS.md          # how to run and test just the API
└── apps/web/
    └── AGENTS.md          # component conventions, build commands

Two mechanism-specific notes. Claude Code loads root-and-above files at launch but discovers subdirectory files on demand, when it reads files in those directories — so a nested file that has not been triggered yet is not in context. And in large monorepos where other teams’ files get picked up, claudeMdExcludes skips specific paths by glob.

For rules that should only apply to certain files, Claude Code’s .claude/rules/ directory supports paths: frontmatter:

---
paths:
  - "src/api/**/*.ts"
---

# API rules

- Validate all input at the handler boundary
- Use the standard error response shape

That content only enters context when the agent touches a matching file, which is the right home for instructions that would otherwise bloat a shared AGENTS.md.

It is guidance, not enforcement

This matters enough to state plainly: instruction files shape behavior, they do not constrain it. Anthropic’s documentation is explicit that CLAUDE.md content “is delivered as a user message after the system prompt” and that there is “no guarantee of strict compliance.”

So anything that must hold regardless of what the agent decides belongs somewhere else:

You want	Put it in
”Prefer this style”	AGENTS.md
”Never run this command”	Permission deny rules
”Always run this before committing”	A hook
”Cannot write outside this directory”	The sandbox
”Cannot land without review”	Branch protection

Writing “never commit directly to main” in AGENTS.md is a reasonable reminder and a poor control. The permissions and sandboxing guide covers which of these layers actually enforce anything.

What changes when agents run in parallel

Most AGENTS.md advice assumes one agent in one checkout. Running several agents across isolated worktrees adds four wrinkles that are easy to trip over.

Each worktree carries the instruction file from whatever commit it branched from. AGENTS.md is a tracked file, so a worktree created before you fixed a wrong test command still contains the wrong test command. Agents started earlier keep using it. When you change shared instructions, land the change on the base branch and create new worktrees from there.

Editing AGENTS.md inside a task branch is a shared-contract change. If two agents both revise it, you get a conflict in the one file every agent reads. Treat it like a schema or a type definition: change it first, alone, merge it, then fan out — the contract-first pattern applies to instructions as much as to code.

Gitignored personal files do not follow you into new worktrees by default. A CLAUDE.local.md exists only in the worktree where you created it. Claude Code’s .worktreeinclude can copy ignored files into new worktrees, and orchestrators may symlink them — see running multiple Claude Code agents in parallel for that mechanism. Anthropic’s suggested fix for exactly this case is to keep personal instructions in your home directory and import them:

# Individual Preferences
- @~/.claude/my-project-instructions.md

Note that an import in a project file resolving outside the working directory triggers an approval dialog the first time Claude Code sees it.

Claude Code’s auto memory is shared across worktrees, unlike the files. Its storage path is derived from the git repository, so every worktree of the same repo shares one auto memory directory. A correction you give an agent in one worktree can therefore surface in another — a genuinely useful default, and a surprising one if you assumed worktrees isolate everything.

Keeping the file honest

The maintenance rule that works: add to it when an agent makes the same mistake twice. That is the signal that the information is missing from the repository’s shared context rather than from one prompt.

The corollary is to delete as readily as you add. Instructions that describe code that has since changed are worse than no instructions, because agents follow them. Conflicting rules across nested files are worse still — Anthropic’s documentation notes that when two files disagree, “Claude may pick one arbitrarily.”

A quick periodic check: does every line still describe the current repository, and would a competent new contributor need it? If not, cut it.

Where Parallel Code fits

Disclosure: Parallel Code is our product. Everything above is standard agent configuration and works the same regardless of how you launch the agents.

Parallel Code runs Claude Code, Codex, Gemini CLI, Copilot CLI, and Antigravity CLI side by side, each task in its own worktree — which is exactly the setup where four vendors reading four different files becomes a daily annoyance rather than a curiosity. A single AGENTS.md with per-tool pointers means every agent you dispatch starts from the same conventions, whichever one picks up the task.

The worktree caveats above apply directly: land instruction changes on the base branch before creating the tasks that should follow them.

Frequently asked questions

Does Claude Code read AGENTS.md?

Not on its own. Anthropic’s documentation states that Claude Code reads CLAUDE.md, not AGENTS.md, and recommends creating a CLAUDE.md that imports it with @AGENTS.md on the first line, or symlinking one to the other. Recent versions also offer /import, which copies a supported agent’s configuration — including AGENTS.md — into the matching CLAUDE.md as a one-time operation.

Should I use AGENTS.md or CLAUDE.md?

Use AGENTS.md for the content and CLAUDE.md as a thin pointer to it. AGENTS.md is read by the widest range of tools and is now stewarded under the Linux Foundation; CLAUDE.md gives you Claude-specific features like .claude/rules/ and claudeMdExcludes. You do not have to choose — the import gives you both.

Will Copilot CLI read my instructions twice if I have both files?

It de-duplicates identical copies but defines no precedence between different files. If CLAUDE.md imports AGENTS.md rather than copying it, there is one authoritative copy of the content on disk and no conflicting guidance to rank.

How long should AGENTS.md be?

Short. Anthropic suggests targeting under 200 lines, and Codex caps the combined instruction content it loads at 32 KiB by default. Both are really pointing at the same thing: the file is loaded into context on every session, and Anthropic ties longer files to weaker adherence.

Do I need a separate AGENTS.md in each worktree?

No — it is a tracked file, so every worktree gets a copy automatically when it is created. The thing to watch is that each copy reflects the commit the worktree branched from, so instruction changes need to land on the base branch before the worktrees that should follow them are created.

Can AGENTS.md stop an agent from doing something?

No. It is context, not configuration, and no agent guarantees compliance with it. Use permission rules, hooks, sandboxes, and branch protection for anything that must hold.

Start with the file you already have

If a repository already has a CLAUDE.md that works, the migration is mechanical: rename it to AGENTS.md, create a CLAUDE.md containing @AGENTS.md, add AGENTS.md to Gemini CLI’s context.fileName, and stop there. Codex and Copilot CLI pick it up without configuration.

What that buys you is not a better file — it is the same file, read by every agent you run. In a single-agent workflow that is tidiness. Once several agents are working the same repository at once, it is the difference between one set of conventions and four.