September 15, 2026 · Comparison · EN

Coding-Agent Context Files in 2026: AGENTS.md vs CLAUDE.md

Compare AGENTS.md, CLAUDE.md, Cursor Rules, Copilot instructions, GEMINI.md, Aider, and OpenCode by discovery, precedence, scope, and portability.

Coding-Agent Context Files in 2026: AGENTS.md vs CLAUDE.md

The key answer: use a root AGENTS.md as the repository’s shared instruction contract, then add only the smallest adapters required by tools that do not load it by default. In September 2026, Codex, OpenCode, modern Cursor, and supported GitHub Copilot agent surfaces can discover AGENTS.md natively. Claude Code requires a CLAUDE.md bridge such as @AGENTS.md; Gemini CLI requires context.fileName configuration if you want AGENTS.md discovered as a context filename; and Aider requires the file to be passed with --read or configured under read:.

That recommendation is a portability pattern, not a claim that every coding agent implements one universal standard. Discovery, scope, precedence, and even product-surface support differ. Treat the file name as routing and the file contents as documentation—not as an enforcement boundary.

Support matrix: native, configurable, bridge, or manual-load

Definitions used in this table:

• Native — the tool documents automatic discovery under that file name without repository-specific setup.
• Configurable — automatic discovery works only after a committed or user-level setting changes the recognized filename.
• Bridge — a native vendor file imports or points the tool to the canonical contract.
• Manual-load — the operator must pass or explicitly load the file; a config file may make that repeatable.
• Fallback — recognized only when the tool’s preferred file is absent.
• Legacy — still documented for compatibility, but not the recommended format for new repositories.

The matrix deliberately avoids “works everywhere.” GitHub Copilot is a family of surfaces, Cursor has both plain agent instructions and metadata-bearing project rules, and local configuration can change Gemini, Aider, and Codex behavior.

The accurate 2026 behavior, tool by tool

Claude Code: CLAUDE.md is native; AGENTS.md needs a bridge

Anthropic’s Claude Code memory documentation is explicit: Claude Code reads CLAUDE.md, not AGENTS.md. If the shared repository contract lives in AGENTS.md, create this thin adapter:

@AGENTS.md

## Claude Code only
- Use plan mode before changing the billing subsystem.

The import avoids copying the shared rules. A symlink from CLAUDE.md to AGENTS.md can also work when no Claude-only text is needed, but an import is usually clearer and is friendlier to Windows contributors.

Claude Code can load CLAUDE.md from multiple levels and supports file imports. Scope therefore depends on where the active memory file lives, not merely on the presence of one root file. Use /context in a fresh session to inspect loaded memory files.

Do not describe /init or /import as continuous synchronization. They can help generate or migrate Claude configuration, but the durable no-duplication pattern is a checked-in CLAUDE.md that imports the canonical file.

For the complete setup surface beyond context files, see How to Prepare Your Repository for Claude Code.

OpenAI Codex: native root-to-CWD AGENTS.md discovery

OpenAI’s Codex AGENTS.md guide documents a precise instruction chain:

1. Codex checks its home directory for AGENTS.override.md, otherwise AGENTS.md.
2. At project scope it starts at the project root and walks down to the current working directory.
3. In each directory it checks AGENTS.override.md, then AGENTS.md, then configured fallback filenames.
4. It includes at most one instruction file per directory.
5. Files are concatenated root first; guidance nearer the working directory appears later and therefore overrides earlier guidance.

This means these are not synonyms:

repo/AGENTS.md
repo/services/payments/AGENTS.md
repo/services/payments/AGENTS.override.md

For a Codex session launched in repo/services/payments, the override file wins over the regular file at that directory. The root file still contributes earlier guidance. Codex also has size limits and optional fallback filenames, so do not assume every byte of an oversized instruction tree reaches the model.

For trusted project configuration, sandboxing, command rules, skills, MCP, and clean-session checks, see How to Prepare Your Repository for OpenAI Codex.

Cursor: project rules and nested AGENTS.md are current; .cursorrules is legacy

Cursor’s current Rules documentation describes two useful repository mechanisms:

• .cursor/rules/ contains version-controlled project rules. Metadata can control whether a rule always applies, is selected by relevance, matches file globs, or is invoked manually.
• AGENTS.md is a plain-Markdown alternative for straightforward agent instructions. Cursor supports it at the project root and in subdirectories, combining parent and nested guidance with more specific instructions taking precedence.

Use .cursor/rules/*.mdc when Cursor-specific metadata or activation modes are valuable:

---
description: "Frontend component and accessibility rules"
globs: "src/**/*.tsx"
alwaysApply: false
---

- Preserve keyboard navigation.
- Run the component accessibility tests.

Use AGENTS.md for the shared, tool-neutral contract. A repository may use both, but duplicated statements create two authorities that can drift.

Cursor’s own help calls root .cursorrules legacy and headed for deprecation. Existing repositories can migrate it, but new repositories should prefer .cursor/rules/ and/or nested AGENTS.md.

The dedicated AGENTS.md vs Cursor Rules guide covers activation modes, Cloud Agents, hooks, and legacy migration in more detail.

GitHub Copilot: three repository instruction shapes, with surface-specific support

GitHub documents three distinct repository mechanisms in its repository custom-instructions guide:

1. .github/copilot-instructions.md for repository-wide Copilot instructions.
2. .github/instructions/NAME.instructions.md (including nested paths below that directory) for path-specific rules using applyTo frontmatter.
3. AGENTS.md for agent instructions; when multiple exist, the nearest one in the directory tree takes precedence for supported agent workflows.

A path-specific file looks like this:

---
applyTo: "src/payments/**/*.ts"
---

- Run the payments contract suite after changing this path.
- Never log cardholder data.

Do not flatten all Copilot features into one behavior. GitHub maintains a custom-instructions support table because Copilot Chat, cloud agent, CLI, code review, and different IDE integrations do not necessarily recognize exactly the same files.

The safe wording is therefore: Copilot supports repository-wide and path-specific .github instructions, and documented Copilot agent surfaces support AGENTS.md; verify the exact surface your team uses.

Gemini CLI: GEMINI.md by default; AGENTS.md through configuration

Gemini CLI’s project-context documentation names GEMINI.md as the default context file. It loads context hierarchically and supports imports with @file.md syntax.

To make AGENTS.md a recognized context filename for the repository, commit .gemini/settings.json:

{
  "context": {
    "fileName": "AGENTS.md"
  }
}

The official docs also allow a list:

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

Use the list only when the files contain intentionally different material. If GEMINI.md imports AGENTS.md and context.fileName also loads both, the same contract can enter context twice.

The alternative adapter is:

# GEMINI.md

@./AGENTS.md

## Gemini CLI only
- Prefer the project sandbox profile for shell commands.

Workspace settings live at .gemini/settings.json, as documented in Gemini CLI settings. /memory show displays the assembled context, and /memory reload refreshes it after edits.

Aider: conventions are explicit read-only context, not magic filenames

Aider’s coding conventions guide uses CONVENTIONS.md as an example. The filename itself has no automatic meaning. Load a shared contract for one session with:

aider --read AGENTS.md

Or make it repeatable in .aider.conf.yml:

read: AGENTS.md

Multiple read-only files are also supported:

read:
  - AGENTS.md
  - docs/aider-notes.md

Aider searches several locations for .aider.conf.yml; its YAML configuration documentation says current-directory, Git-root, and home files can all participate, with later-loaded files taking priority. That config discovery does not make AGENTS.md native—it makes an explicit read: choice persistent.

Call this manual-load or configured support, not automatic AGENTS.md support. Also keep model selection, commit behavior, and other Aider runtime options in .aider.conf.yml; keep shared repository facts in the Markdown contract.

OpenCode: AGENTS.md is native; CLAUDE.md is fallback compatibility

OpenCode’s Rules documentation says it looks for project rules by traversing upward from the current directory. AGENTS.md is preferred. A project CLAUDE.md is used as a fallback only when no AGENTS.md exists in that category.

At user scope, ~/.config/opencode/AGENTS.md is preferred over the Claude-compatible fallback ~/.claude/CLAUDE.md. If both project AGENTS.md and CLAUDE.md exist, OpenCode uses AGENTS.md; it does not concatenate both merely because both are present.

CONVENTIONS.md is not OpenCode’s native repository rule file. If a repository has one, reference it from AGENTS.md or list it through OpenCode’s documented configuration rather than assuming filename discovery.

Precedence and discovery caveats that change the result

“Nearest wins” is not one universal algorithm

The phrase is a useful shorthand, but implementations differ:

• Codex builds a root-to-CWD chain and chooses at most one recognized file per directory.
• Cursor combines parent and nested AGENTS.md instructions for files under their scope.
• GitHub says the nearest AGENTS.md takes precedence for supported Copilot agent workflows.
• Gemini assembles hierarchical context and can discover additional context just in time.
• OpenCode searches upward and applies its own category/fallback precedence.
• Claude Code follows its CLAUDE.md memory hierarchy, not an AGENTS.md hierarchy.
• Aider reads exactly what its command line and merged configuration tell it to read.

Document these semantics in the repository if contributors launch tools from different subdirectories.

Starting directory matters

For tools that walk between a project root and the current directory, launching from repo/ can produce a different instruction set from launching in repo/services/payments/. A clean-session test should cover both locations when nested rules exist.

Product surface matters

“GitHub Copilot supports this” is incomplete without naming the surface. The IDE extension, cloud agent, CLI, and code review have overlapping but non-identical support. Use GitHub’s current support table rather than copying a blanket claim into your own docs.

Configuration can redefine the apparent standard

Gemini’s context.fileName, Codex fallback filenames, and Aider’s read: can make a local setup appear to support a filename natively. Record committed settings in the matrix and test on a clean machine or clean profile before calling the setup portable.

Context budgets still apply

Discovery does not guarantee unlimited inclusion. Keep the root contract short, link to canonical details, and place specialized guidance near its scope. Do not paste whole architecture manuals or style guides into every adapter.

Recommended repository: one contract, thin adapters

A practical cross-tool tree looks like this:

repo/
├── AGENTS.md                              # canonical shared contract
├── CLAUDE.md                              # @AGENTS.md + Claude-only notes
├── .aider.conf.yml                        # read: AGENTS.md
├── .gemini/
│   └── settings.json                      # context.fileName: AGENTS.md
├── .cursor/
│   └── rules/
│       └── frontend.mdc                   # only Cursor-specific scoped behavior
├── .github/
│   ├── copilot-instructions.md            # only Copilot-specific behavior
│   └── instructions/
│       └── payments.instructions.md       # Copilot-only path scope
├── services/
│   └── payments/
│       └── AGENTS.md                      # shared subsystem contract
└── docs/
    ├── architecture.md
    └── validation.md

The root contract should answer only durable, cross-tool questions:

# AGENTS.md

## Repository map
- `src/` contains product code.
- `tests/` mirrors production modules.
- `docs/architecture.md` is the architecture authority.

## Validation
- Fast check: `npm test`
- Full gate: `npm run verify`

## Change boundaries
- Do not edit generated files under `dist/`.
- Database migrations require explicit reviewer approval.

## Source-of-truth rules
- Update the schema before generated clients.
- Link to existing docs instead of duplicating them here.

Thin adapters should contain routing plus truly vendor-specific behavior. They should not paraphrase the shared contract.

A good CLAUDE.md imports AGENTS.md. A good .aider.conf.yml lists it under read:. A good Gemini workspace setting names it. Cursor and OpenCode need no adapter for the shared file. Copilot’s .github files should exist only for Copilot-specific or applyTo-scoped guidance that cannot be represented cleanly by nested shared files.

For a fuller contract template, use the AGENTS.md template. For the larger repository design around it, read What Is an Agent-Ready Repository? and Context Engineering for Coding Agents.

Migration plan: duplicated vendor files to one maintained contract

1. Inventory discovery and ownership

List every instruction-bearing file and the product surface that consumes it:

find . -name AGENTS.md -o -name AGENTS.override.md -o -name CLAUDE.md \
  -o -name GEMINI.md -o -name .cursorrules -o -path '*/.cursor/rules/*' \
  -o -name copilot-instructions.md -o -name '*.instructions.md' \
  -o -name .aider.conf.yml

Do not delete anything yet. Mark each statement as shared, tool-specific, path-specific, personal, obsolete, or enforceable policy.

2. Choose the canonical shared contract

Create or repair root AGENTS.md. Move only durable cross-tool facts into it: repository map, source-of-truth pointers, validation commands, boundaries, and escalation paths.

If two vendor files conflict, resolve the conflict with maintainers before migration. Combining contradictory text does not create a contract.

3. Move scoped shared rules closer to their code

Put subsystem guidance in nested AGENTS.md only where the consuming tools support the needed scope. For a mixed-tool team, verify each tool’s behavior; do not assume Codex, Cursor, and Copilot interpret the same tree identically.

4. Replace copies with adapters

• Claude Code: replace shared prose in CLAUDE.md with @AGENTS.md.
• Gemini CLI: commit .gemini/settings.json with context.fileName: "AGENTS.md", or import the contract from GEMINI.md—not both.
• Aider: configure read: AGENTS.md.
• Cursor: move Cursor-only glob and activation logic into .cursor/rules/; remove duplicated shared prose.
• Copilot: retain .github/copilot-instructions.md and *.instructions.md only for Copilot-specific scopes or behavior.
• OpenCode and Codex: let native AGENTS.md discovery work; add overrides only for genuine scope differences.

5. Retire legacy .cursorrules

Move reusable shared content to AGENTS.md. Convert Cursor-only scoped rules to .cursor/rules/*.mdc, preserving descriptions, globs, and activation behavior. Test before deleting the legacy file.

6. Add a drift check

A lightweight CI check can reject large copied blocks in adapters, but avoid pretending text similarity proves semantic equality. The stronger rule is ownership: shared claims are edited only in AGENTS.md; adapters contain imports, settings, and vendor-only clauses.

7. Verify in clean sessions

Do not trust the existing chat, because it may retain earlier instructions. Use the procedure below for every supported tool and launch directory.

Clean-session verification procedure

Use a temporary, harmless probe so the test proves discovery rather than model guesswork:

1. Add Context probe: CONTEXT_PROBE_20260915 to the applicable canonical or nested AGENTS.md.
2. Fully close the existing agent session.
3. Start the tool from the repository root.
4. Ask: What exact context probe is active, and which instruction file supplied it? Do not search the filesystem.
5. Repeat from one nested directory that has scoped instructions.
6. Inspect the tool’s context UI or command where one exists.
7. Remove the probe and start one final clean session to confirm it disappears.

Tool-specific checks:

For automated repository verification, also confirm adapters contain the expected routing:

rg -n '^@AGENTS\.md$' CLAUDE.md
rg -n '^read:\s*AGENTS\.md$|^-\s*AGENTS\.md$' .aider.conf.yml
rg -n '"fileName"\s*:\s*"AGENTS\.md"' .gemini/settings.json

Those checks prove file configuration, not model compliance. Keep the clean-session probe test as the behavioral check.

Instructions are guidance; policy needs enforcement

Context files influence model behavior. They do not create a security boundary, transactional guarantee, or compliance control.

Put these in instruction files:

• repository maps and source-of-truth pointers;
• build, test, lint, and type-check commands;
• coding and review conventions;
• generated-file warnings;
• approval and escalation expectations;
• explanations of why a boundary exists.

Enforce these elsewhere:

• formatting and style with formatters and linters;
• type rules with compilers and type checkers;
• required tests with CI and branch protection;
• forbidden paths with permissions, CODEOWNERS, sandboxing, or review gates;
• secrets with secret managers and scanners;
• deployment authority with environment protection and least-privilege credentials;
• schema and artifact consistency with deterministic generators and checks.

A sentence such as “never deploy without approval” helps the agent choose correctly. Removing production credentials and requiring an approved deployment job prevents the wrong action. Reliable repositories use both.

See Harness Engineering for Coding Agents for the operational layer around context files, including validation and safe handoff.

Decision checklist

Choose the smallest setup that accurately matches your tools:

• Codex + OpenCode only: root and, when needed, nested AGENTS.md.
• Add Claude Code: add CLAUDE.md with @AGENTS.md and only Claude-specific notes.
• Add Gemini CLI: configure .gemini/settings.json to recognize AGENTS.md, or maintain a GEMINI.md import bridge.
• Add Aider: configure read: AGENTS.md or launch with --read AGENTS.md.
• Add Cursor: use native AGENTS.md; add .cursor/rules/ only for Cursor-specific metadata or activation.
• Add Copilot: keep shared instructions in AGENTS.md, then add .github files where Copilot-specific repository or path scope is required.
• Migrating old Cursor repositories: convert .cursorrules; do not create new dependencies on it.

The open-source repository-harness project packages this one-contract approach with an AGENTS.md template, validation structure, architecture notes, and review boundaries. Star or fork the repository, then adapt the contract and thin adapters to your actual tool matrix.

FAQ

Should I use AGENTS.md or a vendor-specific file?

Use AGENTS.md for shared repository instructions when your tool set can consume it natively, through configuration, or through a thin bridge. Keep vendor-specific files only for required routing, product-specific settings, or scopes that the shared file cannot express.

Does Claude Code automatically read AGENTS.md?

No. Claude Code automatically reads CLAUDE.md. Put @AGENTS.md in CLAUDE.md to import a shared contract, or use a symlink when you need no Claude-specific additions.

Does Aider automatically read AGENTS.md or CONVENTIONS.md?

No. Aider treats CONVENTIONS.md as an example filename, not a magic file. Pass a conventions file with --read or list it under read: in .aider.conf.yml.

Which Cursor format should a new repository use?

Use version-controlled .cursor/rules/ for Cursor-specific scoped or metadata-driven rules, and use root or nested AGENTS.md for straightforward shared instructions. Root .cursorrules is legacy.

How does Codex resolve nested instruction files?

Codex reads from the project root down to the current working directory. At each directory it prefers AGENTS.override.md, then AGENTS.md, then configured fallback names, and includes at most one file per directory. More local guidance appears later in the combined instructions.

Can Gemini CLI use AGENTS.md without GEMINI.md?

Yes, after configuration. Set context.fileName to AGENTS.md in .gemini/settings.json. Without that setting, Gemini CLI’s default context filename is GEMINI.md.

Are context-file instructions enforceable security policy?

No. They are model guidance. Enforce critical rules with permissions, sandboxing, CI, branch protection, CODEOWNERS, secret management, and approval gates; use context files to explain the expected workflow.

Official documentation used

• Claude Code memory and CLAUDE.md
• OpenAI Codex custom instructions with AGENTS.md
• Cursor Rules and nested AGENTS.md
• GitHub Copilot repository custom instructions
• GitHub Copilot custom-instructions support table
• Gemini CLI project context
• Aider coding conventions
• Aider YAML configuration
• OpenCode Rules

Related

• How to Manage Multiple Coding Agents in One Repository
• How to Write an AGENTS.md That Actually Works
• AGENTS.md vs Cursor Rules
• AGENTS.md Template
• What Is an Agent-Ready Repository?