AGENTS.md vs CLAUDE.md

The question behind "AGENTS.md vs CLAUDE.md" is usually not theoretical. A team has been using Claude Code for six months. They have a CLAUDE.md that mostly works. Then Codex enters the workflow, or Cursor starts reading AGENTS.md, or a contractor uses a different coding agent. Suddenly the team has two rule files, three opinions about which one is canonical, and a growing risk that the agents receive different instructions for the same repo.

Short answer: if you run a multi-agent codebase, you usually need both. Not because duplication is good. Duplication is bad. You need both because tool-specific harnesses discover different files, and the file the harness reads is the file that shapes the session. The design problem is not whether to pretend one file can serve every tool. The design problem is how to keep both files from drifting.

AGENTS.md is the primary instruction file for OpenAI Codex. The current Codex docs describe global and project AGENTS.md discovery, including override files and fallback filenames. CLAUDE.md is the primary project memory file for Claude Code. Both are markdown instruction files. Both carry project rules, commands, style, and operational constraints. Neither enforces anything by itself. Both sit above CI, hooks, permissions, and reviews.

The dangerous move is treating them as competitors. They are adapters into different harnesses. Your job is to decide where the source of truth lives.

Do you need both?

For a single-tool solo project, maybe not. If you only use Claude Code, a project CLAUDE.md plus a global CLAUDE.md may be enough. If you only use Codex, AGENTS.md may be enough. A second file that no tool reads is just another place to rot.

For a team or repo touched by multiple agents, yes. You need both because each agent's discovery behavior matters. If Codex reads AGENTS.md and Claude Code reads CLAUDE.md, then a rule that exists only in one file exists only for one agent. That is how you get Codex using npm and Claude using pnpm. That is how you get one agent opening PRs and another pushing directly. That is how "agent behavior" becomes a lottery.

The fix is not to copy-paste blindly. Copy-paste gives you a good first day and a bad third month. The fix is to choose one of three explicit patterns.

Pattern one: AGENTS.md canonical, CLAUDE.md pointer

In this pattern, AGENTS.md is the source of truth. CLAUDE.md is either a symlink or a tiny pointer.

The symlink version:

CLAUDE.md -> AGENTS.md

The pointer version:

# CLAUDE.md

This project uses AGENTS.md as the canonical agent instruction file.
Read AGENTS.md before making changes. Tool-specific Claude Code notes live below.

## Claude Code notes
- Use project-local skills under .claude/skills/ when the user invokes them.
- Hooks are configured in .claude/settings.json.

This is the cleanest pattern for new projects. AGENTS.md is more tool-neutral as a name, and Codex treats it as the first-class project instruction file. It also maps well to the broader direction of open agent harnesses: one repo-level instruction file that multiple tools can understand, with tool-specific details kept in thin adapters.

Pros: one canonical file, less drift, easy review, easier onboarding for Codex and other AGENTS.md-aware tools. The filename says "agents" rather than "one vendor."

Cons: Claude Code users may expect rich CLAUDE.md content and miss the pointer if their tooling does not display it clearly. Symlinks can be awkward on Windows or in repos where tooling handles symlinks poorly. Tool-specific Claude Code behavior still needs a home, usually .claude/settings.json, .claude/skills/, or a short section in CLAUDE.md.

This is my default recommendation for new projects.

Pattern two: parallel files with explicit overrides

In this pattern, AGENTS.md and CLAUDE.md both exist as real files. Most rules are the same. Differences are intentional and declared.

Example AGENTS.md:

# AGENTS.md

## Project rules
- Use npm. package-lock.json is canonical.
- Run npm run build before opening a PR.
- Do not edit dist/ by hand.

## Codex-specific notes
- Nested AGENTS.override.md files may narrow rules for subdirectories.
- When instructions conflict, the closer directory wins.

Example CLAUDE.md:

# CLAUDE.md

This file mirrors AGENTS.md for Claude Code.

## Project rules
- Use npm. package-lock.json is canonical.
- Run npm run build before opening a PR.
- Do not edit dist/ by hand.

## Claude Code-specific notes
- Project hooks live in .claude/settings.json.
- Workflow-specific rules live in .claude/skills/.
- Overrides AGENTS.md only for Claude Code hook and skill behavior.

This is the pragmatic pattern for existing teams. You already have a meaningful CLAUDE.md. You add AGENTS.md without forcing a risky rewrite. The key discipline is to label differences. If CLAUDE.md contains a rule not in AGENTS.md, the file should say whether that rule is Claude-specific or a drift bug waiting to happen.

Pros: works with all tools, respects existing Claude Code setup, avoids symlink portability issues, gives each harness a place for its own semantics.

Cons: higher maintenance cost. Every cross-agent rule change has to hit both files. Reviewers must learn to ask "did the other file change too?" The files can diverge silently unless you lint or test for it.

This is my recommendation for mature Claude Code repos that are adding Codex.

Pattern three: CLAUDE.md canonical, AGENTS.md generated

In this pattern, the existing CLAUDE.md remains the source of truth, and AGENTS.md is generated from it.

A simple generated AGENTS.md might look like this:

# AGENTS.md

Generated from CLAUDE.md. Do not edit by hand.

## Shared project rules
...

## Codex-specific notes
- Codex reads AGENTS.md files from global and project scopes.
- If this generated file is stale, run npm run sync-agent-docs.

This can be the right bridge when a company has hundreds of repos already standardized on CLAUDE.md. It avoids a big-bang migration. It also makes review easier because the generated file should not receive hand edits.

Pros: low disruption, clear source of truth, easy to roll out mechanically across many repos, protects existing Claude Code habits.

Cons: generation scripts become part of the harness and must be maintained. It can hide the fact that AGENTS.md has different discovery semantics from CLAUDE.md. If the generator is naive, it will copy Claude-specific instructions into Codex where they do not apply.

This is a transition pattern, not where I would choose to end up for a new repo.

What belongs in both

Cross-agent rules belong in the canonical source and in whatever adapter files each tool reads. Examples:

- Package manager and install command.
- Build, lint, test, and typecheck commands.
- Branching and PR policy.
- Dependency policy.
- Generated-file policy.
- Security and secret-handling rules.
- Architecture boundaries.
- Source-of-truth docs.

These are not Claude rules or Codex rules. They are project rules. If they differ by agent, you probably have a bug.

What stays tool-specific

Tool mechanics should not be forced into the shared section. Claude Code hooks belong in Claude Code config. Claude Code skills belong in .claude/skills/. Codex-specific override behavior, fallback filenames, CODEX_HOME, and project_doc_max_bytes belong in AGENTS.md or Codex config references. Cursor rule globs belong in .cursor/rules.

The test is simple: if the rule describes the project, share it. If the rule describes how one harness discovers, loads, scopes, or enforces instructions, keep it tool-specific.

The boss recommendation

For new projects, make AGENTS.md canonical. Keep CLAUDE.md as a pointer plus the smallest possible Claude-specific section. That gives you a tool-neutral root file and keeps the cross-agent rules in one place.

For existing Claude Code projects, use parallel files with declared overrides first. Do not spend a week designing a generator before you know what actually diverges. Add AGENTS.md, mirror the shared rules, label the Claude-specific pieces, and watch the diffs for a month. If drift becomes painful, then move to canonical AGENTS.md or a generator.

The mistake is not picking the "wrong" file. The mistake is leaving the relationship implicit. Two instruction files with no declared source of truth are a split-brain harness.

How to keep them honest

Once both files exist, review them as one surface. A change to package-manager policy should touch both files or explain why not. A new rule in CLAUDE.md should be tagged as Claude-specific or copied to AGENTS.md. A new rule in AGENTS.md should be checked against CLAUDE.md before merge.

AgentLint helps here by treating instruction files as part of the harness rather than isolated markdown. It can flag contradictions, stale references, vague rules, missing enforcement, and cross-file drift before those differences turn into different agent behavior.