# 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.

Published 2026-10-07 by Richard Kaminsky and Mitchell Lipyansky, the co-founders of Poly. Canonical: https://usepoly.co/claude-md-vs-agents-md
Poly is a multiplayer AI coding workspace: a shared room where your team works with one AI agent, together. Free to start: https://usepoly.co/

**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 and AGENTS.md, from Anthropic's, OpenAI's and agents.md documentation, October 7, 2026.*

|  | 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](https://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](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-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](https://learn.chatgpt.com/docs/agent-configuration/agents-md)).
- **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](https://code.claude.com/docs/en/memory)):

- **Locations,** broadest first: a managed policy file set by an organization; your own `~/.claude/CLAUDE.md`; the project's `./CLAUDE.md` or `./.claude/CLAUDE.md`; and `CLAUDE.local.md` for 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:** `@path` pulls 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](/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](https://code.claude.com/docs/en/best-practices)).

- **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](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/)).
- **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. `/init` writes 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](https://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](https://www.thoughtworks.com/radar/techniques/curated-shared-instructions-for-software-teams)).

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?](/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.

More guides: https://usepoly.co/guides · Security: https://usepoly.co/security · Pricing: https://usepoly.co/pricing