Which file should you use?
Use the file that the intended agent surface documents. AGENTS.md is a readable Markdown convention for agent instructions and is the repository instruction file documented by Codex. CLAUDE.md is Claude Code's project memory file. GEMINI.md is the project context file documented by Gemini CLI. GitHub Copilot uses .github/copilot-instructions.md for repository-wide instructions and also has separate path-specific instruction files.
Cursor and Windsurf use their own rule systems for the features that need metadata, file globs, activation mode, or editor-specific behavior. A shared AGENTS.md can still be useful where a product documents support, but a shared filename should not be treated as proof of identical discovery, scope, precedence, or context behavior.
Configuration file support matrix
The matrix is a decision aid, not a promise that every plan, editor, CLI, or cloud surface behaves the same way. Follow the linked official documentation for the exact product version and surface, and mark an unverified claim Unknown instead of inferring support from a filename.
A copyable repository layout
Start with a short root policy, then add only the scoped adapters and nested rules that a real package or tool needs. The example below keeps shared commands and boundaries visible while leaving tool-specific metadata in the file format that owns it.
repository/
├── AGENTS.md # canonical shared policy (if your team chooses it)
├── CLAUDE.md # Claude Code adapter or @AGENTS.md import
├── GEMINI.md # Gemini CLI adapter
├── .github/
│ ├── copilot-instructions.md # broad Copilot repository guidance
│ └── instructions/ # optional path-specific Copilot rules
│ └── tests.instructions.md
├── .cursor/
│ └── rules/ # focused Cursor project rules
│ └── testing.mdc
├── .windsurf/
│ └── rules/ # focused Windsurf rules
│ └── review.md
└── packages/
└── api/
└── AGENTS.md # local exception only when neededOne canonical policy, several adapters
Choose one maintained source for facts that must agree everywhere: setup commands, architecture boundaries, test commands, generated-file rules, secrets policy, review expectations, and stop conditions. That source may be AGENTS.md, CLAUDE.md, or an internal policy document; the choice is a maintenance decision, not a claim about universal reader support.
Keep adapters short. An adapter can point maintainers to the canonical policy, express the local file's scope and precedence, and add the few settings that only its tool understands. If an agent cannot follow links or the policy contains security-critical rules, copy the critical rule into the adapter and review it as a synchronized change.
What should not go in an AI coding config file?
Do not commit API keys, access tokens, private certificates, customer data, production credentials, or copied incident transcripts. Do not use a config file as a dumping ground for the entire architecture, every historical decision, or a vendor's marketing text. Long context reduces the chance that the agent notices the command and safety rule that actually matters.
Do not grant permission merely by writing 'you may deploy' or 'skip review'. State the allowed directories, required approval, proof command, rollback boundary, and escalation owner. Keep secrets in the approved secret manager and keep destructive operations behind an explicit human checkpoint.
How to write instructions that agents can verify
Write commands and acceptance criteria that a reviewer can run: install, lint, test, build, migration check, or a focused smoke test. Pair every risky operation with its boundary and stop condition. Prefer a small table of commands and expected results over a paragraph that says 'follow best practices'.
Separate repository facts from preferences. A fact names the current package manager or test command; a preference explains review style. Add an owner or update date when a rule is likely to become stale, and remove instructions that no longer match the repository.
Copilot support is surface-specific
GitHub documents .github/copilot-instructions.md as the repository-wide Copilot instruction path and documents additional scoped instruction files. CLAUDE.md support is not a universal Copilot guarantee: the exact support depends on the Copilot surface, such as CLI, cloud agent, Chat, or code review. Use the dedicated Copilot support matrix linked below when that distinction changes the rollout decision.
The safest broad Copilot baseline is still .github/copilot-instructions.md. Keep CLAUDE.md for Claude Code, and add a Copilot adapter even when a selected Copilot surface happens to read CLAUDE.md.
When should you use nested rules?
Add nested AGENTS.md or scoped editor rules only when a directory has a real local difference: a package-specific test command, generated files, a separate language toolchain, a different owner, or a stricter permission boundary. Keep the nested file shorter than the root and state only the exception.
Before adding another file, ask whether the difference belongs in the build system, editor settings, CI, or a human-owned policy instead. More files are not more governance when nobody can explain which file wins or which agent reads it.
Safe migration checklist
Inventory the current files, exact product surfaces, version or plan, and observed discovery behavior. Make one small adapter change, run the same task before and after, inspect the resulting diff, and keep the old file during comparison when a vendor labels it legacy or deprecated.
Record what was actually verified. If you did not measure context loading, precedence, elapsed time, cost, or human interventions, write Not measured. Do not convert a successful demo into a universal compatibility or benchmark claim.
Recommended play
- List the agent surfaces the repository actually uses before choosing filenames.
- Choose one canonical policy and create short adapters for documented readers.
- Use .github/copilot-instructions.md for broad Copilot coverage and verify CLAUDE.md support by surface.
- Put package-specific commands in nested files only when the package really differs.
- Run one controlled task with the same repository state, permissions, and verification command after each migration.
Execution steps
Inventory the readers
List every IDE, CLI, cloud agent, review surface, and automation that must use repository guidance. Record the product version or plan when support is surface-specific.
Choose the canonical policy
Put shared commands, architecture, security boundaries, and completion criteria in one maintained source, then identify the adapters that must stay synchronized.
Add only documented adapters
Use AGENTS.md, CLAUDE.md, GEMINI.md, Copilot instructions, Cursor Rules, and Windsurf Rules according to each publisher's documented reader and scope.
Add a local exception only when needed
A nested file should describe a real package-specific command, owner, generated-file boundary, or stricter safety rule. Remove duplicate paragraphs from the root policy.
Verify one real task
Run the same task with the same clean repository state, permissions, and proof command. Record measured results and write Not measured for values you did not capture.
Common pitfalls
Treating one filename as a universal standard
Map each file to a documented reader and surface. Keep a small adapter when a tool needs a different filename or metadata format.
Assuming Copilot reads CLAUDE.md everywhere
Use .github/copilot-instructions.md for broad coverage and consult the Copilot surface matrix for exceptions.
Duplicating a giant policy across six files
Choose one canonical source, synchronize only the critical rules, and keep adapters short enough to review for drift.
Putting secrets or deployment authority in Markdown
Use approved secret storage and explicit human approvals. Config files should describe boundaries, not contain credentials or silently widen access.
Calling unmeasured behavior a benchmark
Run a controlled task and publish only measured outcomes, versions, limitations, and the exact verification command.
Implementation checklist
- List every agent surface and version that must read repository guidance.
- Choose one canonical policy source and name synchronized adapters.
- Use .github/copilot-instructions.md for broad Copilot coverage.
- Verify CLAUDE.md, AGENTS.md, GEMINI.md, Cursor Rules, and Windsurf Rules by surface.
- Keep secrets, tokens, and unrestricted deployment authority out of config files.
- Use nested files only for real local exceptions.
- Run the same task and proof command after a migration.
- Publish Not measured instead of invented benchmark values.
Questions this guide answers
What should you do first?
List the agent surfaces the repository actually uses before choosing filenames.
Who is this guide for?
Developers, platform engineers, staff engineers, and engineering managers standardizing AI coding-agent instructions across repositories.
What evidence supports this guide?
This guide uses listed source material from agents.md, OpenAI, Anthropic, GitHub, Google, Cursor, Windsurf. Source links and scope notes are available on this page.