Skip to content
Mia Automation
NLEN Sign in Put Mia to workGet started

AGENTS.md Explained: One Instruction File for Codex, Claude Code and Other Agents

AGENTS.md is a plain Markdown file in your repository that tells coding agents how to work on the project: which commands to run, which rules to follow, what done means. Codex reads it before every task. Claude Code reads it too, but only when the project has no CLAUDE.md; if it has one, add the line @AGENTS.md to CLAUDE.md. We tested all three cases and include a template you can copy.

AI agents and agentic workUpdated 5 min read

Tested by us on 11 November 2026.

What AGENTS.md is

The format's own site calls it a README for agents: a predictable place for the build steps, tests and conventions an agent needs, kept out of the README that humans read. It has no required structure. Headings and bullet lists work best, because agents scan them the same way people do. The site lists dozens of tools that read it, including Codex, Jules, Aider, goose, opencode, VS Code, Cursor, Gemini CLI and Zed (checked November 11, 2026).

Animated diagram: one AGENTS.md file feeding four targets in turn: Codex reads it directly, Claude Code reads it directly when there is no CLAUDE.md, Claude Code with a CLAUDE.md needs the line @AGENTS.md, and other agents read it too.
One file, several readers. The only special case is Claude Code in a project that already has a CLAUDE.md.

How Codex reads AGENTS.md

Codex builds an instruction chain once per run, according to its documentation. It starts with a global file in your Codex home folder (~/.codex/AGENTS.md, or AGENTS.override.md if that exists), then walks from the project root down to your current folder and takes at most one file per folder. Files closer to where you work come later in the chain, so their guidance wins. Codex stops adding files once the total reaches 32 KiB by default; the setting is project_doc_max_bytes. In the CLI, /init writes a first AGENTS.md for you.

How Claude Code reads AGENTS.md: our test

Claude Code's own instruction file is CLAUDE.md. Since version 2.1.277 it can read AGENTS.md instead, but by default only when no CLAUDE.md or CLAUDE.local.md exists in your working folder or above it. Your personal ~/.claude/CLAUDE.md doesn't count for that check. We tested that behavior instead of taking it on trust.

We wrote one rule into AGENTS.md: the project codeword is KIWI-42. Then we asked Claude Code for the codeword in three setups, with all tools switched off so it could only answer from its instructions.

Test matrix with three rows. Only AGENTS.md: the answer was KIWI-42. AGENTS.md plus a CLAUDE.md without an import: the answer was NONE. A CLAUDE.md starting with @AGENTS.md: the answer was KIWI-42.
One run per case, November 11, 2026.

The middle row is the trap. A teammate adds a small CLAUDE.md for their own notes, and from that moment Claude Code stops reading the shared AGENTS.md, without a warning in non-interactive mode. A CLAUDE.local.md has the same effect. The fix is one line at the top of CLAUDE.md:

markdown
@AGENTS.md

# Claude Code only
- Use plan mode for changes that touch more than three files.

CLAUDE.md that pulls in the shared file. Claude Code expands the import when it loads CLAUDE.md.

You can also change the default in Claude Code's settings: under Project instructions, the value claude-md-and-agents-md loads both files in every folder. The import is easier to see in a code review, so that's what we use.

A template to start from

Keep it short and concrete. Commands an agent can run, rules it can check, and a definition of done. This is the shape we start from; replace the project details with yours.

markdown
# AGENTS.md

## Project
Invoice tool for a small business. Node 22, no framework.

## Commands
- Install: `npm install`
- Test: `npm test` (must pass before you say a task is done)

## Rules
- Never send email or call payment APIs. Write drafts to `drafts/`.
- Dates as DD-MM-YYYY in anything a customer sees.
- Ask before adding a dependency.

## When you finish
Report what changed, which tests ran, and what is still open.

Starter AGENTS.md. Copy it to the root of your repository.

How we keep one source for several agents

We work with Claude Code, Codex and other coding agents side by side, and hand-maintained copies drifted apart within weeks. Now one source file holds the shared rules, and a small generator writes the right file for each tool: CLAUDE.md for one, AGENTS.md for the other, each with a short block about the tools that agent has. The generator keeps every output under 6,000 tokens; a test run came out at 3,883. It also strips lines that contain server names, addresses or keys, and refuses to write if the result looks too much like a private instruction file. We tested it on 16 real setups with 63 of 63 checks passing (October 2026).

For a single repository you don't need a generator. Keep the rules in AGENTS.md, make CLAUDE.md a one-line import, and review both in the same pull request.

Questions

What is AGENTS.md?

A Markdown file in your repository with instructions for AI coding agents: commands, conventions and rules. Codex, Claude Code and many other tools can read it.

Does Codex use AGENTS.md?

Yes. Codex reads a global AGENTS.md from its home folder and then one file per folder from the project root down to where you work, up to 32 KiB by default. /init in the CLI creates one.

Does Claude Code read AGENTS.md?

Yes, from version 2.1.277, but by default only when there's no CLAUDE.md or CLAUDE.local.md in your folder or above it. With a CLAUDE.md, add @AGENTS.md to it. Our test confirmed both cases.

AGENTS.md or CLAUDE.md?

Use AGENTS.md for rules every agent should follow and keep CLAUDE.md for Claude-specific notes, with an import line at the top. Then there is one source for the shared rules.

How long should AGENTS.md be?

Short enough to read in a minute. Anthropic recommends keeping CLAUDE.md under 200 lines, and Codex stops reading at 32 KiB by default. Move details that only matter for one folder into a file in that folder.

Sources