# AGENTS.md: one rules file for every coding agent (2026) > Keep your rules in AGENTS.md once. Codex, Cursor, GitHub Copilot and Antigravity read it natively, Claude Code reads it through a one-line @AGENTS.md import in CLAUDE.md, and Gemini CLI needs one setting. Support table checked against vendor docs on 2026-10-24. Source: https://agentpromptsatoz.com/guides/agents-md/ · License: free to use and adapt · Publisher: Agent Prompts A to Z ## The setup ````text your-repo/ ├── AGENTS.md # the one source of truth (all agents) ├── CLAUDE.md # 1 line: @AGENTS.md (+ Claude-only notes) ├── .gemini/settings.json # only if you use Gemini CLI ├── .cursor/rules/*.mdc # optional: file-scoped rules only, no copies └── packages/api/AGENTS.md # optional: nested rules for one folder ```` ## Who reads AGENTS.md (checked 2026-10-24) - **OpenAI Codex** (Native): Reads AGENTS.md from the repo root down to your current folder, plus ~/.codex/AGENTS.md. AGENTS.override.md in a folder replaces that folder's file. Stops at 32 KiB combined by default (project_doc_max_bytes). Docs: https://developers.openai.com/codex/guides/agents-md - **Cursor** (Native): Reads AGENTS.md in the project root and in subfolders (nested files combine, more specific wins). Use .cursor/rules/*.mdc only for file-scoped extras. A file @-mention inside a rule is not inlined, so don't try to 'import' AGENTS.md from a rule. Docs: https://cursor.com/docs/context/rules - **GitHub Copilot** (Native): Copilot reads AGENTS.md files anywhere in the repo; the nearest one in the directory tree takes precedence. It also reads .github/copilot-instructions.md, and instruction files are additive, so don't repeat or contradict AGENTS.md there. In VS Code, the chat.useAgentsMdFile setting is on by default. Docs: https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions - **Claude Code** (Partly native): Since v2.1.277 (Sept 2026) it reads AGENTS.md, but by default only when there is no CLAUDE.md or CLAUDE.local.md. The reliable setup: a CLAUDE.md whose first line is @AGENTS.md, with any Claude-only notes below it. Or set Project instructions to claude-md-and-agents-md in /config. Docs: https://code.claude.com/docs/en/memory - **Gemini CLI** (Setting): Reads GEMINI.md by default. Add AGENTS.md to context.fileName in .gemini/settings.json. Docs: https://geminicli.com/docs/cli/gemini-md/ - **Google Antigravity (IDE and CLI)** (Native): Reads AGENTS.md and GEMINI.md at the workspace root and in subfolders. (For free-tier and Google One users, Gemini CLI was replaced by Antigravity CLI in June 2026.) Docs: https://antigravity.google/docs/rules/ - **Aider** (Setting): Add read: AGENTS.md to .aider.conf.yml. Docs: https://agents.md/ - **Windsurf, Zed, Amp, Jules, Devin, Factory, opencode, goose, Warp, Roo Code, Kilo Code and others** (Listed): Listed as AGENTS.md-compatible on agents.md. We didn't check each tool's docs, so confirm in yours. Docs: https://agents.md/ ## 1. AGENTS.md ````markdown # AGENTS.md ## Project - What this is: {{one sentence, e.g. "Next.js 15 app for booking dog walks"}} - Stack: {{language, framework, database, hosting}} - Package manager: {{npm / pnpm / bun / uv}}. Never switch it. ## Commands - Install: {{pnpm install}} - Dev server: {{pnpm dev}} - Tests: {{pnpm test}} (single file: {{pnpm test path/to/file}}) - Lint and types: {{pnpm lint && pnpm typecheck}} - Build: {{pnpm build}} ## Layout - {{src/app/}}: routes and pages - {{src/lib/}}: shared logic, no UI - {{tests/}}: tests mirror the src/ tree - Do not edit: {{generated/, migrations already applied, vendor/}} ## How to work 1. For anything bigger than a one-line fix, write a short plan first and wait for my OK. 2. Make one small change at a time, then run the tests and lint before moving on. 3. Match the existing style in the file you are editing. Don't reformat unrelated code. 4. Don't add a new dependency without asking. Prefer what's already installed. 5. If something is unclear, ask one question instead of guessing. ## Code rules - {{TypeScript strict, no `any`}} - {{Errors: throw typed errors, never swallow them}} - {{Secrets come from env vars; never hard-code keys or commit .env}} ## Definition of done Before you say a task is done, list each claim (tests pass, bug fixed, feature works) and mark it VERIFIED with the exact command and its real output, or FAILED, or NOT RUN. Never say "all tests pass" unless you ran them in this session and quote the result. Don't skip, delete, or weaken a test to make it pass. ## Gotchas - {{e.g. "The dev DB resets on every `pnpm dev`; seed with `pnpm seed`"}} - {{e.g. "Auth is mocked in tests via tests/setup.ts"}} ```` ## 2. CLAUDE.md ````markdown @AGENTS.md ## Claude Code only - {{e.g. Use plan mode for changes under src/billing/}} ```` ## 3. .gemini/settings.json ````json { "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } } ```` Aider: ````yaml # .aider.conf.yml read: AGENTS.md ```` ## 4. check_agents_md.sh (also at https://agentpromptsatoz.com/guides/agents-md/check_agents_md.sh.txt) ````sh #!/usr/bin/env sh # check_agents_md.sh - fail if your agent rules files have drifted apart. # Free from https://agentpromptsatoz.com/guides/agents-md/ . Read-only; changes nothing. # Usage: sh check_agents_md.sh (run from the repo root, locally or in CI) fail=0 say(){ printf '%s\n' "$1"; } if [ ! -s AGENTS.md ]; then say "FAIL: AGENTS.md is missing or empty (it is the single source of truth)"; exit 1; fi say "ok: AGENTS.md found" size=$(wc -c < AGENTS.md | tr -d ' ') if [ "$size" -gt 32768 ]; then say "FAIL: AGENTS.md is $size bytes; Codex stops reading at 32 KiB by default"; fail=1; else say "ok: AGENTS.md is $size bytes (Codex default cap is 32768)"; fi for f in CLAUDE.md .claude/CLAUDE.md; do [ -e "$f" ] || continue if [ -L "$f" ]; then say "ok: $f is a symlink to $(readlink "$f")"; continue; fi if grep -Eq '^[[:space:]]*@(\./)?AGENTS\.md[[:space:]]*$' "$f"; then say "ok: $f imports @AGENTS.md" else say "FAIL: $f exists but does not import AGENTS.md. Claude Code reads CLAUDE.md instead of AGENTS.md when both exist; add a line: @AGENTS.md"; fail=1; fi done if [ -f .gemini/settings.json ]; then if grep -q 'AGENTS.md' .gemini/settings.json; then say "ok: .gemini/settings.json lists AGENTS.md"; else say "FAIL: .gemini/settings.json does not list AGENTS.md in context.fileName"; fail=1; fi fi if [ -f .github/copilot-instructions.md ]; then n=$(grep -c '' .github/copilot-instructions.md | tr -d ' ') say "note: .github/copilot-instructions.md also exists ($n lines). Copilot adds it on top of AGENTS.md, so keep it Copilot-only and don't repeat or contradict AGENTS.md" fi for f in .cursorrules; do [ -f "$f" ] && say "note: legacy $f found; move it into AGENTS.md or .cursor/rules/*.mdc"; done [ $fail = 0 ] && say "PASS: one source of truth" || say "FAILED: fix the lines above" exit $fail ```` Test log: ````text check_agents_md.sh test run, 2026-10-24 (sh and dash, temp repos) 1 no AGENTS.md -> FAIL, exit 1 (expected) 2 AGENTS.md only -> PASS, exit 0 3 CLAUDE.md without @AGENTS.md -> FAIL, exit 1 (expected) 4 CLAUDE.md with @AGENTS.md -> PASS, exit 0 5 .gemini/settings.json w/o AGENTS -> FAIL, exit 1; copilot-instructions note shown 6 CLAUDE.md symlink + gemini ok -> PASS, exit 0 7 AGENTS.md 40,030 bytes -> FAIL, exit 1 (32 KiB Codex default) Not tested inside the agents themselves; the support table is from the vendors' docs, checked 2026-10-24. ```` ## Tips - Write AGENTS.md once, then delete the copies. Two files with the same rules will drift within a month. - Put the exact install, test, lint and build commands first. Every agent follows them literally. - Keep tool-specific notes out of AGENTS.md. Claude-only lines go under the import in CLAUDE.md. - Check with each tool after setup: /memory or /context in Claude Code, the References list in Copilot, 'Summarize the current instructions' in Codex. - Add one line to AGENTS.md whenever any agent makes the same mistake twice. ## FAQ **Does Claude Code read AGENTS.md now?** Yes, since Claude Code v2.1.277 (September 2026), but by default only when your project has no CLAUDE.md or CLAUDE.local.md. If you have, or might later add, a CLAUDE.md, put @AGENTS.md on its first line. Anthropic's docs say keeping that import never makes Claude read AGENTS.md twice. You can also set Project instructions to claude-md-and-agents-md in /config to load both. **AGENTS.md vs CLAUDE.md: which should be the source of truth?** AGENTS.md. Codex, Cursor, GitHub Copilot, Antigravity and many others read it natively. Claude Code reads it directly or through a one-line @AGENTS.md import. If you keep the real rules in CLAUDE.md instead, every non-Claude agent misses them. **Should I use a symlink (ln -s AGENTS.md CLAUDE.md) instead of the import?** It works, with two catches from Anthropic's docs. Claude's Edit and Write tools won't write through a symlink. And on Windows, Git checks a committed symlink out as a one-line text file unless core.symlinks is enabled. The @AGENTS.md import works everywhere and still leaves room for Claude-only notes. **Do I still need .cursor/rules or .github/copilot-instructions.md?** Not for shared rules. Cursor and Copilot both read AGENTS.md. Use .cursor/rules/*.mdc or .github/instructions/*.instructions.md only for file-scoped extras, such as test-file rules. Copilot adds copilot-instructions.md on top of AGENTS.md, so anything you put in both will drift. **How long can AGENTS.md be?** Codex stops adding instruction files after 32 KiB combined by default. Claude's docs suggest under 200 lines per file. Keep the root file to one screen (commands, layout, how to work, definition of done) and move folder-specific rules into nested AGENTS.md files. **How do nested AGENTS.md files work?** Put another AGENTS.md inside a package or folder. Codex, Cursor and Copilot all apply the nearest file. Codex and Cursor combine it with the parent files, with the closer file winning. Claude Code loads a subfolder's AGENTS.md when it reads a file there, if that folder has no CLAUDE.md. **How do I stop the files drifting apart?** Run the free check_agents_md.sh below in CI. It fails if CLAUDE.md doesn't import AGENTS.md, if Gemini's settings don't list it, or if AGENTS.md is over Codex's 32 KiB default. It also flags a copilot-instructions.md or legacy .cursorrules that may duplicate it. ## Go further (premium) [App Builder Agent Pack](https://payhip.com/b/EuRgw) ($19): finished AGENTS.md, CLAUDE.md and six Cursor rules files with a plan-then-build workflow. Next.js + Supabase + Stripe: [stack kit](https://payhip.com/b/Pdm5J) ($9). Or [all 5 premium packs](https://payhip.com/b/J8eUb) for $29.