AGENTS.md vs CLAUDE.md: Which Agent Memory File Should You Write, and When?

If you switched from Codex to Claude Code last week and tried to copy your AGENTS.md over verbatim, you already know the answer is "kind of, but read this first." Both files solve the same problem. They live at slightly different paths, follow different precedence rules, and one is a Linux Foundation project while the other is documented by a single vendor. Choose wrong and your agent walks into a session missing half its context.

Here is the short version. AGENTS.md is the cross-vendor open standard, governed by the Agentic AI Foundation under the Linux Foundation since December 2025, supported natively by roughly two dozen coding agents. CLAUDE.md is Anthropic's project memory file, read by Claude Code and only Claude Code. As of May 2026, Claude Code does not natively read AGENTS.md, despite a GitHub issue with thousands of upvotes asking for it. The official workaround is a one-line import.

What these files actually are

Both files are persistent project context. You write them once, commit them to the repo (or stash them in your home directory), and the agent reads them at the start of every session. They give the agent the stuff you'd otherwise paste at the top of every conversation: how to run the tests, where the API handlers live, which directory to keep its hands off, what your team's commit message convention looks like.

Skills are something else. A skill is a scoped, on-demand workflow (SKILL.md plus assets, invoked by name or description match). Slash commands are tiny user-defined wrappers. Hooks are shell scripts the runtime fires on lifecycle events. Per-task instructions belong in the prompt for that task. None of those go in a memory file.

The agent's context window has a base layer (system prompt, tools) and an instructions layer that gets injected every session. AGENTS.md and CLAUDE.md are how you fill the instructions layer without typing.

AGENTS.md, in detail

The format was published in mid-2025 after OpenAI, Cursor, Amp, Google's Jules, and Factory agreed they were tired of every vendor inventing its own .cursorrules, .windsurfrules, .amp-context, and so on. The file is plain Markdown. No YAML frontmatter, no schema. The homepage example is six lines.

# AGENTS.md
## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style
- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible

In December 2025 the standard moved under the Agentic AI Foundation inside the Linux Foundation. OpenAI donated AGENTS.md, Anthropic donated MCP, Block donated Goose. AWS, Bloomberg, Cloudflare, and Google are participating. Governance is community-owned rather than vendor-owned, which matters when you're betting your team's tooling on a format.

Codex reads AGENTS.md from a layered set of locations, documented at developers.openai.com/codex/guides/agents-md. It starts at the global scope, checking ~/.codex/AGENTS.override.md first, then ~/.codex/AGENTS.md, and uses only the first non-empty file at that level. Then it walks the directory tree from the Git repository root down to your current working directory, checking AGENTS.override.md first at each level, then AGENTS.md. At most one file per directory.

Files concatenate from root downward, so a rule in services/billing/AGENTS.md overrides the same rule in the repo-root AGENTS.md whenever you're working inside services/billing/.

The cap is 32 KiB by default, controlled by project_doc_max_bytes in ~/.codex/config.toml. Once Codex hits the cap it stops adding files. Raise the limit or split instructions across nested directories.

AGENTS.override.md is the safety valve. Drop one in any directory and it replaces the AGENTS.md at that level. Useful for one-off experiments, throwaway branches, or contractors who need a different view without nuking the team's shared file.

As of May 2026 the agents.md homepage lists native support across roughly two dozen tools: Codex, Cursor, Amp, Jules, Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin, UiPath, JetBrains Junie, RooCode, Gemini CLI, Kilo Code, Phoenix, Semgrep, GitHub Copilot Coding Agent, Ona, Windsurf, and Augment Code. The list grows roughly monthly.

CLAUDE.md, in detail

Anthropic's memory documentation is blunt: "Claude Code reads CLAUDE.md, not AGENTS.md."

CLAUDE.md predates AGENTS.md by a few months and uses a more elaborate path scheme. The scopes, in load order from broadest to most specific:

1. Managed policy, deployed by IT: /Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux and WSL, C:\Program Files\ClaudeCode\CLAUDE.md on Windows. Cannot be excluded by individual settings.
2. User: ~/.claude/CLAUDE.md. Your personal preferences across every project.
3. Project: ./CLAUDE.md or ./.claude/CLAUDE.md at the repo root, checked into source control.
4. Local: ./CLAUDE.local.md, gitignored, for personal project-specific stuff like sandbox URLs.

Claude Code walks the directory tree in the opposite direction from Codex. At launch it walks upward from your cwd to the filesystem root, picking up every CLAUDE.md and CLAUDE.local.md along the way. Files in subdirectories beneath your cwd aren't loaded at launch; they get included on demand when Claude reads files in those subdirectories.

There's no hard byte cap. The docs recommend keeping individual files under 200 lines because longer files consume more tokens and reduce adherence, but Claude loads them in full regardless of length. Auto memory (the separate MEMORY.md system) does cap at the first 200 lines or 25 KB. Different file, different rules.

CLAUDE.md supports @path/to/file imports inline, with a max recursion depth of five hops. It also supports claudeMdExcludes in settings to skip ancestor files you don't want, useful when you cd into a monorepo subdirectory and another team's instructions get pulled in. Block-level HTML comments are stripped before injection, so you can leave notes for human maintainers without spending context on them.

There is no CLAUDE.override.md. CLAUDE.local.md and the @ import system cover the same ground.

Side by side

Axis	AGENTS.md	CLAUDE.md
Governance	Agentic AI Foundation (Linux Foundation)	Anthropic
Read by	Codex, Cursor, Amp, Jules, Factory, Aider, goose, Zed, Warp, Copilot Coding Agent, ~15 more	Claude Code only
Global path	~/.codex/AGENTS.md	~/.claude/CLAUDE.md
Project path	<repo>/AGENTS.md plus any subdirectory AGENTS.md	<repo>/CLAUDE.md or <repo>/.claude/CLAUDE.md
Walked chain	Root down to cwd at launch	Cwd up to root at launch; subdirs load on demand
Override file	AGENTS.override.md at any level	CLAUDE.local.md (gitignored); claudeMdExcludes setting
Size cap	32 KiB combined (project_doc_max_bytes)	No hard cap; 200-line soft target
Imports	None native	@path syntax, 5-hop recursion
Frontmatter	None	None (path-scoped rules in .claude/rules/ use YAML)
Per-task override	AGENTS.override.md	Conversation message

Which one to write

Teams running any combination of Codex, Cursor, Amp, Jules, Factory, or the other adopters should write AGENTS.md. One file, every tool reads it, governed by a foundation rather than a single vendor's roadmap.

Claude Code on its own, with no plans to add another agent? CLAUDE.md is fine alone. You get path-scoped rules, the @ import system, and the managed-policy deployment path for IT teams.

For a mixed setup where Claude Code sits next to anything else, write AGENTS.md and create a CLAUDE.md whose entire contents is one line.

@AGENTS.md

Claude Code expands the import at session start and reads the whole AGENTS.md inline. Append Claude-specific instructions below if you need them.

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.
Skip `/test` after edits to `docs/`.

A symlink works on macOS or Linux (ln -s AGENTS.md CLAUDE.md), but the @AGENTS.md import is portable to Windows without Developer Mode and survives the worktree case where symlinks get awkward.

Running /init inside Claude Code on a repo that already has an AGENTS.md reads it and incorporates the relevant parts into the generated CLAUDE.md. Same for .cursorrules and .windsurfrules.

What goes inside, regardless of which file

The two files are markdown with no schema, so "what goes inside" is a style question. The patterns that hold up across both:

Build and test commands the agent will need every session. Spell out the literal invocation. pnpm test --filter=api beats run the tests.

Project conventions a code reviewer would catch on the second offense. "We use Pydantic v2 syntax, not v1." "All API routes return ApiResponse[T], never raw dicts." "Migrations live in alembic/versions/, generated with make migration name=foo."

Directory layout, at the level of "what lives where." Not a full tree. Just the parts that aren't obvious from filenames.

Guards. The directories the agent shouldn't touch, the commits it shouldn't make on its own, the third-party SDKs it should ask before installing.

Links to internal docs, with @docs/architecture.md style imports (Claude) or just markdown links (everywhere else).

What does not belong in either file

Skills are a folder, not a paragraph. The agent loads them on demand based on description match. If you find yourself writing a 50-line "here's how to deploy" section inside CLAUDE.md, that's a skill in the wrong wrapper.

Secrets shouldn't go anywhere near a markdown file you commit. Either memory file gets read into every session's context, often by tools you don't fully control. API keys belong in a .env, project secrets belong in your secrets manager.

Hooks are configured in settings.json (Claude) or ~/.codex/config.toml (Codex). The instruction layer cannot enforce shell behavior. Writing "always run make lint before commit" in CLAUDE.md and expecting it to actually run is a category error.

Per-task instructions belong in the prompt. If something only applies to the bug you're fixing today, type it into the chat. Memory files capture the rules that survive across sessions, not this morning's plan.

Skip the prose about company values, mission, or "our engineering culture." The agent doesn't care, the context tokens are expensive, and it dilutes the actual instructions.

A note on the layers above and below

Memory files sit in the middle of an agent's customization stack. Above them is the prompt, which is per-task and ephemeral. Below them is the skill layer, which packages repeatable workflows (a skill for cutting releases, a skill for triaging Sentry alerts) into reusable folders with their own assets. Memory files handle the "always know this" layer between the two.

Knack is the skill manager I've been using for the skill layer. It authors SKILL.md files in the open Anthropic skills standard, which Codex now also reads natively. The two concerns are complementary: AGENTS.md and CLAUDE.md cover persistent memory above, skills cover on-demand workflows below. Most projects end up with one memory file at the root and a handful of skills under .claude/skills/ or .agents/skills/. For the broader context, see the Knack blog on the skills marketplace and the how-to on using Claude skills.

The take

If you only remember one thing: write AGENTS.md, then add a one-line CLAUDE.md that imports it. You get cross-vendor portability for free, and Anthropic's own docs recommend exactly this pattern. The day Claude Code adds native AGENTS.md support (the GitHub issue is at four-figure upvotes and counting), you delete the CLAUDE.md and nothing else changes.

The bet underneath that recommendation is the same bet the Linux Foundation made when it took on the format: AI coding tools will continue to multiply, and the team that committed a single AGENTS.md in mid-2025 is going to spend the next three years onboarding new agents in seconds while everyone else maintains four parallel rules files.

Pick the standard. Skip the duplication.