AGENTS.md vs CLAUDE.md: How to Give Claude and Codex Separate Rules in the Same Repository

Jun 22, 2026

Shiori

About This Article

This article explains the design of having both a Claude-specific and a Codex-specific configuration file in the same repository — what each file does, why separate files are necessary, and how I manage common rules without duplicating them.

The Role of Each File

CLAUDE.md is a configuration file that Claude Code loads automatically. When Claude Code finds this file at the project root, it reads it at the start of each session and treats its contents as project-specific constraints.

AGENTS.md is a configuration file that Codex (OpenAI) reads. When Codex finds this file at the repository root, it references it as rules before beginning work. Claude Code does not automatically load AGENTS.md.

Both files serve the same purpose — “here are the rules for this project” — but they are read by different AIs.

Why Separate Files Are Necessary

Claude and Codex have different capabilities and permission scopes.

For example, a rule like “ask for confirmation before running this command” maps to a specific behavior for Claude — displaying a confirmation prompt. The same rule passed to Codex may be interpreted differently because of how Codex processes instructions.

Claude is also optimized for instructions suited to real-time terminal interaction, while Codex pushes changes to GitHub asynchronously. The meaning of “run this command after the work is done” differs between the two AIs.

Passing the same instructions in identical wording to both AIs means that some instructions will be a poor fit for one of them.

Avoiding Duplication of Common Rules

Writing the same content in both files creates drift when only one copy is updated. After encountering that problem on this site, I made shared/ the source of truth for common rules and kept CLAUDE.md and AGENTS.md as runtime-specific entry points.

To address this, I use the following structure:

Project root/
  CLAUDE.md         ← Read by Claude (holds consolidated common rules)
  AGENTS.md         ← Read by Codex (Codex-specific settings + references to shared/)
  shared/
    rules/
      build-and-deploy.md   ← Stores shared constraints
      content-i18n.md       ← Stores shared conventions
      ...

CLAUDE.md contains the common rules. AGENTS.md contains a pointer to CLAUDE.md and shared/rules/ for common rules, plus only the Codex-specific settings.

What Goes in Each File

CLAUDE.md contains:

Commands that must not run, and the conditions that apply
Files and directories that must not be modified
Content style rules
Safety verification procedures

AGENTS.md contains:

References to where common rules are located (paths to CLAUDE.md and shared/rules/)
Codex-specific permission settings
Verification commands to run before pushing to GitHub

This division lets common rules be managed in one place while AI-specific behavior is documented separately.

A Note on How These Files Are Read

CLAUDE.md and AGENTS.md are read automatically by their respective AIs. Asking either AI to “ignore this rule” will not prevent the file from being loaded again in the next session.

Changing a rule requires editing the file directly. Also, because Codex does not read CLAUDE.md, the reference to CLAUDE.md must be explicit in AGENTS.md.

Summary

CLAUDE.md is the configuration file Claude Code reads automatically
AGENTS.md is the configuration file Codex (OpenAI) reads
Claude and Codex have different capabilities and permissions, which is why separate files are necessary
To avoid duplicating common rules, detailed rules are stored in shared/rules/ and both files reference that location