Guide
CLAUDE.md vs AGENTS.md: which instructions file to use
Most agents read AGENTS.md; Claude Code reads CLAUDE.md first. How each is loaded, and the one-line setup that gives every agent the same rules.
AGENTS.md is the open, shared instructions file that most coding agents read, including Codex, Cursor, GitHub Copilot, Google Antigravity, Kiro, Devin and OpenCode; CLAUDE.md is Claude Code's own. Since version 2.1.277, released September 18, 2026, Claude Code also reads AGENTS.md, but only when a project has no CLAUDE.md. If your team uses Claude Code alongside other agents, keep your rules in AGENTS.md and add a CLAUDE.md containing the line @AGENTS.md, plus anything only Claude needs. Both files load into every session, so keep them short: Anthropic suggests under 200 lines.
Key takeaways
- AGENTS.md is an open format stewarded by the Agentic AI Foundation under the Linux Foundation, and used by more than 60,000 open-source projects.
- Claude Code reads CLAUDE.md, and reads AGENTS.md only when there is no CLAUDE.md, unless you change "Project instructions" in
/config. - The setup for both: AGENTS.md holds the rules; CLAUDE.md says
@AGENTS.md. Anthropic recommends the import over a symlink if anyone uses Windows. - Instructions vs skills: instruction files load every session; skills (SKILL.md) load only when a task needs them.
- For teams: commit the files to the repository; Thoughtworks rates curated shared instructions "Adopt."
| CLAUDE.md | AGENTS.md | |
|---|---|---|
| Who reads it | Claude Code (and some other tools as a fallback) | Codex, Cursor, Copilot, Antigravity, Kiro, Devin, OpenCode and more; Claude Code since 2.1.277 |
| Maintained by | Anthropic | Agentic AI Foundation (Linux Foundation) |
| Where it lives | Project root or .claude/, your home folder, managed policy | Repository root and subfolders, plus a global file in some tools |
| Nesting | Parent folders combined; subfolders load on demand | Closest file wins |
| Personal file | CLAUDE.local.md | AGENTS.override.md in Codex |
| Size guidance | Under 200 lines | Codex reads up to 32 KiB by default |
What is AGENTS.md?
A plain Markdown file of instructions for coding agents, a "README for agents" with no required fields (agents.md). OpenAI introduced it, and in December 2025 it became one of the founding projects of the Linux Foundation's Agentic AI Foundation, alongside Anthropic's MCP and Block's goose (Linux Foundation). Files can sit at the repository root and in subfolders; the closest one to the file being edited wins, and the user's own prompt overrides everything.
Which tools read AGENTS.md?
- Codex: reads a global file and every AGENTS.md from the repository root down to the current folder, with AGENTS.override.md taking priority, up to 32 KiB by default (OpenAI).
- Cursor, GitHub Copilot, Google Antigravity, Kiro, Devin, Factory, Cline, Kilo Code, Zed and Jules: read AGENTS.md natively.
- OpenCode: prefers AGENTS.md and falls back to CLAUDE.md.
- Gemini CLI: reads GEMINI.md, and AGENTS.md only if you configure it.
- Claude Code: since September 2026, as below.
How does Claude Code load CLAUDE.md?
From Anthropic's docs (Anthropic):
- Locations, broadest first: a managed policy file set by an organization; your own
~/.claude/CLAUDE.md; the project's./CLAUDE.mdor./.claude/CLAUDE.md; andCLAUDE.local.mdfor personal notes you keep out of git. - Loading: files from the current folder and every folder above it load at launch and are combined, not overridden. CLAUDE.md files in subfolders load when Claude works on files there.
- Imports:
@pathpulls in another file. It organizes, but doesn't save context, since imported files load too. - Path-scoped rules: files in
.claude/rules/can apply only to matching paths. - Auto memory: Claude also keeps its own notes for each project, separate from CLAUDE.md (Claude Code memory).
How does Claude Code read AGENTS.md?
By default, only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working folder or above it. In /config, "Project instructions" can be set to read CLAUDE.md or AGENTS.md (the default), both, only CLAUDE.md, or only managed instructions. One catch: adding a personal CLAUDE.local.md stops AGENTS.md from loading under the default.
How do you use both?
Keep the shared rules in AGENTS.md, and create a CLAUDE.md that imports it:
@AGENTS.md
## Claude Code only
- Plan first for payment changes.
Every agent then follows the same rules, and Claude gets its extras. A symlink from CLAUDE.md to AGENTS.md also works, but Anthropic recommends the import if anyone clones on Windows, where symlinks need admin rights or Developer Mode.
What should go in the file?
Anthropic's test for every line: "Would removing this cause Claude to make mistakes?" If not, cut it (Anthropic).
- Include: commands the agent can't guess (build, test, lint, with exact flags), code style that differs from defaults, branch and pull request conventions, architecture decisions, environment quirks and known gotchas.
- Leave out: anything it can read from the code, standard conventions, long tutorials and file-by-file descriptions.
- Boundaries: GitHub's analysis of agent instruction files recommends three tiers, always, ask first and never (GitHub).
- Keep it short: Anthropic targets under 200 lines per CLAUDE.md, and OpenAI says to keep AGENTS.md small.
- Keep it current: when the agent repeats a mistake, add a line; prune the file regularly.
/initwrites a starter file in both Claude Code and Codex.
The file is guidance, not enforcement. For rules that must always hold, Anthropic points to hooks and permission settings.
AGENTS.md vs skills
There is no SKILLS.md standard; the format is SKILL.md, one per skill folder, from the open Agent Skills standard that Anthropic started and dozens of tools now support (agentskills.io). The difference: instruction files load in full every session, while a skill's name and description load at startup and its body only when a task needs it. Put facts every task needs in AGENTS.md or CLAUDE.md, and step-by-step procedures in skills. One gap for teams using both agents: Claude Code reads skills from .claude/skills/ and Codex from .agents/skills/.
How should a team manage instructions?
- Commit them: AGENTS.md, CLAUDE.md and
.claude/rules/belong in the repository; CLAUDE.local.md doesn't. - Set organization rules centrally: Claude Code supports a managed CLAUDE.md, Codex admin-set instructions, and Cursor team rules that admins can enforce.
- Treat them as shared code: Thoughtworks' Technology Radar places "curated shared instructions for software teams" in Adopt and calls individual ad-hoc prompting an anti-pattern (Thoughtworks).
Poly (usepoly.co) runs Claude Code and Codex in a shared room on your repository, so one AGENTS.md with a CLAUDE.md that imports it gives both agents, and the whole team, the same rules. Any member can approve a change before it happens. Free to start. What is Poly?
Common questions
Does Claude Code read AGENTS.md?
Yes, since version 2.1.277 in September 2026, but by default only when the project has no CLAUDE.md. You can make it read both in /config under Project instructions, or import AGENTS.md from CLAUDE.md.
Should I use CLAUDE.md or AGENTS.md?
If anyone uses another agent, keep the shared rules in AGENTS.md and add a CLAUDE.md that imports it with @AGENTS.md. If only Claude Code is used, CLAUDE.md alone is fine.
Where should CLAUDE.md go?
At the project root or in .claude/, committed to git for the team. Personal instructions go in ~/.claude/CLAUDE.md or a git-ignored CLAUDE.local.md.
How long should CLAUDE.md be?
Anthropic suggests under 200 lines. Keep only lines that would change how Claude works if removed, and move longer procedures into skills.
What is the difference between AGENTS.md and skills?
AGENTS.md loads in full every session. A skill, defined in a SKILL.md file, loads only its name and description until a task needs it, so it suits longer procedures.