# AGENTS.md vs CLAUDE.md vs Copilot Instructions: Which File Should You Use?

Use this support matrix to decide whether CLAUDE.md, Copilot instructions, AGENTS.md, or Cursor rules should carry repository guidance for each tool surface.

## Quick Answer

AGENTS.md vs CLAUDE.md is a reader-support question, not a choice between interchangeable filenames. Use AGENTS.md for Codex and as an open shared policy for other documented readers; use CLAUDE.md for Claude Code, where it can import @AGENTS.md; use .github/copilot-instructions.md for broad GitHub Copilot repository guidance; and use .cursor/rules/*.mdc for current Cursor project rules. GitHub Copilot support for CLAUDE.md depends on the Copilot surface: selected cloud-agent surfaces and Copilot CLI support it, while many Copilot Chat and code-review surfaces do not. No single filename is a universal baseline across every agent surface.

## Best for

Developer tools teams, staff engineers, platform teams, and AI coding adopters.

## Use this guide to

Choose compatible instruction files, migrate Cursor rules carefully, and test AI coding tools without unsupported benchmark claims.

## Recommended play

1. Inventory the agent surfaces the repository actually uses, then map each surface to the publisher's current support record.
2. Maintain one canonical shared policy and generate or review concise adapters for AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, and .cursor/rules/*.mdc.
3. Use .github/copilot-instructions.md as the broad Copilot repository baseline; treat CLAUDE.md support as surface-specific.
4. 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

1. **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.
2. **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.
3. **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.
4. **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.
5. **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.

## FAQ

**Q: 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.

**Q: 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.

**Q: 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.

**Q: 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.

## Evidence sources

- [Use AGENTS.md with Codex](https://learn.chatgpt.com/docs/agent-configuration/agents-md) — OpenAI. Documents Codex instruction discovery, precedence, scope, and fallback filenames.
- [AGENTS.md open format and supported-agent ecosystem](https://agents.md/) — AGENTS.md. Describes the open format, supported-agent ecosystem, 60,000-plus open-source project usage statement, nested guidance, and AAIF stewardship.
- [Claude Code memory documentation](https://code.claude.com/docs/en/memory) — Anthropic. Documents CLAUDE.md loading, scoped project memory, imports such as @AGENTS.md, and symlink options.
- [GitHub Copilot custom instructions support matrix](https://docs.github.com/en/copilot/reference/custom-instructions-support) — GitHub. Lists instruction-file support by Copilot surface, including surface-specific CLAUDE.md support.
- [Adding custom instructions for GitHub Copilot](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions) — GitHub. Documents repository-wide and path-specific Copilot instruction files.
- [Cursor rules documentation](https://docs.cursor.com/context/rules-for-ai) — Cursor. Documents project rules, root AGENTS.md support, and the legacy/deprecated .cursorrules status.
- [Cursor CLI instruction-file support](https://docs.cursor.com/en/cli/using) — Cursor. Documents Cursor CLI loading root AGENTS.md and CLAUDE.md alongside .cursor/rules.
- [Configuration Smells in AGENTS.md Files](https://arxiv.org/abs/2606.15828) — arXiv. June 2026 preprint that catalogs six instruction-file configuration smells across 100 popular repositories and reports their observed prevalence.

## Related guides

- [Does GitHub Copilot read CLAUDE.md? support matrix](/guides/does-github-copilot-read-claude-md-support-matrix) — Readers with the Copilot-specific question should move to the narrow support matrix page instead of staying on the broad comparison.
- [AGENTS.md examples for Node.js, Python, and monorepos](/guides/agents-md-examples-codex-node-python-monorepos) — Readers who already chose AGENTS.md need concrete copyable examples for real repository shapes.
- [View the AGENTS.md template for monorepos](/guides/agents-md-template-for-ai-coding-agents) — Use the template to turn the shared policy into a concise Codex repository adapter.
- [AI coding agents comparison](/guides/ai-coding-agents-comparison) — Build a four-tool operating-model shortlist before choosing the repository instruction policy.
- [Codex vs Claude Code](/guides/codex-vs-claude-code) — Compare the tool workflows after instruction-file compatibility and scope are controlled.
- [Codex vs GitHub Copilot](/guides/codex-vs-github-copilot) — Compare current app, CLI, cloud-agent, model, permission, and governance surfaces after choosing the instruction policy.
- [Claude Code hooks and MCP setup](/guides/claude-code-hooks-mcp-setup) — Move deterministic automation into hooks or MCP after deciding what belongs in CLAUDE.md.
- [MCP security checklist](/guides/secure-mcp-servers-ai-coding-agents) — Instruction adapters should name safe tool boundaries before agents receive MCP access.
- [loop engineering for AI coding agents](/guides/loop-engineering-ai-coding-agents) — Shared instruction files should name verification commands and stop rules for agent loops, not only one-shot prompts.
- [GitHub instruction-file adoption report](/guides/ai-coding-agent-instruction-file-adoption-report-2026) — Compare official support rules with a dated 400-file public GitHub content sample and downloadable raw data.

---
Canonical: https://www.kyenai.com/guides/agents-md-vs-claude-md-cursorrules-copilot-instructions