AGENTS.md: One Instruction File for Codex, Cursor, and Claude Code

Coding agents keep project instructions in the repository under different names: CLAUDE.md for Claude Code, .cursor/rules for Cursor, .github/copilot-instructions.md for Copilot, GEMINI.md for Gemini CLI. AGENTS.md folds them into one file. It’s an open format: plain Markdown in the repository root with build and test commands, code conventions, and constraints. The specification at agents.md calls it a “README for agents”, and the Agentic AI Foundation under the Linux Foundation stewards the format.

As of November 2026, Codex, Cursor, and GitHub Copilot read AGENTS.md, and Claude Code reads it from version 2.1.277 if the project has no CLAUDE.md. Each tool reads it differently, though. Some concatenate every file in the tree, others take the nearest one. Codex caps the whole chain at 32 KiB. Claude Code silently switches to CLAUDE.md if one sits next to AGENTS.md.

This guide covers who reads AGENTS.md and how, how to combine it with CLAUDE.md on a team that runs several agents, what belongs in the shared file, and which traps show up in practice. Claude Code behavior was tested on version 2.1.318; everything else is described from the documentation as of November 6, 2026. CLAUDE.md levels and their load order have their own CLAUDE.md guide.

What is AGENTS.md

Origin and stewardship

The format started with OpenAI Codex and quickly spread to other tools. In December 2025 the Linux Foundation launched the Agentic AI Foundation, and AGENTS.md (from OpenAI) joined it together with Anthropic’s MCP and Block’s goose (SD Times, InfoQ). The agents.md site says the format is used by over 60,000 open-source projects, and that the main OpenAI repository had 88 AGENTS.md files when the page was written.

The most important fact about the format: it has no schema. Asked about required fields, the specification answers “No. AGENTS.md is just standard Markdown.” The format requires no frontmatter and no reserved headings, and it has no mechanism for conditional rules. Anything beyond “read this text” is up to each tool.

The specification gives only two precedence rules. If the tree has several AGENTS.md files, the one closest to the edited file wins. An explicit user prompt in chat overrides any file.

What to put in it

The specification suggests five sections: project overview, build and test commands, code style, testing, and security. A minimal working file fits in about fifteen lines:

# AGENTS.md

## Commands
- Install: `pnpm install`
- Tests: `pnpm test` (before every commit)
- Linter: `pnpm lint --fix`

## Conventions
- TypeScript strict, no `any`
- API handlers live in `src/api/handlers/`

## Constraints
- Don't add dependencies without approval
- Don't commit `.env*` files or secrets

A full team template is in the section “AGENTS.md template and a thin CLAUDE.md”.

Who reads AGENTS.md: the tool matrix

The table is built from each tool’s primary documentation, checked on November 6, 2026. Behavior changes from release to release, so recheck your tool against the link in the last column before you roll anything out.

The supported-tools list on agents.md also names Jules, Devin, Windsurf, Junie, Zed, Warp, Factory, goose, opencode, Amp, RooCode, Kilo Code, Augment Code, and others. We didn’t check their own documentation for this article. A separate caveat about Gemini CLI: in May 2026 Google announced a move to Antigravity CLI. Since June 18, 2026, Gemini CLI no longer serves free users or Google AI Pro and Ultra subscribers; access remains for Gemini Code Assist Standard and Enterprise licenses and through paid API keys. We didn’t check whether Antigravity CLI itself reads AGENTS.md.

Codex: the file chain and the 32 KiB limit

Codex rebuilds its instructions on every run. First comes the global level in ~/.codex (or CODEX_HOME): it takes AGENTS.override.md, or AGENTS.md if there’s no override, and uses the first non-empty one. Then the project level: Codex walks from the project root (usually the Git root) down to the current directory and takes at most one file per directory, in the order AGENTS.override.md → AGENTS.md → names from project_doc_fallback_filenames.

The files don’t replace each other. Codex concatenates them from the root down, separated by blank lines. Files closer to the working directory come last, so they win when instructions conflict. Empty files are skipped.

Once the combined size reaches project_doc_max_bytes (32 KiB by default), Codex stops adding files. The docs suggest either raising the limit or splitting instructions across nested directories.

Fallback names go in ~/.codex/config.toml:

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

You can ask Codex itself what it sees, from the repository root: codex --ask-for-approval never "Summarize the current instructions.". For a subdirectory, add --cd subdir.

Cursor: AGENTS.md or .cursor/rules

Cursor supports both mechanisms, and they solve different problems. AGENTS.md is plain Markdown with no metadata, and Cursor’s docs position it for simple use cases. Files in subdirectories merge with their parents, and more specific instructions take precedence.

Rules in .cursor/rules live in .mdc files with a three-field frontmatter: description, globs, alwaysApply. These fields set the rule type: Always Apply (every session), Apply Intelligently (the agent decides from the description), Apply to Specific Files (by path pattern), and Apply Manually (by @-mention). Older versions of the docs called the middle two Agent Requested and Auto Attached. The rules system ignores a plain .md file in .cursor/rules without frontmatter.

On top of project rules there are User Rules (global for the user) and Team Rules (Team and Enterprise plans). In a conflict, the order is Team → Project → User. The current docs page says nothing about the legacy .cursorrules, so you can’t draw conclusions about its status from it.

GitHub Copilot: copilot-instructions.md, applyTo, and AGENTS.md

Copilot has three kinds of repository instructions. .github/copilot-instructions.md applies to the whole repository. Files named .github/instructions/NAME.instructions.md with an applyTo key (a glob) apply to a subset of paths; only the cloud agent and code review support them, and an excludeAgent key ("code-review" or "cloud-agent") hides the file from one of the two. The third kind is agent instructions: one or more AGENTS.md files anywhere in the repository, where the nearest one wins, or a single CLAUDE.md or GEMINI.md in the root.

The support table shows who reads agent instructions: the cloud agent (on GitHub.com and from the IDE), code review, Copilot CLI, and Copilot Chat in VS Code. Per the table, Copilot Chat in JetBrains, Visual Studio, Eclipse, and Xcode doesn’t support agent instructions. If your team uses Chat outside VS Code, you still need copilot-instructions.md.

Personal Copilot instructions take precedence over repository ones, and repository instructions over organization ones; all relevant sets go into the request.

Claude Code: what changed and how it picks a file

Before version 2.1.277, Claude Code read only CLAUDE.md, and AGENTS.md needed workarounds. Now a built-in plugin reads AGENTS.md directly, with one condition. By default (claude-md-or-agents-md), it does so only if none of three files exists in the working directory or above: CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md. The user-level ~/.claude/CLAUDE.md, the organization’s managed CLAUDE.md, and .claude/rules/ don’t count for this check and load alongside AGENTS.md.

Tested: November 6, 2026, Claude Code 2.1.318, temporary folders with a unique marker phrase in each file. In all four cases the model named markers only from the files listed in the table, and /context all showed the same files under Memory files. The @AGENTS.md import didn’t create a duplicate: each file appeared in the list once.

Per the docs, AGENTS.md read directly differs from CLAUDE.md in three more ways. InstructionsLoaded hooks don’t fire for it (they do fire for an AGENTS.md pulled in by import or symlink). AGENTS.md from directories added with --add-dir doesn’t load. And Claude Code doesn’t read AGENTS.local.md, AGENTS.override.md, or anything under .agents/. If you keep a Codex-specific AGENTS.override.md, Claude Code won’t see it.

How to combine AGENTS.md with CLAUDE.md

There are four options, and none of them is right for everyone. The choice depends on whether anyone on the team uses Windows, whether you need Claude Code-only instructions, and whether the shared text fits within the Codex limit.

Option 1: AGENTS.md only

The repository has no CLAUDE.md, and Claude Code reads AGENTS.md on its own. This fits when the instructions really are shared and there’s nothing Claude-specific (hooks, skills, plan mode), or when that part lives in .claude/rules/ and .claude/settings.json.

The main trap here is CLAUDE.local.md. It’s a personal, uncommitted file, and it looks like it only adds instructions. In fact it counts as a CLAUDE.md, and Claude Code stops reading AGENTS.md. In a live test, a model with AGENTS.md and CLAUDE.local.md in the same folder saw only the marker from CLAUDE.local.md. There’s no error message. The agent just works without the project instructions.

The second limitation is about versions. Sessions on Claude Code before 2.1.277 don’t see AGENTS.md. Before 2.1.281, some sessions on recent versions didn’t see it either, for example on Amazon Bedrock or with telemetry disabled. Sometimes the first session right after upgrading from 2.1.276 or earlier doesn’t read it.

Option 2: CLAUDE.md with @AGENTS.md

This is the option to pick by default. AGENTS.md is the source of truth for every agent, and CLAUDE.md stays a thin wrapper: the import on the first line, and below it whatever applies only to Claude Code.

@AGENTS.md

## Claude Code
- Changes in `src/billing/`: plan mode only
- Before committing, run the `pre-push` skill

Claude Code reads the imported file first, then the rest of CLAUDE.md. The setup works in sessions where native AGENTS.md reading isn’t available and with any Project instructions value, and it never puts a duplicate into context. The docs state that “keeping the import never makes Claude read AGENTS.md twice”, and the live test confirms it. There’s one downside: if someone adds shared rules to CLAUDE.md, other agents won’t see them. Only code review catches that.

Option 3: symlink

ln -s AGENTS.md CLAUDE.md

There’s one set of contents, and everyone reads it. The Claude Code docs list two limitations. First, the Edit and Write tools don’t write through a symlink, and Claude redirects the edit to the target file, AGENTS.md.

Second, Windows. Creating a symlink needs administrator rights or Developer Mode, and Git without core.symlinks checks out a committed link as a regular text file. A developer on Windows ends up with a one-line CLAUDE.md that contains the text AGENTS.md instead of instructions.

The reverse setup also exists: AGENTS.md -> CLAUDE.md. In the author’s workspace (about 15 projects, with Claude Code and Codex used in parallel), most projects work this way: they started with Claude Code, and CLAUDE.md stayed the source of truth. The link direction decides which file is the real one, and that matters in two places. You edit the target, not the link. And every agent sees whatever is in the target: with AGENTS.md -> CLAUDE.md, Codex also gets the Claude-specific instructions about hooks and skills, which it doesn’t have.

Option 4: two files of different length

Sometimes the shared text genuinely doesn’t fit within the Codex limit. An example from the same workspace: in a product monorepo, CLAUDE.md is about 708 lines and 41,415 bytes, while AGENTS.md is about 128 lines and 10 KB. The long file wouldn’t fit in the default Codex limit (32,768 bytes). The docs don’t say what Codex does with a single file over the limit; they only describe stopping once the total accumulates. We didn’t test that case.

The short Codex version holds only the operational minimum: response language, conservative changes, prohibitions (deleting files, new dependencies, long-running processes, secrets), the verification order, and a pointer saying “details are in docs/, not here”. The split is deliberate: the short file has its own job and doesn’t try to summarize the long one.

The cost of this option is two files you have to keep in sync by hand. It only works if the short file really is short and rarely changes.

Decision table

“Yes” in a cell means the option works under that condition.

claude-md-and-agents-md mode and checking with /context all

If you need both CLAUDE.md and AGENTS.md and don’t want an import, you can switch Claude Code to read both files. In an interactive session: /config → Project instructions → claude-md-and-agents-md. In a settings file:

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

Claude Code reads this setting only from ~/.claude/settings.json, from a file passed with --settings, and from managed settings. It ignores the setting in a project .claude/settings.json and in settings.local.json, so you can’t commit it to the repository for the whole team. Before v2.1.285 the plugin was called agents-md@builtin; from 2.1.285 both IDs work. The other values are claude-md (CLAUDE.md only) and managed-only (only the organization’s managed instructions).

Tested: November 6, 2026, Claude Code 2.1.318, setting passed with --settings. With a CLAUDE.md without the import, the model saw markers from both files; with CLAUDE.local.md, also markers from both. The mode fixes both the common “CLAUDE.md next to AGENTS.md” case and the CLAUDE.local.md trap.

The fastest way to check what loaded is /context all at the start of a session. The Memory files section lists instruction files with their level (Project, Local, User) and token count. The command also works non-interactively: claude -p "/context all". If the list shows only CLAUDE.local.md where you expected AGENTS.md, you’ve found the cause.

Nested AGENTS.md files and monorepos

The specification recommends a separate AGENTS.md in each monorepo package. The general rule is that the nearest file wins, but the mechanics differ by tool:

• Codex concatenates the whole chain from the root to the current directory, and nested files spend the shared 32 KiB budget. Splitting by package helps only if the root file is short, because it lands in every chain.
• Cursor merges a nested file with its parents, and the more specific one wins a conflict.
• Copilot takes the nearest file in the tree.
• Claude Code reads AGENTS.md from the working directory and every directory above it at startup, and it loads a subdirectory’s AGENTS.md when it opens a file from that subdirectory and there’s no CLAUDE.md there. We didn’t cover nested files in the live test; this is the documented behavior.

Splitting makes sense when packages really do have different commands and conventions: a frontend on pnpm and Vitest, a backend in Go, a separate infrastructure package. If a nested file repeats the root one with a couple of differences, a single line in the root file is better: “in packages/api, run tests with go test ./...”.

What goes in the shared file, and what doesn’t

Agents with different capabilities read a shared AGENTS.md, so it should contain only what holds for any of them:

• build, test, and lint commands;
• code and structure conventions that the code itself doesn’t reveal;
• prohibitions: secrets, new dependencies, deleting files, manual deploys;
• the verification steps before a commit;
• links to docs/ and ADRs instead of retelling them.

Tool-specific material goes into that tool’s file. Claude Code hooks, skills, plan mode, subagents, and MCP servers belong in CLAUDE.md or .claude/.

Codex-specific material goes into AGENTS.override.md or the global ~/.codex/AGENTS.md. A line like “run the pre-push skill” in the shared file sends Codex looking for something it doesn’t have. Hard rules that must never be broken are better moved out of text and into mechanisms: Claude Code has hooks for that. To the model, an instruction in any of these files is only context, and it doesn’t guarantee execution.

AGENTS.md doesn’t share personal rules. It’s a project file: Claude Code keeps global preferences in ~/.claude/CLAUDE.md, Codex in ~/.codex/AGENTS.md, and you’ll have to sync them separately.

On content, there’s empirical data. In a study by ETH Zurich and LogicStar.ai (arXiv 2602.11988, v3, September 29, 2026), agents ran on SWE-bench tasks and on a set of issues from repositories where developers had committed their own context files. The authors’ conclusion: such files don’t generally improve the share of solved tasks, and inference cost rises by more than 20% on average. Agents follow instructions well, but repository overviews don’t help. The files pay off where they describe a project’s non-standard practices.

The practical takeaway: write what’s non-obvious and verifiable in AGENTS.md. The agent will read the directory structure itself, so there’s no point retelling it. Every line in the file costs context in every session; the context engineering guide explains why that cost matters.

AGENTS.md template and a thin CLAUDE.md

A template for a repository that several agents work in. Replace the commands and paths with your own.

## Project
Monorepo: `apps/web` (Next.js), `apps/api` (Go), `packages/ui`.
Architecture is in `docs/architecture.md`, decisions in `docs/adr/`.

## Commands
- Install: `pnpm install`
- All tests: `pnpm test`; one package: `pnpm --filter <pkg> test`
- API: `cd apps/api && go test ./...`
- Lint and format: `pnpm lint --fix`

## Conventions
- TypeScript strict, no `any`; API errors go through `ApiError`
- New endpoints ship with a test in `apps/api/internal/.../*_test.go`
- DB migrations only as new files; never edit existing ones

## Constraints
- Don't add dependencies without approval in the PR
- Don't commit `.env*`, keys, or tokens
- Don't delete files or large blocks of code unless asked
- Don't start long-running processes (dev servers, watchers)

## Before committing
1. `pnpm lint` and `pnpm test` pass
2. The PR describes the change: what and why

And a thin CLAUDE.md next to it:

@AGENTS.md

## Claude Code only
- Changes in `apps/api/internal/billing/`: use plan mode
- Before pushing, run the `pre-push` skill

Together, both parts fit in a few kilobytes: far below the Codex limit and below the recommended 200 lines for CLAUDE.md. What else to put in the Claude part is covered in the CLAUDE.md guide.

Migrating an existing setup

From CLAUDE.md. Move the shared parts into AGENTS.md, and leave @AGENTS.md and the Claude-specific parts in CLAUDE.md. If nothing is Claude-specific, you can delete CLAUDE.md, and a recent Claude Code will read AGENTS.md on its own. People used to handle this by generating AGENTS.md from CLAUDE.md with external tools like AgentSync, excluding the Claude-specific sections. For rules, native AGENTS.md reading mostly removes that need; syncing MCP configs across agents is still a separate job.

From .cursor/rules. Always Apply rules move into AGENTS.md. Rules tied to file patterns stay in .mdc files or become a nested AGENTS.md in the matching directory. Apply Intelligently rules have no AGENTS.md equivalent.

From .github/copilot-instructions.md. Move the shared text into AGENTS.md. Keep copilot-instructions.md itself if your team uses Copilot Chat outside VS Code: AGENTS.md isn’t read there.

With Claude Code’s own tools. When /init generates CLAUDE.md, it takes .cursor/rules, .cursorrules, and .github/copilot-instructions.md into account; with the CLAUDE_CODE_NEW_INIT=1 variable, also AGENTS.md, .devin/rules/, .windsurf/rules/, and .clinerules. /import copies another agent’s configuration, including AGENTS.md, into CLAUDE.md once. Either way you get a copy of the text: if AGENTS.md stays in the repository, replace the copied text with @AGENTS.md. Don’t keep the generated file as is. /init writes a project overview, and the ETH data suggests such overviews don’t help agents.

Old workarounds. The Claude Code docs cover four common ones:

Common mistakes

Two copies edited independently. The classic drift scenario. In one of the author’s projects, CLAUDE.md and AGENTS.md started as identical copies; over time they diverged in several paragraphs, and now nobody can tell which version is correct. Agents in the same repository get different rules.

Find-and-replace on names. Someone makes a copy for another agent by replacing Claude with Codex. Paths change along with the name: the line ~/.claude/team-rules.md becomes ~/.Codex/team-rules.md, which doesn’t exist. The failure is silent: the agent just doesn’t find the file.

Claude-specific content in the shared file. For other agents, mentions of Claude Code skills, hooks, subagents, and MCP servers in AGENTS.md turn into instructions they can’t follow. At best that wastes context; at worst the agent spends steps hunting for things that don’t exist. It happens especially easily with an AGENTS.md -> CLAUDE.md setup.

A symlink on a team with Windows users. Part of the team gets a one-line file instead of instructions. It’s easy to miss: the agent works as usual, just without the project rules.

CLAUDE.local.md in a project built on AGENTS.md. A personal file silently turns off reading of the shared one. The fix is an @AGENTS.md import in CLAUDE.local.md or the claude-md-and-agents-md mode in user settings.

A stale file. An AGENTS.md with commands that no longer work is worse than no file at all, because agents follow instructions diligently. Change the file in the same PR as the build commands and check it in review.

How the agents themselves differ is covered in the Claude Code vs Codex comparison. Where rule files fit into a team workflow is in the vibe coding guide, and general Claude Code setup is in the complete Claude Code guide.

Where to start

1. Run /context all in Claude Code and see which instruction files actually load right now.
2. Find every instruction file in the repository: CLAUDE.md, CLAUDE.local.md, AGENTS.md, .cursor/rules, .github/copilot-instructions.md. If some are copies, pick one as the source of truth.
3. Move the shared parts into AGENTS.md, and keep the Claude-specific parts in CLAUDE.md under the @AGENTS.md line.
4. Check the size: run wc -c on every AGENTS.md in the chain from the root to the deepest package. The total should stay well below 32 KiB.
5. Check with each agent: /context all in Claude Code, codex ... "Summarize the current instructions." in Codex, and /memory show in Gemini CLI if it still works for you.