# AI Coding Config Files Guide: AGENTS.md, CLAUDE.md, Gemini, Copilot, Cursor & Windsurf (2026)

Choose and organize AGENTS.md, CLAUDE.md, GEMINI.md, GitHub Copilot instructions, Cursor Rules, and Windsurf Rules with a surface-aware support matrix, copyable repository layout, and safe synchronization policy.

## Quick Answer

There is no universal AI coding config filename. Use AGENTS.md for documented Codex and cross-agent repository guidance, CLAUDE.md for Claude Code project memory, GEMINI.md for Gemini CLI guidance, .github/copilot-instructions.md for broad GitHub Copilot repository instructions, .cursor/rules/*.mdc for current Cursor project rules, and .windsurf/rules/*.md for Windsurf rules. Keep one canonical policy and maintain short tool-specific adapters; verify support by product surface before assuming a file is loaded.

## Best for

Developers, platform engineers, staff engineers, and engineering managers standardizing AI coding-agent instructions across repositories.

## Use this guide to

Developers and platform teams want one practical map of AI coding configuration files before they add repository instructions or migrate between coding agents.

## Recommended play

1. List the agent surfaces the repository actually uses before choosing filenames.
2. Choose one canonical policy and create short adapters for documented readers.
3. Use .github/copilot-instructions.md for broad Copilot coverage and verify CLAUDE.md support by surface.
4. Put package-specific commands in nested files only when the package really differs.
5. Run one controlled task with the same repository state, permissions, and verification command after each migration.

## AI coding config files by reader and scope

Use this table to choose a starting file. Support, nesting, and precedence can change by product surface, plan, and version; use the official source before standardizing a repository policy.

| Area | File or rule system | Best documented use | Scope and caution |
| --- | --- | --- | --- |
| AGENTS.md | Codex repository instructions and a readable shared policy for tools that document support | Root or nested repository guidance can be useful, but every reader must be checked separately | Do not assume AGENTS.md is loaded by every editor, CLI, cloud agent, or review surface |
| CLAUDE.md | Claude Code project memory, setup, workflow, and repository guidance | Project and user scope are documented by Claude Code; import or synchronize shared policy intentionally | Selected Copilot surfaces may support it, but it is not a universal Copilot baseline |
| GEMINI.md | Gemini CLI project context and repository instructions | Use the scope and discovery rules documented by the Gemini CLI version in use | Keep Gemini-specific guidance separate from generic policy when commands or tools differ |
| .github/copilot-instructions.md | Broad repository-wide GitHub Copilot instructions | Add path-specific .instructions.md files when a folder needs different guidance | Check Chat, CLI, coding-agent, and code-review support separately |
| .cursor/rules/*.mdc | Current Cursor project rules with metadata and file matching | Rules can be always-on, file-matched, requested, or manual depending on metadata | Keep legacy .cursorrules during migration until observed behavior and checks pass |
| .windsurf/rules/*.md | Windsurf project rules for editor-specific behavior and workflows | Use documented activation and scope settings for the Windsurf version in use | Do not treat Windsurf rule discovery as proof that another agent reads the same file |

## Execution steps

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

## FAQ

**Q: What should you do first?**

List the agent surfaces the repository actually uses before choosing filenames.

**Q: Who is this guide for?**

Developers, platform engineers, staff engineers, and engineering managers standardizing AI coding-agent instructions across repositories.

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

## Evidence sources

- [AGENTS.md documentation](https://agents.md/) — agents.md. Project overview for the Markdown convention and its use across coding agents; verify each product's own discovery behavior.
- [Codex coding-agent instructions](https://developers.openai.com/codex/guides/agents-md/) — OpenAI. Official AGENTS.md discovery and repository-instruction behavior for Codex.
- [Claude Code memory](https://docs.anthropic.com/en/docs/claude-code/memory) — Anthropic. Official CLAUDE.md project-memory and scope guidance for Claude Code.
- [Customize GitHub Copilot with custom instructions](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions) — GitHub. Official Copilot instruction-file paths and surface-specific support, including repository-wide and path-specific guidance.
- [Gemini CLI repository context](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md) — Google. Gemini CLI documentation for GEMINI.md context and instruction behavior.
- [Cursor rules](https://docs.cursor.com/context/rules) — Cursor. Official Cursor project rules, metadata, scopes, and legacy .cursorrules migration context.
- [Windsurf rules](https://docs.windsurf.com/windsurf/cascade/memories) — Windsurf. Official Windsurf Cascade memories and rules documentation; verify current activation and scope behavior before rollout.

## Related guides

- [compare AGENTS.md, CLAUDE.md, Copilot instructions, and Cursor Rules](/guides/agents-md-vs-claude-md-cursorrules-copilot-instructions) — Use the evidence-backed comparison when the repository must choose a file by tool surface and precedence.
- [copy an AGENTS.md starter template](/guides/agents-md-template-for-ai-coding-agents) — Start from a concise policy template after choosing the repository instruction boundary.
- [adapt AGENTS.md examples for Node.js, Python, or monorepos](/guides/agents-md-examples-codex-node-python-monorepos) — Use concrete directory, command, and safety examples instead of copying a generic policy unchanged.
- [check whether GitHub Copilot reads CLAUDE.md by surface](/guides/does-github-copilot-read-claude-md-support-matrix) — Resolve Copilot CLI, cloud-agent, Chat, and code-review support before claiming compatibility.
- [review the instruction-file adoption dataset and limitations](/guides/ai-coding-agent-instruction-file-adoption-report-2026) — Inspect the sampled public files and evidence boundaries before generalizing configuration patterns.
- [secure MCP credentials and tool permissions](/guides/secure-mcp-servers-ai-coding-agents) — Repository instructions should define the approval and revocation boundaries around external agent tools.

---
Canonical: https://www.kyenai.com/guides/ai-coding-config-files-guide