AGENTS.md vs. CLAUDE.md: Which File Does Your AI Coding Project Need?

You start a new project, open OpenAI Codex, and want to explain how your repository is structured. So you create an AGENTS.md.

The next day, a colleague opens the same repository with Claude Code.

Does Claude now automatically know the rules from your AGENTS.md?

No.

This is currently one of the most common pitfalls in AI-assisted software development.

Codex works with AGENTS.md by default. Claude Code, on the other hand, uses CLAUDE.md. At first glance both files serve a very similar purpose — but technically they're not identical.

And if you use multiple coding agents, you definitely shouldn't start maintaining the same rules manually in five different files. The better solution is a single, central source for shared project rules.

The short answer

If you just need a quick decision:

Recommended instruction file by coding agent

Your coding agent	Recommended file
OpenAI Codex	AGENTS.md
Claude Code	CLAUDE.md
Codex + Claude Code	AGENTS.md + a small CLAUDE.md
Multiple different coding agents	AGENTS.md as a shared base, wherever possible
Claude-Code-only project	CLAUDE.md is enough

For projects that use Codex and Claude Code together, this is currently the most sensible setup:

AGENTS.md
CLAUDE.md

The actual shared project rules live in AGENTS.md. CLAUDE.md then contains, for example, just:

@AGENTS.md

## Claude Code

Use plan mode first for larger changes.

That way you maintain the shared rules in exactly one place. Anthropic now describes exactly this setup in its official Claude Code documentation: Claude Code reads CLAUDE.md, not AGENTS.md automatically. If an AGENTS.md already exists, it can be imported into CLAUDE.md. If you use both agents on the same project and are still unsure which one fits your workflow better overall, see the in-depth comparison in Claude Code vs. OpenAI Codex: Which Coding Agent Is Better? (Read article).

What is an AGENTS.md?

Put simply, an AGENTS.md is a README for AI coding agents. It explains things to an agent that it can't reliably infer from the source code alone.

For example:

• which architecture is used
• how to start the project
• which tests need to run
• which coding conventions apply
• which directories may be changed
• which components are especially critical
• what Git commits should look like
• which commands must run before a pull request
• which changes are explicitly forbidden

A typical file might start like this:

# AGENTS.md

## Project

This repository contains a React application with a Flask API
and a MySQL database.

## Installation

Frontend:

npm install
npm run dev

Backend:

python -m venv .venv
pip install -r requirements.txt

## Tests

Before finishing any change:

npm test
pytest

## Coding rules

- Keep the existing architecture.
- No new dependencies without justification.
- Never commit secrets to the repository.
- Don't remove existing tests.
- Don't suppress errors with empty catch blocks.

The open AGENTS.md format deliberately positions README.md and AGENTS.md as complementary: README.md is for humans — quick starts, project descriptions, and contribution guidelines — while AGENTS.md provides the extra, sometimes detailed context that coding agents need.

AGENTS.md is now more than just a Codex file

AGENTS.md originally became known mainly through coding agents like Codex. Meanwhile, though, the format has grown into a much broader convention for coding agents in general.

The official AGENTS.md site describes the format as an open, tool-agnostic approach to project instructions and now lists more than 60,000 open-source projects using it. Its ongoing development is stewarded by the Agentic AI Foundation under the Linux Foundation.

That creates an important advantage: AGENTS.md isn't tied exclusively to a single AI model or vendor. That's exactly why the file works so well as a shared foundation for a modern AI coding project.

How OpenAI Codex uses AGENTS.md

Codex automatically reads AGENTS.md before starting on a task — no manual step is needed. The file is collected hierarchically: a global level under ~/.codex/AGENTS.md or ~/.codex/AGENTS.override.md, followed by project-level files from the Git root down to the current working directory.

Simplified, a repository might look like this:

project/
├── AGENTS.md
├── frontend/
│ ├── AGENTS.md
│ └── src/
└── backend/
├── AGENTS.md
└── src/

The file at the project root contains general rules, for example:

- Never commit secrets.
- All changes must be tested.
- No direct changes to production.

The backend can have additional, more specific rules, and the frontend different ones again. At every level, Codex first checks whether an AGENTS.override.md exists — if it does, it takes priority over the regular AGENTS.md at that same level. Files closer to the directory being worked on override more general guidance from higher up the tree.

There's also a context budget for these project instructions: by default, Codex collects files up to a combined size of 32 KiB (configurable via project_doc_max_bytes) and skips empty files. If you want to set up the Codex CLI on Linux, a detailed step-by-step guide with practical AGENTS.md examples is available in Install and Use the Codex CLI on Linux (Read article).

What is a CLAUDE.md?

CLAUDE.md serves a very similar purpose for Claude Code. It contains persistent instructions that Claude should take into account while working on the project.

These typically include things like:

# Project rules

## Architecture

The backend is built on Flask.
The REST API lives under src/api/.

## Database

Use MySQL.
Never modify existing migrations.
Create a new migration for schema changes.

## Tests

After backend changes:

pytest tests/

## Security

Never print credentials from .env.
Never modify production systems.
Never deploy without an explicit instruction.

Claude Code loads this information back into its context at the start of every new session. Anthropic recommends putting things in CLAUDE.md that you'd otherwise have to keep re-explaining to Claude — build commands, conventions, project architecture, or fixed working rules, for example.

Claude Code has several levels of CLAUDE.md

Claude Code has an extensive system around its instruction files. Anthropic distinguishes four levels:

Managed policy — deployed centrally by IT or DevOps, for example under /etc/claude-code/CLAUDE.md on Linux and WSL, or /Library/Application Support/ClaudeCode/CLAUDE.md on macOS. This usually holds company-wide policies that apply to every user on a machine and can't be overridden by individual project or user settings.

User instructions — ~/.claude/CLAUDE.md, for example: "Prefer detailed commit messages.", "Use pnpm instead of npm."

Project instructions — ./CLAUDE.md or ./.claude/CLAUDE.md. This file normally lives in the repository and applies to the whole team.

Local instructions — ./CLAUDE.local.md. This is where you can keep project-specific personal settings that shouldn't be shared with the team. CLAUDE.local.md should normally be excluded via .gitignore.

Claude Code loads CLAUDE.md and CLAUDE.local.md from the current working directory and every directory above it; files in subdirectories are loaded on demand as Claude reads files there. For larger projects, instructions can additionally be split across .claude/rules/ — individual rule files there can even be scoped to specific file paths, so they only load when Claude is actually working on matching files.

The key difference: Claude Code doesn't read AGENTS.md automatically

This is where the crucial trap lies.

You've meticulously maintained an AGENTS.md. It covers architecture, tests, security rules, Git conventions, and deployment rules.

You then start claude and assume Claude will take that file into account too.

You shouldn't assume that.

Anthropic's documentation states it plainly: Claude Code reads CLAUDE.md, not AGENTS.md. That's exactly why Anthropic recommends a small import file for projects that already have an AGENTS.md:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

That gives Claude Code the same shared context. Claude loads the imported file at session start, then appends the remaining, Claude-specific instructions after it.

The best structure for using Codex and Claude Code together

For a modern multi-agent project, I'd favor a structure like this:

project/
├── AGENTS.md
├── CLAUDE.md
├── README.md
├── docs/
├── frontend/
├── backend/
└── tests/

The roles are clearly separated:

README.md — for humans. Covers things like: What does the project do? How do I install it? How do I run it? How can I contribute?

AGENTS.md — shared working rules for coding agents. For example: architecture principles, build commands, test commands, security rules, Git rules, definition of done, important constraints.

CLAUDE.md — only Claude-specific additions, for example:

@AGENTS.md

## Claude Code

- Use plan mode for architecture changes.
- Use subagents for independent analysis tasks.

That way, there's exactly one shared source of truth.

Why you shouldn't copy AGENTS.md and CLAUDE.md

A bad solution would be: AGENTS.md and CLAUDE.md, each with roughly 300 nearly identical lines.

On Monday you change the test rule in AGENTS.md. On Wednesday someone adds a security rule to CLAUDE.md. Four weeks later, the two files contradict each other.

Codex gets npm test. Claude gets npm run test:ci. Codex is allowed to modify a certain directory. According to its file, Claude isn't.

Now you've created exactly the problem these files were supposed to prevent: duplicating agent rules creates configuration drift.

The more sensible architecture is:

AGENTS.md = shared source of truth
CLAUDE.md = import + Claude-specific additions

Alternative: CLAUDE.md as a symlink

Anthropic mentions a second option. On Linux or macOS, you can use, for example:

ln -s AGENTS.md CLAUDE.md

Then both filenames point to the same content. This works well when you don't need any Claude-specific additions at all.

The downside: as soon as you need Claude-specific rules, the simple symlink becomes impractical. Creating symbolic links on Windows also requires administrator rights or Developer Mode depending on configuration — which is why the @AGENTS.md import is usually the more practical choice there.

Can Codex read CLAUDE.md too?

Technically, Codex can be configured more flexibly than it first appears. OpenAI supports alternative project filenames in the Codex configuration via the project_doc_fallback_filenames option. That would let a user configure Codex to consider additional instruction files.

For a team project, though, I wouldn't rely on that. This setting might only exist on your own machine. Another developer clones the repository, uses the default configuration — and suddenly the project context is missing.

For portable repositories, this is therefore the better approach:

Codex → AGENTS.md
Claude → CLAUDE.md
Together → AGENTS.md + CLAUDE.md import

What actually belongs in AGENTS.md or CLAUDE.md?

These files shouldn't turn into an encyclopedia of your entire project. Useful content includes, for example:

Project structure

Frontend: /frontend
Backend: /backend
Tests: /tests
Docs: /docs

Technology

Frontend: React + TypeScript
Backend: Flask
Database: MySQL
CSS: Tailwind CSS

Build commands

npm install
npm run build

Test commands

npm test
pytest

Coding rules

- Reuse existing patterns.
- Don't add unnecessary dependencies.
- Prefer small, traceable changes.

Security rules

- Never commit .env files.
- Never print secrets.
- Never modify production systems.
- Never delete databases.

Definition of done — a task is only finished when:

1. the change has been implemented,
2. existing tests pass,
3. new functionality has been tested,
4. no secrets were committed,
5. git diff has been reviewed.

A definition of done like this significantly improves coding-agent workflows.

What shouldn't go in?

What you leave out matters at least as much.

No credentials

Never:

DATABASE_PASSWORD=...
API_KEY=...
SSH_PASSWORD=...

An instruction file is often committed to the Git repository. Secrets don't belong in it.

No 1000-line project documentation

In practice, a very large AGENTS.md tends to work worse than a compact file that points the agent to further documentation when needed. The official AGENTS.md site accordingly describes the file more as a map or table of contents for the repository — more detailed information belongs in structured documentation under docs/.

For example:

AGENTS.md
ARCHITECTURE.md
docs/
├── security.md
├── database.md
├── deployment.md
└── api.md

That's far more scalable. Anthropic likewise warns against letting CLAUDE.md grow unnecessarily large, recommending a rough target of under 200 lines per file — longer files consume more context and are followed less reliably. For rules that only apply to certain file types, a path-scoped rule set under .claude/rules/ is a better fit, since it only loads when needed.

AGENTS.md should be a map — not a novel

A good rule of thumb: write down in AGENTS.md what the agent always needs to know. Link out to the right documentation for everything else.

For example:

# Architecture

See docs/architecture.md.

# Database

Schema and migration rules:
docs/database.md

# Security

Security requirements:
docs/security.md

That way the agent doesn't have to load the entire architectural history of the project into its context for every small task. It saves context and reduces contradictory information.

CLAUDE.md also comes with auto memory

Claude Code now explicitly distinguishes between the instructions you write yourself and project knowledge it builds up automatically.

CLAUDE.md contains deliberately defined rules that you formulate yourself.

Alongside that, Claude Code can store its own findings in a separate auto-memory directory, typically under:

~/.claude/projects/<project>/memory/
├── MEMORY.md
├── user_role.md
├── feedback_testing.md
└── ...

There, Claude Code distinguishes four kinds of notes: information about your role and preferences, feedback and corrections, ongoing project context that Claude can't derive from the code or Git history alone, and references to external systems. Anything that's already derivable from the code, or already covered in CLAUDE.md, is deliberately not saved again.

This is an important distinction: CLAUDE.md tells Claude how to work. Auto memory stores things Claude has learned while working. The two shouldn't be confused with each other.

AGENTS.md and CLAUDE.md are not security mechanisms

This point matters a lot.

A line like "Never delete production data." is useful. But it's not a technical access control.

Claude Code explicitly treats CLAUDE.md as context, not as enforced configuration: its contents are delivered to Claude as a message after the system prompt, and there's no guarantee that every rule you write will be followed strictly in every situation. If you want to reliably block an action regardless of what the agent decides, you need a technically enforced hook, not just a text rule. The same basic principle applies to coding-agent instructions in general.

If an agent can technically reach and delete a production database, your security strategy shouldn't consist solely of the sentence "please don't delete it."

Instead, you need technical boundaries: sandboxing, filesystem permissions, separate users, minimal API permissions, restricted SSH access, Git, backups, CI/CD, reviews, approvals, isolated development environments. For a practical walkthrough of setting up exactly these approvals and security boundaries for Codex, see How to Use OpenAI Codex Safely: Git, Sandbox, Backups, and Approvals (Read article). If you're also connecting MCP servers, the same least-privilege principle applies there too — concrete hardening steps are covered in MCP Server Security: Permissions, Tools, and Risks Explained (Read article).

Instruction files complement these mechanisms — they don't replace them.

Example of a good AGENTS.md

A compact file might look like this:

# AGENTS.md

## Project

Web application with a React frontend, Flask backend, and MySQL.

## Structure

/frontend React
/backend Flask API
/tests automated tests
/docs technical documentation

## How to work

- Analyze the existing architecture first.
- Prefer small changes.
- Don't perform unnecessary refactors.
- Don't add new dependencies without a technical reason.

## Tests

Frontend:

npm test

Backend:

pytest

Relevant tests must run after any change.

## Git

- No direct changes on main.
- Never rewrite existing commits.
- Review git diff before finishing.

## Security

- Never commit secrets.
- Never print .env files.
- Never modify production systems.
- Never delete databases.
- Never deploy without an explicit instruction.

## Documentation

Architecture:
docs/architecture.md

Security:
docs/security.md

Deployment:
docs/deployment.md

## Definition of done

A task counts as done when:

- the implementation is complete
- tests pass
- there are no known regressions
- documentation was updated where needed
- git diff has been reviewed

A file like this is far more useful to a coding agent than generic sentences like "Write good code.", "Work professionally.", or "Avoid mistakes." Those statements provide almost no extra context.

Which file should you use in 2026?

That brings us to the actual decision.

You use only OpenAI Codex

Use AGENTS.md. It's the natural choice for Codex. Codex can even generate a starting skeleton for the current project via /init.

You use only Claude Code

Use CLAUDE.md. For larger projects, add .claude/rules/ and regular technical documentation as needed.

You use Claude Code and Codex

Use both AGENTS.md and CLAUDE.md — but don't maintain the rules twice. Instead: @AGENTS.md in your CLAUDE.md.

Your team uses different coding agents

In that case, I'd use AGENTS.md as the shared, as tool-agnostic as possible, base. Tool-specific files should then serve only as adapters or extensions. This reduces maintenance effort and prevents contradictory rules.

The real future isn't "AGENTS.md or CLAUDE.md"

Long-term, the decisive question probably isn't "which file is better?" at all.

It's: where does the single source of truth about how my project works actually live?

A professional repository shouldn't tie its architecture, security requirements, tests, and workflows entirely to a single AI product.

A sensible structure might therefore look like this:

README.md
AGENTS.md
CLAUDE.md
ARCHITECTURE.md

docs/
├── development.md
├── testing.md
├── security.md
├── database.md
└── deployment.md

Each file has a clear job. README.md helps humans get started. AGENTS.md provides shared agent rules. CLAUDE.md adapts those rules for Claude Code. The detailed technical truth lives in /docs.

That keeps your project understandable — regardless of whether Codex, Claude Code, or a completely different coding agent works on it tomorrow.

Conclusion: AGENTS.md or CLAUDE.md?

The answer is surprisingly clear: for Codex, you need AGENTS.md. For Claude Code, you need CLAUDE.md.

If you use both, you still shouldn't maintain two separate rule sets. The cleanest solution right now is: AGENTS.md and CLAUDE.md, with @AGENTS.md as an import inside CLAUDE.md.

That makes AGENTS.md the shared source for architecture rules, tests, security requirements, and workflows. Claude-specific quirks stay in CLAUDE.md. This avoids duplicate maintenance, contradictory agent instructions, and unnecessary context.

And that's ultimately what good AI coding projects are about: not writing as many rules as possible, but making sure every agent gets the right rules at the right time.

Frequently asked questions about AGENTS.md and CLAUDE.md

Does Claude Code read an AGENTS.md automatically?

No. Anthropic explicitly documents that Claude Code uses CLAUDE.md, not AGENTS.md. An existing AGENTS.md can still be pulled in via an @AGENTS.md import inside a CLAUDE.md file.

Does OpenAI Codex read CLAUDE.md?

Not by default. Codex automatically reads AGENTS.md or AGENTS.override.md, both globally under ~/.codex/ and hierarchically from the Git root down to the working directory. Additional filenames can be added via the project_doc_fallback_filenames configuration option, but OpenAI's documentation does not explicitly confirm support for CLAUDE.md.

Can I use AGENTS.md and CLAUDE.md at the same time?

Yes. For projects that use both Codex and Claude Code, it's actually a good idea. The shared configuration should still be maintained in one place.

Can CLAUDE.md simply import AGENTS.md?

Yes. Anthropic documents the line @AGENTS.md at the top of a CLAUDE.md file for this. Additional Claude-specific rules can follow below it.

Can I set up CLAUDE.md as a symlink to AGENTS.md?

Yes. On Linux or macOS, for example, with ln -s AGENTS.md CLAUDE.md. If you need Claude-specific additions, the import is usually more flexible.

Should AGENTS.md be committed to the Git repository?

Project-wide rules normally yes. That way every developer and agent gets the same instructions. Personal settings or confidential information don't belong in it, though.

Do passwords or API keys belong in AGENTS.md?

No. Never write secrets, passwords, tokens, private keys, or credentials into AGENTS.md, CLAUDE.md, or any other version-controlled instruction file.

Does AGENTS.md replace the README.md?

No. README.md is aimed primarily at humans. AGENTS.md provides additional context and working instructions for coding agents. The two files complement each other.

How large should an AGENTS.md or CLAUDE.md be?

As compact as possible. Anthropic recommends keeping CLAUDE.md under 200 lines per file. The same principle applies to AGENTS.md: treat it more as a map of the repository than exhaustive documentation, which belongs in structured files under docs/ instead.

Sources and fact-check

This article draws in particular on OpenAI's current documentation for Codex and AGENTS.md, Anthropic's official Claude Code documentation, and the documentation of the open AGENTS.md format.

Updated: September 2026.

Related topics

Claude Code vs. OpenAI Codex: Which Coding Agent Is Better? (Read article)

How to Use OpenAI Codex Safely: Git, Sandbox, Backups, and Approvals (Read article)

Install and Use the Codex CLI on Linux (Read article)

MCP Server Security: Permissions, Tools, and Risks Explained (Read article)