AGENTS.md for OpenAI Codex: What Works, What Doesn't, and How It Differs from Claude

AGENTS.md became the cross-tool standard for project-level AI agent instructions. Both Claude Code and OpenAI Codex read it, both treat it as authoritative project context. But they read it differently, apply it differently, and respond to the same instructions in measurably different ways.

If you are maintaining a single AGENTS.md that needs to work across both tools — or if you are switching from Claude Code to Codex — this guide covers the practical differences that affect daily output.

What Codex Actually Reads

OpenAI Codex (the cloud-based coding agent, not the older completion model) looks for AGENTS.md in:

1. The repository root (/AGENTS.md)
2. The directory you ask it to work in
3. Any parent directory up to the repo root

The lookup is hierarchical. If you run Codex on src/components/, it reads src/components/AGENTS.md, then src/AGENTS.md, then ./AGENTS.md. All found files are combined, with more specific (deeper) files taking precedence for conflicting instructions.

This is the same lookup behavior as Claude Code, which makes a shared AGENTS.md work in principle. The differences are in how instructions are interpreted.

Instruction Interpretation Differences

Explicit commands execute more literally in Codex.

Claude Code applies contextual judgment to rule exceptions. If your CLAUDE.md says “always run tests before committing” and you tell Claude Code “just make this one quick fix,” Claude Code may proceed without tests, inferring from context that you know what you’re doing.

Codex applies rules more uniformly. The same “quick fix” instruction will more often trigger a test run because that is what the AGENTS.md says to do. This is not a bug — it is a deliberate design choice toward reliability over flexibility.

Practical implication: if you write an AGENTS.md that is too strict, Codex will follow it more literally than you intended. Write rules you actually want enforced, not aspirational rules you ignore in practice.

Negations work differently.

In CLAUDE.md, “do not commit directly to main” is reliably respected. In AGENTS.md for Codex, negative instructions need to be paired with positive alternatives to be consistently followed:

# Less reliable in Codex
Do not commit directly to main.

# More reliable in Codex
Always create a feature branch before making changes. Never push directly to main.

The positive version (“create a branch”) gives Codex a concrete action to take. The negative version (“do not do X”) leaves it to infer what to do instead, which varies.

Format specifications are followed closely.

Both tools respect format instructions, but Codex is particularly consistent about output format. If you specify “output test results in a table,” Codex will reliably produce a table. This makes format instructions more useful in Codex than in Claude Code, where the actual format sometimes drifts based on context.

Writing AGENTS.md for Codex Compatibility

A well-structured AGENTS.md that works for both tools:

# Project: [Name]

## Purpose
[One sentence on what this codebase does]

## Stack
- Runtime: Node 20
- Framework: Next.js 14 (App Router)
- Database: PostgreSQL 16 with Drizzle ORM
- Testing: Vitest + Testing Library

## Working Conventions

### Before Making Changes
1. Read the relevant existing code first
2. Check if tests exist for the area you are modifying
3. For changes larger than a single function, describe the approach in a comment before implementing

### After Making Changes
1. Run `npm run lint` and fix all errors
2. Run `npm run test` and ensure all tests pass
3. If you added new functionality, add corresponding tests

### Branch and Commit
- Always create a branch named `feature/{description}` or `fix/{description}`
- Commit messages: `type: concise description` (e.g., `fix: null check in user loader`)
- Do not squash commits — preserve the history of your changes

### Code Patterns
- Prefer named exports over default exports
- Use `const` assertions for static configuration objects
- Return early from functions instead of deeply nesting conditions
- Co-locate tests with source files

Note the structure: numbered steps for processes, short declarative sentences for patterns. This format produces consistent parsing in both Claude Code and Codex.

CI Integration with Codex

Codex runs in CI pipelines through the OpenAI Agents API. When it runs in a headless environment, AGENTS.md context is even more important because there is no interactive session to resolve ambiguity.

For CI-specific behavior, add a section:

## CI Environment

When running in CI (detected by CI=true environment variable):
- Do not ask for confirmation — make the best decision based on available context
- Run `npm run test:ci` instead of `npm run test` (no watch mode)
- Use `--reporter=json` flag for test output (machine-readable)
- Do not open browser tabs or require interactive input
- Exit with code 1 if any step fails — do not attempt to recover automatically

Codex reads this section and applies it when CI=true is set, making its behavior predictable in automated pipelines.

Security Instructions That Actually Work

Both Claude Code and Codex respect security rules in AGENTS.md, but the framing matters:

## Security Rules

The following apply to all code changes:

- Validate all user input before using it in database queries or system calls
- Use parameterized queries for all database operations — string concatenation is never acceptable
- Do not log values that may contain secrets (passwords, tokens, API keys)
- Dependencies: do not add new npm packages without listing them in this file first
- Environment variables: read from environment at runtime, never hardcode values

### Restricted Operations
These operations require explicit human approval before proceeding:
- Database schema changes (migrations)
- Changes to authentication or authorization logic
- Adding new external API integrations
- Changing CORS configuration

The “Restricted Operations” section works differently in Claude Code vs Codex. Claude Code will pause and explain what needs approval. Codex in a CI pipeline will stop and fail the run, requiring manual intervention. Both are appropriate outcomes — the key is that the behavior is explicit in AGENTS.md rather than implicit.

Testing AGENTS.md Effectiveness

The fastest way to test whether your AGENTS.md instructions are being followed:

1. Write an instruction that produces observable behavior (output format, file naming, branch naming)
2. Run a task that should trigger it
3. Verify the output matches

For Codex, test in a sandbox repository:

# Create a test task
echo "Add a utility function that validates email addresses" | codex run

# Check if it followed the naming convention in AGENTS.md
# Check if it created tests
# Check if it created a feature branch

If three simple observable rules are not being followed, longer rules lists will not help. Fix the fundamental parsing issue first (usually formatting or instruction clarity).

When to Maintain Separate Files

The multi-agent AGENTS.md works well up to a point. When the divergence between Claude Code and Codex behavior becomes significant enough that you are writing rules that actively work against one tool, split into separate files:

• AGENTS.md — shared universal rules
• CLAUDE.md — Claude Code-specific behavior (imports AGENTS.md context implicitly)

Claude Code reads CLAUDE.md preferentially when both exist. Codex reads AGENTS.md. The shared rules go in AGENTS.md, Claude-specific optimizations go in CLAUDE.md.

This setup handles cases where you want Claude Code’s more context-aware interpretation for complex judgment calls, while using Codex for its consistent, literal rule-following in CI pipelines.

Summary

The main practical differences between AGENTS.md behavior in Claude Code vs Codex:

Write AGENTS.md with numbered process steps and positive action statements. Reserve judgment calls for CLAUDE.md. Use the split-file approach when behavioral differences require different instructions for each tool.