Which instruction file should each tool use?
Choose the file by the tool that must read it, not by the wording you prefer. The official AGENTS.md project describes an open format used across a growing coding-agent ecosystem, while each product still documents its own discovery behavior. Codex documents AGENTS.md for repository instructions. Claude Code documents CLAUDE.md as project memory. GitHub documents .github/copilot-instructions.md as the broad repository-wide Copilot instructions file. Cursor documents project rules under .cursor/rules/*.mdc.
A repository can keep the same policy language synchronized across those files, but no single filename is the universal reader for all four tools. Treat each file as a small adapter for the surface that actually loads it.
Copilot compatibility varies by surface
GitHub's support matrix lists CLAUDE.md for selected cloud-agent surfaces and Copilot CLI, while many Copilot Chat and code-review surfaces do not list it. That makes CLAUDE.md a surface-specific Copilot input, not a safe universal Copilot baseline.
Use the dedicated Copilot surface matrix linked on this page for the exact environment-by-environment answer. For broad repository coverage, keep .github/copilot-instructions.md for Copilot and CLAUDE.md for Claude Code.
CLAUDE.md vs AGENTS.md: What Is the Difference?
AGENTS.md is a simple open Markdown format for coding-agent instructions and is the documented repository instruction file for Codex, including directory-scoped guidance and precedence. The official AGENTS.md project says the format is used by more than 60,000 open-source projects and is stewarded by the Agentic AI Foundation under the Linux Foundation. CLAUDE.md is the documented project memory file for Claude Code.
Use AGENTS.md as a shared baseline only for tools and surfaces that document loading it. Use CLAUDE.md for Claude Code memory, workflows, and project context; when appropriate, a short CLAUDE.md can import @AGENTS.md. Keep shared facts synchronized, but do not assume every tool implements the same discovery order, nesting, or precedence.
What Do Public AGENTS.md and CLAUDE.md Files Commonly Miss?
KyenAI's July 19 GitHub snapshot analyzed 100 readable best-match AGENTS.md files and 100 readable best-match CLAUDE.md files. The detector found no explicit security or approval rule in 68% of the AGENTS.md sample and 62% of the CLAUDE.md sample. It found no verification or completion criteria in 53% and 58%, respectively. These percentages describe the non-random samples, not all repositories.
A separate June 2026 preprint analyzed 100 popular repositories and cataloged six instruction-file configuration smells. It reported lint leakage in 62% of files, context bloat in 42%, and skill leakage in 35%. The study uses different sampling and definitions from KyenAI's dataset, so treat the results as complementary warnings rather than numbers to combine.
Does Cursor Support AGENTS.md?
Yes. Cursor documents a root-level AGENTS.md as a simple project-wide alternative to .cursor/rules, and Cursor CLI documents reading both root AGENTS.md and CLAUDE.md alongside Cursor project rules. This support is surface-specific: the cited IDE page limits AGENTS.md to the project root, while the CLI page explicitly names both root files.
Use .cursor/rules/*.mdc when you need metadata, path scoping, or several focused rules. Use root AGENTS.md when one readable shared policy is enough, and reuse root CLAUDE.md in Cursor CLI only when that cross-tool policy is intentional.
CLAUDE.md vs copilot-instructions.md
CLAUDE.md is the Claude Code project memory file. .github/copilot-instructions.md is the broad repository-level instruction file for GitHub Copilot. They may contain similar setup commands and review rules, but they are not interchangeable because the supported surfaces differ.
Use CLAUDE.md when the intended reader is Claude Code. Use .github/copilot-instructions.md when the intended reader is Copilot across supported repository workflows. If a Copilot cloud-agent surface also reads CLAUDE.md, treat that as an exception to verify, not the general Copilot baseline.
How Do Nested AGENTS.md Files Work?
Use nested AGENTS.md files only when a folder genuinely needs different guidance: package-specific test commands, generated-file boundaries, ownership rules, or risk limits. Keep the root file for shared repo policy and the nested file for local exceptions.
A good nested file should be shorter than the root. It should say what changes inside that directory: commands, forbidden files, local completion standards, and when to ask for approval. Avoid duplicating the whole root policy because duplicated policy drifts quickly.
Can One Repository Use All Four Instruction Files?
Yes. A serious AI coding repository can use AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, and .cursor/rules/*.mdc at the same time. The reason to do this is not duplication for its own sake; it is compatibility across tools that load different filenames.
Keep the shared policy short and stable: setup commands, test commands, architecture boundaries, secrets policy, review expectations, and loop stop rules. Then keep each tool adapter concise so maintainers can update all affected files in one reviewed change.
Which File Should Be the Canonical Source?
The canonical source is the place maintainers agree to edit first; it is not necessarily the file every tool reads. Small teams often make AGENTS.md the canonical human-maintained policy because Codex uses it directly and it maps well to nested repository scope. Claude-heavy teams may choose CLAUDE.md instead.
Whichever source you choose, mark the other files as synchronized adapters and review drift. A stale adapter is worse than no adapter because it gives one agent outdated commands while another agent follows the current rule.
Compatibility is a surface policy
Do not reduce compatibility to a single yes-or-no claim per vendor. OpenAI documents AGENTS.md discovery and nested precedence for Codex. Anthropic documents CLAUDE.md memory and scoped project guidance for Claude Code. GitHub publishes a support matrix because instruction-file support differs across Copilot surfaces. Cursor documents project rules, a root AGENTS.md alternative, and extra root-file support in Cursor CLI.
For Copilot specifically, GitHub's matrix lists CLAUDE.md for selected cloud-agent surfaces and Copilot CLI, but not for many Chat and code-review surfaces. A repository that needs broad Copilot coverage should therefore maintain .github/copilot-instructions.md even when CLAUDE.md is also present.
One shared policy, small tool adapters
Choose one maintained policy source for facts that must agree everywhere: setup commands, verification, security boundaries, repository architecture, and review expectations. Then keep AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, and Cursor rules as concise adapters that carry the shared policy into each tool's documented format and scope.
A canonical source does not mean every tool reads that file. It means maintainers know where authoritative wording lives and update adapters in the same change. Never rely on links alone unless the target agent can actually open them.
Migrate the legacy .cursorrules file safely
For maintained Cursor guidance, move rules toward the currently documented .cursor/rules/*.mdc format. Split a large .cursorrules file into focused rules, add descriptions and globs where scope matters, compare behavior, and remove the old file only after repository testing.
Cursor's current rules documentation labels .cursorrules as legacy and deprecated while stating that it remains supported. Preserve it during comparison if an existing workflow still depends on it, then remove it after the maintained .cursor/rules version passes repository checks.
Test the same task in the same repository
Compare tools only with the same repository state, task prompt, allowed tools, instruction files, verification command, and success criteria. Record tool and model versions so the result can be interpreted later.
Report success, elapsed time, measured cost, and human interventions only when they were actually measured. Use Not measured for unavailable values, preserve failed runs, and document limitations instead of filling gaps with estimates or invented benchmark results.
Recommended play
- Inventory the agent surfaces the repository actually uses, then map each surface to the publisher's current support record.
- Maintain one canonical shared policy and generate or review concise adapters for AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, and .cursor/rules/*.mdc.
- Use .github/copilot-instructions.md as the broad Copilot repository baseline; treat CLAUDE.md support as surface-specific.
- Run a controlled same-task, same-repository comparison and publish only measured success, time, cost, and human-intervention values.
Current instruction-file decision table
Choose files by documented reader, scope, and surface. Shared wording may be synchronized, but file discovery remains tool-specific.
| Area | Current documented use | Scope or surface caveat | Recommended policy |
|---|---|---|---|
| AGENTS.md | Open cross-agent instruction format; Codex repository instructions; root project instructions in Cursor IDE and CLI | Support is tool- and surface-specific; Codex supports nested precedence while cited Cursor support is root-level and does not inherit Codex nesting behavior | Use it as a shared policy only where the reader documents support, and keep thin tool-specific adapters where behavior differs |
| CLAUDE.md | Claude Code project memory and instructions | Copilot support exists on selected cloud-agent surfaces and Copilot CLI, not broadly across Chat and code review | Keep it for Claude Code; also use .github/copilot-instructions.md when broad Copilot coverage matters |
| .github/copilot-instructions.md | Repository-wide GitHub Copilot instructions | Broadly supported across Copilot surfaces; path-specific files are separate | Use as the Copilot baseline and add .github/instructions/*.instructions.md only for scoped guidance |
| .cursor/rules/*.mdc | Current documented Cursor project rules | Metadata can make rules always-on, file-matched, requested, or manual | Split guidance into focused rules with explicit descriptions and globs |
| .cursorrules | Legacy Cursor repository instruction file that remains supported | Cursor documents it as deprecated in favor of Project Rules | Test migration to .cursor/rules/*.mdc before removing the legacy file |
Execution steps
Inventory files and surfaces
List AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .github/instructions/*.instructions.md, .cursorrules, and .cursor/rules/*.mdc, then record the exact agent surfaces expected to read each file.
Define the canonical shared policy
Choose the maintained source for setup, architecture, security, edit boundaries, tests, and review rules. Mark generated or manually synchronized adapters so maintainers know which wording is authoritative.
Create documented adapters
Place Codex guidance in AGENTS.md, Claude Code guidance in CLAUDE.md, broad Copilot guidance in .github/copilot-instructions.md, and current Cursor guidance in focused .cursor/rules/*.mdc files.
Migrate Cursor rules safely
Translate the deprecated .cursorrules file into scoped .mdc rules, preserve it during comparison, and remove it only after observed behavior and repository checks support the change.
Run a controlled comparison
Use the same clean repository state, task, prompt, permissions, and verification criteria for every tool. Record versions and mark unavailable success, elapsed time, cost, or human-intervention data as Not measured.
Common pitfalls
Saying Copilot reads or ignores CLAUDE.md everywhere
Check the GitHub support matrix by surface and use .github/copilot-instructions.md for broad repository-wide compatibility.
Deleting .cursorrules without a migration check
Cursor still supports the deprecated legacy file. Migrate toward .cursor/rules/*.mdc and verify behavior before removal.
Copying a shared policy until adapters drift
Name the canonical source, keep adapters narrow, and update all affected files in the same reviewed change.
Publishing zeros or estimates as benchmark data
Use measured values only. Display Not measured when success, time, cost, human interventions, or changed-file counts were not captured.
Implementation checklist
- List every agent surface, not just each vendor name.
- Verify support against current publisher documentation.
- Use .github/copilot-instructions.md for broad Copilot repository coverage.
- Keep one canonical shared policy and identify every adapter.
- Put current Cursor project rules in .cursor/rules/*.mdc.
- Treat .cursorrules as supported legacy input and verify its .cursor/rules replacement before removal.
- Run the same task against the same repository state and criteria.
- Publish only measured success, elapsed time, cost, and human interventions.
Questions this guide answers
Which file should you use: CLAUDE.md, Copilot Instructions, or AGENTS.md?
Use AGENTS.md as an open shared policy only for agents and surfaces that document support, including Codex. Use CLAUDE.md for Claude Code; it can import @AGENTS.md when you want one maintained baseline. Use .github/copilot-instructions.md for broad GitHub Copilot repository guidance and .cursor/rules/*.mdc for scoped Cursor project rules. No filename has identical discovery behavior across every tool.
Does Cursor support AGENTS.md and CLAUDE.md?
Cursor documents root AGENTS.md as a simple project-wide alternative to .cursor/rules. Cursor CLI also documents loading root AGENTS.md and CLAUDE.md alongside Cursor rules. Use .cursor/rules when you need metadata or path scoping, and do not assume Codex or Claude Code nesting behavior carries over.
Is AGENTS.md an open standard?
AGENTS.md is a simple open Markdown format for coding-agent instructions. The official project says it is used by more than 60,000 open-source projects and is stewarded by the Agentic AI Foundation under the Linux Foundation. Tool support still varies by product and surface, so verify the target agent's discovery and precedence rules.
Can one repository use AGENTS.md, CLAUDE.md, Copilot instructions, and Cursor rules together?
Yes. Keep one short shared policy for setup commands, verification, security boundaries, and review expectations, then maintain concise tool-specific adapters. Update all affected files in the same reviewed change so adapters do not drift.