One instructions file for every AI coding agent
Write the rules once in AGENTS.md. Most agents read it as is; for Claude Code, add a CLAUDE.md that contains @AGENTS.md (or is a symlink to it); for Gemini CLI and Aider, name AGENTS.md in their settings. Of 388 popular GitHub repos, 39 import AGENTS.md from CLAUDE.md and 28 symlink it.
Can one instructions file work for every coding agent?
Nearly. Most agents already read AGENTS.md, so keep that one. What each needs beyond the file:
| Agent | Reads AGENTS.md | What to add |
|---|---|---|
| Codex, Cursor, Devin, Kimi CLI, OpenHands, Pi, OpenCode | Always | Nothing |
| GitHub Copilot | Cloud agent, code review, CLI and VS Code | A short .github/copilot-instructions.md for Chat on github.com and the other IDEs |
| Claude Code | Only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists (v2.1.277 and later) | A CLAUDE.md with @AGENTS.md, or a symlink |
| Gemini CLI | Once named in context.fileName | A settings.json entry |
| Aider | Once listed under read: | A line in .aider.conf.yml |
Symlink, import or setting: what are the options for Claude Code?
| Approach | How | Trade-off |
|---|---|---|
| Import | A CLAUDE.md containing @AGENTS.md, plus any Claude-only lines below it | Works on every OS and in sessions that read only CLAUDE.md; one extra small file |
| Symlink | ln -s AGENTS.md CLAUDE.md | No second file to read, but breaks on Windows clones without core.symlinks; no room for Claude-only lines |
| No CLAUDE.md | Rely on Claude Code reading AGENTS.md when no CLAUDE.md exists | Needs v2.1.277+; any CLAUDE.local.md turns it off; before v2.1.281, Bedrock and telemetry-disabled sessions read only CLAUDE.md |
| Setting | Set Project instructions in /config to claude-md-and-agents-md | Per user, not per repo: contributors who don't set it don't get it |
How do you import AGENTS.md into CLAUDE.md?
Put @AGENTS.md in a CLAUDE.md beside it. Claude reads the imported file first, then the rest of CLAUDE.md, so Claude-only instructions go below the import. Anthropic's docs say the import never makes Claude read AGENTS.md twice, whatever the Project instructions setting.
CLAUDE.md
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.How do you symlink CLAUDE.md to AGENTS.md?
macOS or Linux, at the repo root
ln -s AGENTS.md CLAUDE.md
git add CLAUDE.md
git commit -m "Link CLAUDE.md to AGENTS.md"- Windows: creating a symlink needs Administrator rights or Developer Mode, and unless
core.symlinksis enabled Git checks a committed symlink out as a plain file holding the link text, so that clone's CLAUDE.md is the one lineAGENTS.md. Git probes and may setcore.symlinksto false on clone. If anyone works on Windows, use the import. - Editing: Claude reads through the link, but its Edit and Write tools won't write through a symlink; they edit the target, AGENTS.md, instead.
- Symlinks to network or UNC paths aren't followed.
How do Gemini CLI, Aider and Copilot pick up the same file?
Gemini CLI reads GEMINI.md by default; context.fileName in settings.json takes a name or a list. Keep GEMINI.md in the list if you have one.
settings.json (Gemini CLI)
{
"context": {
"fileName": ["AGENTS.md", "GEMINI.md"]
}
}Aider's docs describe no file it finds on its own. List AGENTS.md under read: in .aider.conf.yml (a list takes several), or pass --read AGENTS.md.
.aider.conf.yml
read: AGENTS.mdCopilot's cloud agent, code review and CLI read AGENTS.md and also a root CLAUDE.md or GEMINI.md, and VS Code reads AGENTS.md (its Local harness once chat.useAgentsMdFile is on). Chat on github.com, Visual Studio, JetBrains, Xcode and Eclipse don't list AGENTS.md; they read .github/copilot-instructions.md, so keep a short one with the essentials. The Copilot guide has the per-surface table.
What do real repos do?
From our census of the 388 GitHub repos on the board on 2026-11-16: 39 have a CLAUDE.md that imports @AGENTS.md, 28 have a root CLAUDE.md symlinked to an AGENTS.md, and 18 keep AGENTS.md and CLAUDE.md as separate files with no link or import. 38 repos have a root AGENTS.md or CLAUDE.md that is a symlink to something.
| Approach | Examples |
|---|---|
| CLAUDE.md imports @AGENTS.md | astral-sh/ruff, grafana/grafana, supabase/supabase, n8n-io/n8n, prometheus/prometheus |
| CLAUDE.md → AGENTS.md symlink | apache/airflow, sveltejs/kit, colinhacks/zod, pnpm/pnpm, moby/moby |
| AGENTS.md → CLAUDE.md symlink | oven-sh/bun, pytorch/pytorch, vitessio/vitess, milvus-io/milvus |
| Both linked to a third file | huggingface/transformers (.ai/AGENTS.md), discourse/discourse (AI-AGENTS.md), lit/lit (.github/copilot-instructions.md) |
| GEMINI.md linked too | apache/superset (CLAUDE.md and GEMINI.md → AGENTS.md) |
| Two separate files | ollama/ollama, mui/material-ui, nrwl/nx, ggml-org/llama.cpp |
Which approach should you pick?
- Import by default.
@AGENTS.mdworks on Windows, on older Claude Code, and in sessions that can't load AGENTS.md, and leaves room for Claude-only lines. - Symlink only if every contributor is on macOS or Linux and you have nothing Claude-specific to say.
- Keep two separate files only if their content truly differs; otherwise they drift, and each agent follows whichever copy it reads.
- Add
context.fileNamefor Gemini CLI andread:for Aider if your contributors use them, and a short copilot-instructions.md if they use Copilot Chat outside VS Code.
Questions people ask
- What is the GitHub Copilot equivalent of CLAUDE.md?
.github/copilot-instructions.md. But Copilot's cloud agent, code review and CLI also read AGENTS.md and a root CLAUDE.md, and VS Code reads AGENTS.md, so those may not need a Copilot-only file.- Will Claude Code read AGENTS.md twice if CLAUDE.md imports it?
- No. Anthropic's docs say the import never causes a second read, whatever the Project instructions setting. A symlinked CLAUDE.md is also read once.
- Does a CLAUDE.md symlink work on Windows?
- Only if the clone has
core.symlinksenabled and the user can create symlinks (Administrator or Developer Mode). Otherwise the checkout is a one-line file holding the link target, and Claude sees that line instead of your instructions. - Can I symlink AGENTS.md to CLAUDE.md instead?
- Yes; oven-sh/bun and pytorch/pytorch do. Either direction gives every tool the same content.
- Do I still need CLAUDE.md if Claude Code reads AGENTS.md?
- Not on Claude Code v2.1.277 or later with the default setting, as long as no CLAUDE.md,
.claude/CLAUDE.mdor CLAUDE.local.md exists. A CLAUDE.md with@AGENTS.mdmakes it work for everyone else too.
From the docs: code.claude.com/memory (new tab) · git-scm.com/git-config (new tab) · geminicli.com/gemini-md (new tab) · aider.chat/conventions.html (new tab) · docs.github.com/custom-instructions-support (new tab) · docs.github.com/add-repository-instructions (new tab) · agents.md (new tab)
CLAUDE.md vs AGENTS.md · GEMINI.md vs AGENTS.md · Cursor rules vs AGENTS.md · CLAUDE.md guide · copilot-instructions.md guide · What each agent reads · All guides