What is AGENTS.md?

AGENTS.md is an open Markdown format for agent instructions: build commands, conventions and boundaries, kept at the repository root and, for scoped detail, in subdirectories. Codex reads it before doing any work. By default Claude Code reads it only when a project has no CLAUDE.md (v2.1.277+), and Cursor reads it in the project root and in subdirectories.

Last updated
By
Published
In Polish
AGENTS.md
First set up at
Level 2, free guide
Also searched as
AGENTS.md file, agents.md convention

$59.99 once for 12 months of access. Nothing renews on its own. 30-day refund on a first purchase.

On this page Why it mattersHow each tool does itQuestions

Why it matters.

Two tools, two files, and a policy copied between them drifts. In the guide’s example one file gets the new test command and the other keeps the old one, so a Codex session runs it, sees it fail and "fixes" the failure by rewriting a test. One short AGENTS.md that the other files import keeps the policy in one place, and a load check per tool shows what each agent actually read.

One policy, two ways to keep it

The test command changes. Does every agent hear about it?

  • A file the agent reads and weighs
  • A mechanism that runs
  • What you can rely on

Two copies Drifts

  1. The edit

    You change the test command in CLAUDE.md

    From npm test to pnpm test:unit, last sprint.

  2. The other file

    AGENTS.md still says npm test

    Nothing keeps two copies of the policy in step.

  3. Codex starts

    It reads AGENTS.md and runs the old command

    The command fails.

  4. The outcome

    It "fixes" the failure by rewriting a test

    The guide’s own scenario. Nobody could say which file each agent read, because nobody had checked.

One file, one import One source

  1. The policy

    One short AGENTS.md holds the rules

    Layout, exact commands, boundaries and what done means.

  2. The adapter

    CLAUDE.md is one line: @AGENTS.md

    The import works on every version and never loads the file twice. Codex needs no adapter.

  3. The check

    /context and codex debug prompt-input

    Each shows which files that tool actually loaded.

  4. What you can rely on

    One edit reaches both tools

    Both load the same text. Whether the agent follows it stays advisory: the guide puts "never" rules in hooks, permissions and CI.

Instructions steer; they are not a security boundary. A rule that must hold moves to a deny rule, a hook or CI, and the sentence stays only as an explanation. Source: Repository context guide, 2026-09-26.

How each tool does it.

Cursor, Claude Code and Codex each name this their own way. Each note carries the date it was checked.

Cursor

Cursor supports AGENTS.md in the project root and in subdirectories (nested files combine with their parents, and the more specific one wins); Rules in .cursor/rules/ are the other mechanism.

Cursor’s docs (checked 2026-10-12) say it reads CLAUDE.md the same way and always applies it, while the agent runtime in @cursor/sdk 1.0.32 (checked 2026-09-26) loads a root and nested AGENTS.md unconditionally and CLAUDE.md only with third-party config loading on. To check your build, ask a new Agent chat which instruction files it loaded, and repeat the question after every Cursor update.

Cursor token management guide, 2026-10-12

Claude Code

By default reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md (v2.1.277+). The /config Project instructions setting claude-md-and-agents-md loads both, and a CLAUDE.md containing @AGENTS.md imports it on any version.

Sessions on Amazon Bedrock, Google Cloud, Microsoft Foundry, an LLM gateway or with telemetry off need v2.1.281. Both versions are on the latest and stable release channels since stable reached v2.1.287 (checked 2026-10-12), so only a teammate on an older build still needs the @AGENTS.md import, which works on every version.

Claude Code memory guide, Claude Code 2.1.283, 2026-09-26

Codex

The native file: Codex reads AGENTS.md before doing any work, one file per directory from the repository root down; /init creates one.

A project you mark untrusted supplies no project files (since 0.150.0). The combined files stop at project_doc_max_bytes, 32 KiB by default, and Codex cuts the deepest file first with no message; an AGENTS.override.md hides the AGENTS.md in the same directory. codex debug prompt-input prints the prompt the model sees, so you can check what loaded.

Codex AGENTS.md guide, Codex CLI 0.157.1, 2026-09-26

Questions about AGENTS.md.

Which tools read AGENTS.md?

Codex reads it natively. By default Claude Code reads it only when a project has no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md: from v2.1.277 (both release channels since stable reached v2.1.287, checked 2026-10-12), and from v2.1.281 on Bedrock, Google Cloud, Microsoft Foundry and gateway sessions; the /config Project instructions setting claude-md-and-agents-md loads both. Cursor supports AGENTS.md in the project root and in subdirectories (Cursor docs, checked 2026-10-12); run a discovery probe in a new Agent chat to see what your build loaded.

What should go in AGENTS.md?

Only lines that are true for every task and that an agent could not discover by reading the code: layout, exact commands, boundaries and what done means, in about 40 lines. Multi-step procedures belong in skills, and rules that must hold belong in hooks, permissions and CI, because instructions steer and do not enforce.

Can a repository have both AGENTS.md and CLAUDE.md?

Yes, and the safe layout keeps the policy once: put the rules in AGENTS.md and make CLAUDE.md the single line @AGENTS.md, plus any Claude-only lines. By default, adding a CLAUDE.md without the import hides AGENTS.md from Claude Code, and two copies of the rules drift.

How do I check that Codex loaded it?

Run codex debug prompt-input: it prints the model-visible prompt as JSON without calling a model, so a script can grep it. It catches the three silent failures: truncation at the 32 KiB budget, an AGENTS.override.md that shadows the real file, and a nested file that no longer loads.

Does this page answer your questions?

One tap, no sign-in.

not at all fully

Read the guides in the same words.

Open every guide with the Toolkit. Each term is defined once here, and the guides use it the same way.

$59.99 once for 12 months of access. Nothing renews on its own. 30-day refund on a first purchase.