AGENTS.md vs CLAUDE.md: one source of truth for Claude Code and Codex
In short: put every rule in AGENTS.md. Make CLAUDE.md a thin file whose first line is @AGENTS.md, then add only Claude-specific notes. Codex, Cursor, Windsurf/Devin and Copilot read AGENTS.md directly, and Claude Code imports it, so you edit one file and nothing drifts.
Why two files exist
Most AI coding tools adopted AGENTS.md. Claude Code reads CLAUDE.md instead. Newer Claude Code versions fall back to AGENTS.md when there's no CLAUDE.md, but as soon as you add a CLAUDE.md (for imports, skills notes or team settings), Claude stops reading AGENTS.md on its own. Copying the rules into both files works on day one. Within a month, one copy is stale and two agents on the same repo follow different rules.
The pattern
# CLAUDE.md
@AGENTS.md
## Claude Code
- Skills: /plan-feature, /review-changes, /record-decisions
- Use plan mode before touching auth or billing@path is Claude Code's documented import syntax. The imported file is expanded into context at launch, just as if its text were in CLAUDE.md. Two consequences:
- Imports don't save context. Keep AGENTS.md lean. Anthropic suggests about 200 lines per memory file, and Codex stops at 32 KiB by default (
project_doc_max_bytes). - Put Claude-only content after the import: skills, plan-mode habits and hooks. Anything every agent needs goes in AGENTS.md.
Add a decisions log
Rules say how to work; decisions say what was already settled ("we use Drizzle, not Prisma", "money is integer cents"). Without them, each new session re-litigates old choices. End AGENTS.md with a short, append-only section:
## Decisions log
- 2026-10-16: Use @supabase/ssr with getClaims() on the server. Why: auth-helpers is deprecated. Rejected: getSession() for authorization.Then make appending a habit with an end-of-session command (a Claude Code skill, a Codex skill or a Windsurf workflow) that collects the session's decisions, shows them to you, and appends them. It must never rewrite old entries.
Local rules next to risky code
Global rules can't hold every invariant. Put a short AGENTS.md in src/auth/ or src/billing/ with the invariants, a never-list and the checks to run, plus a one-line CLAUDE.md (@AGENTS.md) beside it. Loading differs by tool:
| Tool | Nested AGENTS.md |
|---|---|
| Cursor | Applied to files in that folder, combined with parent rules |
| Windsurf / Devin | Auto-discovered; acts like a glob rule for that folder |
| Claude Code | Reads the sibling CLAUDE.md when it works in that folder, which imports the local AGENTS.md |
| Codex | Loads root → launch folder only, so add an always-on rule: “before editing, read AGENTS.md in the file's folder and its parents” |
| VS Code Copilot | Experimental chat.useNestedAgentsMdFiles setting, or .github/instructions/*.instructions.md with applyTo |
What to put in AGENTS.md (that agents actually need)
- Commands: exact lint, typecheck, test and build commands.
- Definition of done: never edit or delete tests or assertions to make them pass, never change acceptance criteria, and verify the real user flow.
- Version pinning: read package.json and the lockfile before writing code. Tailwind v4 is CSS-first (
@import "tailwindcss"), Next.js 16 awaitscookies()andparamsand renames middleware toproxy.ts, and Supabase uses@supabase/ssr. - Security basics: secrets, input validation, authorization on the server.
- Decisions log at the end.
The AI Coding Rules Pack ships exactly this layout (shared AGENTS.md, thin CLAUDE.md, /record-decisions, local-rule examples) for all five tools. The free sampler uses the same structure.
FAQ
Does Claude Code read AGENTS.md?
Only when there is no CLAUDE.md. If you have a CLAUDE.md, add @AGENTS.md to it so Claude imports the shared file.
Can I symlink CLAUDE.md to AGENTS.md instead?
You can, but then you can't add Claude-only notes, and symlinks break on some Windows setups and zip downloads. The one-line import is more portable.
Does importing AGENTS.md save tokens?
No. Imported files load in full at launch, so keep AGENTS.md short and move detail into local AGENTS.md files or skills.