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.
- 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.
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
-
The edit
You change the test command in
CLAUDE.mdFrom
npm testtopnpm test:unit, last sprint. -
The other file
AGENTS.mdstill saysnpm testNothing keeps two copies of the policy in step.
-
Codex starts
It reads
AGENTS.mdand runs the old commandThe command fails.
-
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
-
The policy
One short
AGENTS.mdholds the rulesLayout, exact commands, boundaries and what done means.
-
The adapter
CLAUDE.mdis one line:@AGENTS.mdThe import works on every version and never loads the file twice. Codex needs no adapter.
-
The check
/contextandcodex debug prompt-inputEach shows which files that tool actually loaded.
-
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.
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.
Keep reading.
The guides that go deeper, and the terms and comparisons next to this one.
In the docs
Does this page answer your questions?
One tap, no sign-in.
What are you here for?
What is holding you back?
How does it read?
Thanks. If you left an email, Michał will reply.
Answering your questions?
One tap each. Close whenever you like.
no sign-in
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.
Michał replies, not a bot. The address is used for this reply only.