AGENTS.md vs CLAUDE.md for Production Coding Teams

The Verdict: One Contract, One Adapter

Production teams should put shared coding-agent rules in AGENTS.md, then make CLAUDE.md import that contract and add only Claude-specific behavior. That gives Codex, Claude Code, and any future coding agent the same repository truth without forcing every tool into the same configuration model.

The rule is simple:

• AGENTS.md: repository contract for agents. It holds build commands, test commands, repo layout, review expectations, security boundaries, and directory-specific rules.
• CLAUDE.md: Claude Code adapter. It imports AGENTS.md, then adds Claude-specific memory, interaction, path-scoped rules, and settings notes.
• .claude/settings.json: enforcement and tool configuration for Claude Code, not prose guidance.
• CI and hooks: actual gates. Context files guide behavior, but tests, linters, permissions, and hooks enforce behavior.

That split matters when an engineering org runs both tools. Codex and Claude Code do not read the same files in the same way. OpenAI documents that Codex reads AGENTS.md before doing any work. Anthropic documents that Claude Code reads CLAUDE.md, not AGENTS.md, and recommends creating a CLAUDE.md that imports AGENTS.md when the repository already has the shared file.

The production mistake is treating this as a naming debate. It is a source-of-truth decision. If your team is already choosing between Codex and Claude Code, pair this with the production tool comparison, then standardize the repo contract so the selected tools do not learn different rules.

What Each File Actually Loads

AGENTS.md is the portable contract because Codex loads it natively and the broader coding-agent ecosystem has converged on it as an open repository instruction file. The AGENTS.md spec frames README files as human-facing and AGENTS.md as the place for build steps, tests, conventions, and agent-focused detail that would clutter a README. It also points to 60k+ examples on GitHub, which is enough adoption to treat the format as a shared repo convention rather than a one-tool preference.

Codex builds an instruction chain when it starts. At global scope, it reads from the Codex home directory, which defaults to ~/.codex unless CODEX_HOME is set. It prefers AGENTS.override.md over AGENTS.md and uses only the first non-empty file at that level. At project scope, it starts at the project root, typically the Git root, walks down to the current working directory, and checks AGENTS.override.md, then AGENTS.md, then configured fallback names. Codex concatenates from root down, so instructions closer to the working directory appear later and override earlier guidance.

One number should shape your file design: Codex stops adding project guidance when the combined project-doc size reaches project_doc_max_bytes, 32 KiB by default. You can raise the limit, but the better production move is to keep the root file tight and push local rules into nested files.

Claude Code has a different model. It uses CLAUDE.md files and auto memory. Both are loaded at the start of every conversation, but Claude treats them as context, not enforced configuration. Anthropic is explicit about the enforcement boundary: if you need to block an action regardless of what the model decides, use a PreToolUse hook.

Claude project instructions live at ./CLAUDE.md or ./.claude/CLAUDE.md; local instructions live at ./CLAUDE.local.md. Claude recommends targeting under 200 lines per CLAUDE.md file because longer always-loaded files consume context and can reduce adherence. It also supports @path/to/import inside CLAUDE.md, with recursive imports capped at four hops. That import feature is the clean bridge:

# CLAUDE.md

@AGENTS.md

## Claude Code adapter

- Use `/memory` to verify loaded project files before changing guidance.
- Use `.claude/rules/` for path-scoped Claude-only behavior.
- Treat permission changes as settings changes, not prose-only instructions.

The Production File Layout

The clean layout is a root AGENTS.md, a thin root CLAUDE.md, nested AGENTS.md files where the monorepo needs local rules, and .claude/ only for Claude-specific configuration. It is boring on purpose. Boring file placement is how you make every future task start with the same operating contract.

Use this as the starting shape:

repo/
  AGENTS.md
  CLAUDE.md
  .claude/
    settings.json
    rules/
      frontend.md
      migrations.md
  services/
    payments/
      AGENTS.md
    web/
      AGENTS.md
  .github/
    pull_request_template.md
    workflows/
      context-guidance.yml

The root AGENTS.md should be short and verifiable:

# AGENTS.md

## Repository map
- `services/web`: Next.js app and customer-facing UI.
- `services/api`: API handlers, queue workers, and integrations.
- `packages/db`: schema, migrations, and generated types.

## Build and test
- Install with `pnpm install --frozen-lockfile`.
- Run `pnpm typecheck`, `pnpm lint`, and targeted tests before reporting done.
- If database schema changes, run `pnpm db:generate` and include migration notes.

## Change rules
- Prefer small diffs that match existing ownership boundaries.
- Do not introduce a runtime dependency without explaining the production reason.
- Never read, print, or commit secrets from `.env*`, cloud credentials, or local keychains.

## Review contract
- Report tests run and tests skipped.
- Call out any behavior change that affects auth, billing, data deletion, or permissions.

Then keep CLAUDE.md as the adapter:

# CLAUDE.md

@AGENTS.md

## Claude Code specifics
- Use `.claude/rules/` for path-specific guidance instead of growing this file.
- Use `/memory` when checking which CLAUDE.md, CLAUDE.local.md, and rules files are active.
- Permission changes belong in `.claude/settings.json` or managed settings.

Nested AGENTS.md files should carry rules that are genuinely local. A payments service can require ledger tests and audit notes. A frontend package can require screenshot checks and accessibility assertions. A root file should not carry every package's edge cases because Codex has to load the useful instruction chain before it starts work.

This also makes ownership visible. Platform owns the root contract. Service owners own nested rules. Tool owners own .claude/ settings. Reviewers can tell which layer changed and why.

The Drift Check That Keeps Both Agents Honest

Instruction drift starts when a repo changes how work should be done but only one agent's file gets updated. The fix is a small CI check that treats context files like operational code.

Use a PR template checkbox:

- [ ] If build, test, review, security, or agent workflow changed, I updated `AGENTS.md`, nested `AGENTS.md`, `CLAUDE.md`, or `.claude/` settings.

Then add a lightweight guard:

#!/usr/bin/env bash
set -euo pipefail

changed="$(git diff --name-only origin/main...HEAD)"

touches_agent_surface=false
echo "$changed" | grep -Eq '(^package.json$|^pnpm-lock.yaml$|^services/.*/package.json$|^\\.github/workflows/|^\\.claude/|^scripts/|^Makefile$)' && touches_agent_surface=true

touches_guidance=false
echo "$changed" | grep -Eq '(^AGENTS.md$|/AGENTS.md$|^CLAUDE.md$|^\\.claude/)' && touches_guidance=true

if [ "$touches_agent_surface" = true ] && [ "$touches_guidance" = false ]; then
  echo "Agent-facing workflow changed without guidance update."
  echo "Update AGENTS.md, nested AGENTS.md, CLAUDE.md, or explain why the contract is unchanged."
  exit 1
fi

That check is intentionally conservative. It should not decide what to write. It should force the reviewer to ask whether the agent contract still matches the repo. The moment teams start using Codex, Claude Code, and CI agents for real work, stale setup commands and stale test commands become production defects. The agent burns time, changes the wrong package, or reports done without running the command the team actually trusts.

For Claude Code, put hard blocks in hooks and settings. Claude settings support managed, user, project, and local scopes. Project scope lives in .claude/ and is shared when committed. Local scope lives in .claude/settings.local.json and is gitignored when Claude Code creates it. Permission rules support deny, ask, and allow, evaluated in that order. That is where "never read .env" becomes a real boundary, not a paragraph the model might miss.

OpenAI's customization docs make the same operational point from the Codex side: update AGENTS.md for repeated mistakes, excessive reading, recurring PR feedback, and automation drift checks. The file should get better because the team keeps finding real friction, not because somebody wrote a grand manifesto.

What Not To Put In Either File

Always-loaded context should be short, operational, and boringly testable. Bad context files fail by becoming either policy theatre or a second README.

Do not put secrets or secret paths in AGENTS.md or CLAUDE.md. Use permission systems, local environment documentation, and secret managers. A file that tells an agent exactly where secrets live is not safer because it says "do not read them."

Do not put long architecture essays in always-loaded files. Link to architecture docs by name when the agent needs them, but keep the contract focused on what changes how work gets done. If a rule only matters for migrations, put it under .claude/rules/ for Claude and a nested AGENTS.md near the migration code for Codex.

Do not duplicate the same prose into both root files. The bridge pattern exists so the shared contract has one edit point:

# CLAUDE.md

@AGENTS.md

## Claude-specific notes
- Use path-scoped rules for large framework-specific guidance.

Do not confuse memory with guidance. Claude auto memory loads the first 200 lines or 25KB, whichever comes first, and is meant for learned patterns. CLAUDE.md is for instructions and rules. Codex memories, skills, MCP, and subagents are also complementary to AGENTS.md, not replacements for it. The repository contract should say how this repo works; memory should carry learned local context; skills should package repeatable workflows.

Do not rely on prose for enforcement. If a dangerous command must never run, use a deny rule, hook, sandbox, or CI gate. If a deploy path requires human review, enforce it in branch protection and release tooling. Context tells the agent how to behave. Controls decide what is allowed.

The Decision Rule

Use both files when the team uses both Codex and Claude Code. AGENTS.md is the source of truth. CLAUDE.md imports it and adds Claude-only behavior. This is the default for a production engineering org because tool choice changes faster than repository rules.

Use AGENTS.md alone when the repo is optimizing for multi-agent portability and Claude Code is not part of the workflow. That keeps the contract readable by Codex and the growing AGENTS.md ecosystem without adding a second file nobody owns.

Use CLAUDE.md alone only when the repo is Claude-only and the team has no near-term need for Codex, Copilot coding agent, or other agent surfaces. Even then, the moment another coding agent enters the repo, move shared rules into AGENTS.md and convert CLAUDE.md into the adapter.

The deeper rule is the same one behind CLAUDE.md file best practices: context files are not prompt decoration. They are part of the agentic repository system. They need ownership, limits, drift checks, and enforcement around the parts that can hurt production.