AGENTS.md: one rules file for every coding agent (2026)

The setup

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)

Tools change fast. Every row links to the vendor doc we checked, so confirm in your version.

1. AGENTS.md (the source of truth)

Raw markdown with every file: /guides/agents-md.md. Save this as AGENTS.md in your repo root and replace every {{placeholder}}.

# 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 (one line, plus Claude-only notes)

@AGENTS.md

## Claude Code only
- {{e.g. Use plan mode for changes under src/billing/}}

The @AGENTS.md line pulls the whole file in. It must not be inside backticks or a code block, because Claude Code skips imports there.

3. Gemini CLI: .gemini/settings.json

{
  "context": { "fileName": ["AGENTS.md", "GEMINI.md"] }
}

Aider: read: AGENTS.md in .aider.conf.yml. Codex, Cursor, Copilot and Antigravity need nothing extra.

4. Keep them in sync: check_agents_md.sh (free)

A short, read-only POSIX shell script. Run it from the repo root or as a CI step. It exits 1 if AGENTS.md is missing, if CLAUDE.md doesn't import it, if Gemini's settings don't list it, or if AGENTS.md is over Codex's 32 KiB default. It also flags duplicate sources. We ran it on 7 test repos under sh and dash (log in the raw markdown).

Download: curl -o check_agents_md.sh https://agentpromptsatoz.com/guides/agents-md/check_agents_md.sh.txt (read it first), then sh check_agents_md.sh. In GitHub Actions, add a step: - run: sh check_agents_md.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

Migrating from an existing setup

• Have a CLAUDE.md? Move its shared rules into AGENTS.md. Replace CLAUDE.md with @AGENTS.md plus anything Claude-only.
• Have .cursorrules or .cursor/rules? Move the always-on rules into AGENTS.md. Keep only file-scoped .mdc rules (with globs). Our Cursor rules guide shows the four rule types.
• Have .github/copilot-instructions.md? Move the shared parts to AGENTS.md. Copilot reads both and adds them together, so keep only Copilot-specific lines there, or delete it.
• Have GEMINI.md? Move the content to AGENTS.md and add the settings.json above. Or keep GEMINI.md and list both names.

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

Related free guides

• CLAUDE.md template
• Cursor rules for vibe coding
• Claude Code Stop hook that blocks a fake "done"
• Agent Done-Check pack