Quick answer
Use AGENTS.md for repository-level guidance that Codex-compatible agents can read, CLAUDE.md for Claude Code project memory and local workflow notes, .cursorrules or Cursor rules for Cursor behavior, and Copilot instructions for GitHub Copilot coding guidance. The safest shared pattern is to keep durable project facts in one canonical source and mirror tool-specific instructions only where the tool requires them.
What each file should own
AGENTS.md should describe build commands, test commands, repository conventions, safe edit boundaries, and review expectations.
CLAUDE.md is best for Claude Code workflows, recurring commands, subagent expectations, and local project context that Claude should remember.
Cursor rules work well for editor behavior, coding style, framework conventions, and file-pattern-specific instructions.
Copilot instructions should stay concise and align with GitHub workflows, pull requests, security expectations, and organization policies.
Avoid duplicated contradictions
The risk is not having multiple instruction files; the risk is letting them disagree. Keep a canonical policy section and copy only short tool-specific adapters. Review these files whenever build commands, package managers, test names, or security boundaries change.
Recommended play
- Make one repository instruction inventory before editing files.
- Choose the canonical source by team workflow: AGENTS.md for cross-agent repo rules, CLAUDE.md for Claude Code memory, Cursor rules for editor behavior, and Copilot instructions for GitHub-native coding guidance.
- Keep shared rules short, copy-pasteable, and linked from tool-specific files instead of rewriting the same policy four times.
Instruction file ownership map
Use this table to decide where each kind of rule should live before adding or migrating instruction files.
| Area | Best owner | Put here | Avoid here |
|---|---|---|---|
| Build and test commands | AGENTS.md | Package manager, test entrypoints, verification expectations | Long tool-specific memories that drift from the repo |
| Claude Code project memory | CLAUDE.md | Recurring local commands, project context, Claude-specific workflow notes | Rules needed by every agent if no shared source exists |
| Editor behavior | Cursor rules | Framework style, file-pattern rules, editor assistance boundaries | Secrets, credentials, or organization-wide policies |
| GitHub workflow | Copilot instructions | Pull request style, review expectations, repository guidance | Large onboarding docs or conflicting build commands |
Execution steps
Inventory current files
Search the repository for AGENTS.md, CLAUDE.md, Cursor rules, and Copilot instruction files, then list which agent reads each one.
Select a canonical policy source
Put durable build, test, security, and review rules in the file most likely to be read across the team, then keep tool-specific adapters short.
Normalize commands
Make every command copy-pasteable, include the working directory when needed, and remove stale package-manager assumptions.
Add drift review
Review instruction files when CI, package managers, frameworks, or security rules change so agents do not follow old workflow memory.
Common pitfalls
Duplicating policy into every file
Keep one source of truth and link or summarize it in the tool-specific files.
Mixing agent memory with secrets
Document environment names and access boundaries, but never paste credentials into instruction files.
Letting old commands survive
Treat instruction changes like code changes and verify the listed commands before publishing.
Implementation checklist
- List the agent tools the repository actually uses.
- Choose one canonical source for build/test/security rules.
- Add tool-specific files only when the tool reads them.
- Keep commands copy-pasteable and current.
- Add a quarterly review owner for instruction drift.
Questions this guide answers
What is the answer to AGENTS.md vs CLAUDE.md vs .cursorrules?
A practical comparison of repository instruction files for Codex, Claude Code, Cursor, and GitHub Copilot so teams can decide what to put where.
Who is this cross-tool reference comparison for?
Developer tools teams, staff engineers, platform teams, and AI coding adopters.
Which sources support this guide?
This guide is grounded in official or high-confidence sources from OpenAI, Anthropic, Cursor, GitHub.