AGENTS.md vs CLAUDE.md: what is the difference?

AGENTS.md vs CLAUDE.md: which tool reads which?

AGENTS.md is the convention used by Codex for project instructions. Codex looks for applicable files in the directory hierarchy around the working project and applies their guidance while it plans, edits, and verifies work. In a repository, the root file commonly contains the broad contract, while deeper files add rules for a subtree.

CLAUDE.md is the convention used by Claude Code. Claude Code loads its applicable project instructions from CLAUDE.md files and can also use user-level instructions, depending on how the installation and session are configured. The exact loading locations can differ by product version, so check the tool's own documentation when debugging a surprising result.

The practical consequence is easy to miss: adding a perfect rule to CLAUDE.md will not configure Codex, and adding it only to AGENTS.md will not configure Claude Code. Test each tool in a fresh session instead of inferring that it loaded a file.

Precedence and nesting: which instruction wins?

Instruction systems are hierarchical. A broad file near the repository root can establish defaults; a file inside a directory can add constraints for the code below it. The closer file is normally the place for narrower rules, such as “run the package-level test command” or “do not edit generated files.”

Do not treat nesting as a universal override operator. A more-specific instruction should refine a general one, not casually contradict a safety rule or an acceptance criterion. When two instructions conflict, the tool's documented precedence rules, the file locations, and higher-priority system or user instructions all matter. If the result is important, make the policy unambiguous and verify it with a small probe.

# Inspect instruction files in the current repository
find .. -name AGENTS.md -o -name CLAUDE.md

# From the project root, show their relative locations
find . -name AGENTS.md -o -name CLAUDE.md | sort

For a monorepo, a useful layout might be:

repo/
├── AGENTS.md
├── CLAUDE.md
├── services/
│   └── payments/
│       ├── AGENTS.md
│       └── CLAUDE.md
└── packages/
    └── web/
        └── AGENTS.md

The root files describe rules that apply broadly. The payments files describe payments-specific behavior. The web package may need a Codex-only addition. Keep the narrower files short enough that a maintainer can compare them during review.

How to keep one source of truth across both files

The safest pattern is not to duplicate every paragraph. Put durable, tool-neutral policy in a canonical file such as docs/ai-instructions.md, then make both adapter files point maintainers to it and contain only the details their reader needs.

# AGENTS.md and CLAUDE.md should each state:
- Read docs/ai-instructions.md before changing application code.
- Follow the repository's test and formatting commands.
- Treat generated files and secrets as protected.
- Record verification evidence in the pull request.

There are two important caveats. First, a reference is useful to a human only if the assistant actually receives the referenced content; do not assume that a sentence saying “see this file” magically imports it. If the tool does not follow references, copy the small required rule into the adapter or use an officially supported import mechanism. Second, relative paths must be correct from every directory where the file can apply.

To prevent drift, update the canonical file first, then review both adapters in the same change. A lightweight check can reject a missing adapter:

test -f AGENTS.md && test -f CLAUDE.md
test -f docs/ai-instructions.md
git diff --check

For high-risk rules, create a harmless verification task. Ask the assistant to name the applicable instruction file, explain the expected command, and make no edits. This checks loading and precedence without using a real feature branch as an experiment.

Migration: moving from one file to the other

Start by inventorying the existing file rather than renaming it blindly. Separate instructions into four groups: shared engineering policy, tool-specific behavior, directory-specific rules, and stale or unverifiable claims. Preserve the first group in the canonical document, translate the second into the destination tool's vocabulary, and place the third at the matching directory depth.

1. Record the current file path and the command used to start the assistant.
2. Copy the useful rules into a temporary comparison, then remove duplicates and outdated commands.
3. Create the destination adapter with a concise scope statement and links to shared policy.
4. Open a fresh session in the relevant directory and run a read-only loading probe.
5. Commit the migration together with a small test or documentation note that prevents accidental deletion.

If both assistants will remain in use, do not delete the original file after a successful test. Keep both filenames under version control and establish ownership in the README or contributor guide. If only one tool is used, remove the unused adapter only when you are sure another workflow does not depend on it.

Common mistakes that cause silent failures

• Renaming instead of adapting: AGENTS.md renamed to CLAUDE.md may lose Codex coverage, and the reverse loses Claude Code coverage.
• Assuming every directory applies: a file in a sibling directory does not necessarily govern your current working path.
• Contradictory duplicates: two copies of a test command can diverge and leave the assistant with an ambiguous instruction.
• Overloaded prose: long narratives bury the one command or safety constraint the assistant must not miss.
• Unverified references: links to deleted scripts, old package managers, or unavailable tools turn a correct-looking rule into bad execution.
• Testing only an existing session: a warm session may retain context that a new session will not have. Re-test after changing instructions.

A good instruction file is explicit about scope, trigger, action, and proof. Say when a rule applies, what the assistant must do, what it must not do, and which command demonstrates completion. That structure works in either filename and makes differences between Codex and Claude Code visible during review.

It is also worth distinguishing instructions from project documentation. An architecture decision belongs in the repository’s normal docs; a coding-assistant file should tell the assistant how to use that decision while working. Keep credentials, private prompts, and machine-specific secrets out of both files. Everything committed to the repository may be read by contributors, CI jobs, forks, or automated tooling.

Finally, treat the filename as part of your integration surface. A future contributor may open the repository with only Codex or only Claude Code. A short note in each adapter explaining its reader and canonical source makes the setup discoverable without relying on tribal knowledge.