Skip to content
Agent Friendly Code

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:

What each coding agent needs to read a repo's AGENTS.md
AgentReads AGENTS.mdWhat to add
Codex, Cursor, Devin, Kimi CLI, OpenHands, Pi, OpenCodeAlwaysNothing
GitHub CopilotCloud agent, code review, CLI and VS CodeA short .github/copilot-instructions.md for Chat on github.com and the other IDEs
Claude CodeOnly 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 CLIOnce named in context.fileNameA settings.json entry
AiderOnce listed under read:A line in .aider.conf.yml

Symlink, import or setting: what are the options for Claude Code?

Ways to make Claude Code read a repo's AGENTS.md
ApproachHowTrade-off
ImportA CLAUDE.md containing @AGENTS.md, plus any Claude-only lines below itWorks on every OS and in sessions that read only CLAUDE.md; one extra small file
Symlinkln -s AGENTS.md CLAUDE.mdNo second file to read, but breaks on Windows clones without core.symlinks; no room for Claude-only lines
No CLAUDE.mdRely on Claude Code reading AGENTS.md when no CLAUDE.md existsNeeds v2.1.277+; any CLAUDE.local.md turns it off; before v2.1.281, Bedrock and telemetry-disabled sessions read only CLAUDE.md
SettingSet Project instructions in /config to claude-md-and-agents-mdPer 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 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.md

Copilot'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.

Repos on the board by how they share one instructions file
ApproachExamples
CLAUDE.md imports @AGENTS.mdastral-sh/ruff, grafana/grafana, supabase/supabase, n8n-io/n8n, prometheus/prometheus
CLAUDE.md → AGENTS.md symlinkapache/airflow, sveltejs/kit, colinhacks/zod, pnpm/pnpm, moby/moby
AGENTS.md → CLAUDE.md symlinkoven-sh/bun, pytorch/pytorch, vitessio/vitess, milvus-io/milvus
Both linked to a third filehuggingface/transformers (.ai/AGENTS.md), discourse/discourse (AI-AGENTS.md), lit/lit (.github/copilot-instructions.md)
GEMINI.md linked tooapache/superset (CLAUDE.md and GEMINI.md → AGENTS.md)
Two separate filesollama/ollama, mui/material-ui, nrwl/nx, ggml-org/llama.cpp

Which approach should you pick?

  1. Import by default. @AGENTS.md works on Windows, on older Claude Code, and in sessions that can't load AGENTS.md, and leaves room for Claude-only lines.
  2. Symlink only if every contributor is on macOS or Linux and you have nothing Claude-specific to say.
  3. Keep two separate files only if their content truly differs; otherwise they drift, and each agent follows whichever copy it reads.
  4. Add context.fileName for Gemini CLI and read: 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.symlinks enabled 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.md or CLAUDE.local.md exists. A CLAUDE.md with @AGENTS.md makes 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