What is AGENTS.md?

What is AGENTS.md?

AGENTS.md is a Markdown file in a repository that holds instructions for coding agents, e.g. the commands that build and test the project. The agent loads the file when a session starts, so its text shapes each step of the task. Files of this kind are also called agent instruction files or rules files.

The agents.md site describes AGENTS.md as "a simple, open format for guiding coding agents." The file has no required fields, and any Markdown headings work. Several makers of coding agents shaped the format together, and the Agentic AI Foundation under the Linux Foundation now stewards it.

A README explains a project to the people who work on it. AGENTS.md holds the details an agent needs that a README usually leaves out. The agents.md site suggests a project overview and the build and test commands, plus sections on code style, testing, and security. Without exact commands, an agent has to search the code for them and can run one that does not fit, e.g. npm install in a project that uses pnpm.

How does AGENTS.md work?

AGENTS.md is plain text, and nothing in it runs on its own. The agent harness finds the file and adds its text to the model's context. A session uses the file in five steps:

1. A developer starts a coding agent in a folder of the repository.
2. The harness looks for AGENTS.md in that folder and in each folder above it.
3. The harness adds the text of each file to the context, with the root file first and the closest file last.
4. The developer's task enters the context after the instructions.
5. The model generates each tool call from the whole context, so a command named in the file can become a command the agent runs.

In a monorepo, each package can keep its own AGENTS.md in its folder, in addition to the root file. The agents.md site says the file closest to the edited code wins, and that a prompt from the user overrides both.

Codex's documentation says Codex builds this chain once per run, from the repository root down to the folder where the session starts. It reads a global AGENTS.md from ~/.codex first, and an AGENTS.override.md in any folder takes the place of that folder's AGENTS.md. A package's file loads only when Codex starts inside that package. Codex also stops adding files at 32 KiB by default.

When a project has no CLAUDE.md, Claude Code reads the AGENTS.md files in the working folder and above it at launch. It reads a subfolder's file when the agent opens a file there. This needs Claude Code v2.1.277 or later, and a CLAUDE.local.md or .claude/CLAUDE.md counts as a CLAUDE.md for this check. Each file takes part of the model's context window, so choosing what goes in it is part of context engineering.

What is an example of an AGENTS.md file?

Here is an illustrative example. Acme Co. sells furniture online. A developer at Acme adds this AGENTS.md to the root of the web store's repository:

# AGENTS.md

## Setup
- Install dependencies with `npm ci`.

## Checks
- Type check: `npm run typecheck`
- Unit tests: `npm test`
- Checkout smoke test: `npm run test:e2e -- checkout.spec.ts`
- Run all three checks before you report that a task is done.

## Rules
- Do not edit files in `tests/e2e/` to make a test pass.
- Store prices as integers in cents.

The developer then asks a coding agent to "Let customers edit their delivery address during checkout." The session runs in four steps:

1. The harness adds the text of the file to the context, ahead of the request.
2. The agent edits checkout/AddressForm.tsx, runs npm run typecheck and npm test, and both pass.
3. The agent runs the checkout smoke test that the file names, and the test finds 0 items in the cart instead of 2.
4. The agent changes the address handler so it keeps the cart, and all three checks pass on the rerun.

The unit tests passed on the broken change, because none of them checked the cart after an address change. This example is simplified. A real AGENTS.md would also describe the project's layout and how to run the tests without production secrets.

Should AGENTS.md say how to test the project?

AGENTS.md should list the exact commands that test the project. The agents.md site says that when the file lists test commands, the agent "will attempt to execute relevant programmatic checks and fix failures before finishing the task." A useful testing section covers four things:

• Exact commands. The file names the command for the whole suite and for one test file, e.g. npm test -- cart.test.ts.
• A check that runs the software. A smoke test starts the app and tries one real workflow, e.g. a checkout. For a command-line application, the check runs the built tool with real arguments.
• What finished means. The team's definition of done lists the checks that must pass on the final code.
• What not to change. The file names the tests and fixtures that the agent must not edit to make a check pass.

An instruction in AGENTS.md is a request, not a check. Claude Code's documentation says Claude treats its instruction files "as context, not enforced configuration." An agent can skip a listed command and still report that the task is "done." That report, with no passing run behind it, is a false completion claim.

Checks that must run belong on a trigger outside the model. An agent hook, e.g. a Stop hook, can run the tests when the agent tries to end its turn. A pre-commit hook runs them before Git records a commit, unless the commit uses --no-verify. AGENTS.md then tells the agent what to run, and the hooks run the same checks whether or not the agent did.

What can go wrong with instruction files?

An instruction file can fail in these ways:

• The model skips a rule. A long or vague rule competes with the rest of the context. Claude Code's documentation suggests keeping each CLAUDE.md under 200 lines, because longer files "consume more context and reduce adherence."
• The file goes stale. The build changes and the file does not, so the agent runs a command that no longer works.
• Two files disagree. A root file and a package file can give different rules for the same step. The package file comes last, but that place does not force its rule to win. Claude Code's documentation warns that Claude "may pick one arbitrarily."
• The file never loads. Each tool reads its own list of file names. By default, Claude Code reads only CLAUDE.md when a project has both files, so rules kept only in AGENTS.md never reach it. Setting Project instructions to claude-md-and-agents-md in /config makes Claude Code read both, as does an @AGENTS.md import in CLAUDE.md.

A rules file backdoor hides instructions in a rules file, e.g. with invisible Unicode characters, so the agent writes harmful code while it appears to follow the rules. This attack is one form of prompt injection, so changes to instruction files need the same review as code.

How is AGENTS.md different from CLAUDE.md and rules files?

AGENTS.md is one shared file that many coding agents read. CLAUDE.md is the instruction file written for Claude Code, and the other rules files are each written for one tool. The files compare on these points:

The formats overlap, because Cursor and GitHub Copilot also read AGENTS.md. A team can keep shared rules in AGENTS.md and add a CLAUDE.md whose first line, @AGENTS.md, imports that file. The lines below the import hold the instructions for Claude Code.

FAQs

Is AGENTS.md a standard?

AGENTS.md is an open format stewarded by the Agentic AI Foundation under the Linux Foundation, not a schema that a tool checks. It has no required fields, and each coding agent reads its own list of file names.

Does a repository need both AGENTS.md and CLAUDE.md?

A repository usually needs both AGENTS.md and CLAUDE.md only when Claude Code needs instructions that the shared file leaves out. Claude Code reads AGENTS.md when no CLAUDE.md exists. When both exist, the CLAUDE.md can import AGENTS.md so the shared rules still load.

Where should AGENTS.md live in a monorepo?

AGENTS.md in a monorepo usually sits at the repository root, with another AGENTS.md inside each package that needs its own commands. The package file comes later in the context, so agents usually favor it, but a direct conflict with the root file can still go either way. Codex loads it only when the session starts inside the package.

How long should AGENTS.md be?

AGENTS.md should hold only the facts an agent needs on each task, e.g. the build and test commands. Claude Code's documentation suggests keeping each CLAUDE.md under 200 lines, and Codex stops adding files at 32 KiB by default. Longer files use more context and are followed less reliably.