AGENTS.md vs CLAUDE.md: Pick One Source of Truth

The answer

Use AGENTS.md as the shared source when Codex, Cursor, or other compatible agents work in the repository.

Use CLAUDE.md for instructions that apply only to Claude Code.

Do not maintain two independent copies of the same rule. They will drift, and the agents will receive different project truth.

What AGENTS.md does

OpenAI’s AGENTS.md guide says Codex reads instruction files from the repository root toward the working directory. Instructions closer to the current file take precedence.

Cursor’s official rules documentation also supports AGENTS.md as plain Markdown project instructions.

This makes AGENTS.md useful for portable rules such as:

• build and test commands;
• repository structure;
• file ownership boundaries;
• safe commit practices;
• naming and style requirements.

Nested AGENTS.md files can narrow those rules for one directory. Keep overrides small so the effective instruction set remains clear.

What CLAUDE.md does

Claude Code loads project memory from CLAUDE.md files. Anthropic’s memory documentation describes the locations and import behavior.

CLAUDE.md is the better place for Claude-specific details such as:

• Claude Code commands used by the team;
• Claude-only hooks or subagent conventions;
• imports that depend on Claude Code behavior;
• product-specific troubleshooting notes.

Shared build commands do not become Claude-specific because Claude runs them. Keep those commands in the portable source.

Use this file split

The shared file defines repository truth. The product-specific file defines one client’s behavior.

Avoid duplicated policy

Suppose both files say how to deploy. Someone updates AGENTS.md but misses CLAUDE.md. Codex now blocks unapproved deployment, while Claude Code follows stale text.

Use one of these patterns:

1. Put all shared rules in AGENTS.md. Keep only Claude-specific rules in CLAUDE.md.
2. Import or reference the shared source when the client supports that behavior.
3. Generate both files from one controlled source, then test the generated output.

The first pattern is simplest for most repositories.

Diagnose an ignored instruction

If an agent ignores a rule, identify the file it actually loaded.

For Codex, check every AGENTS.md from the repository root to the working directory. A closer file can override a root rule.

For Claude Code, inspect the applicable CLAUDE.md hierarchy and any imports.

For Cursor project rules, confirm the file uses .mdc. The Cursor wrong-extension guide covers that exact failure.

Then reduce the rule to one direct statement and test a task that must trigger it. Do not diagnose instruction loading through a vague conversation.

The default architecture

Use a root AGENTS.md for shared repository operations. Add nested files only when a directory needs a real exception.

Keep CLAUDE.md short. Store only Claude-specific behavior there. This preserves one operational source of truth.

Next, use Claude Code hooks vs skills to separate automatic enforcement from reusable procedure. Use which coding agent should you use when the workflow itself is still undecided.