Malhar Ujawane

Blog

Explainer·(updated October 31, 2026)

What is AGENTS.md? The README for coding agents

AGENTS.md is a Markdown file of project instructions that coding agents read before they work. What to put in it, how agents load it, and what research says.

What is AGENTS.md? The README for coding agents

AGENTS.md is a plain Markdown file in a code repository that tells AI coding agents how to work on that project: how to install dependencies, run the tests, follow the code style and avoid known traps. The official site calls it “a README for agents”, and Codex, Cursor, Gemini CLI, GitHub Copilot, Jules, Amp, Factory, VS Code and Claude Code can all read it.

It has no required fields and no schema. Agents read it as text at the start of a session, which makes it the cheapest piece of harness engineering you can do, and also the easiest one to get wrong.

Where did AGENTS.md come from?

OpenAI built it for Codex. In its Agentic AI Foundation post (December 9, 2025), OpenAI says Codex “needed a predictable way to find project-specific instructions” and that since its release in August 2025 AGENTS.md “has been adopted by more than 60,000 open-source projects and agent frameworks”. The agents.md site credits the format to a collaboration across OpenAI Codex, Amp, Google’s Jules, Cursor and Factory.

On the same day, OpenAI donated AGENTS.md to the Agentic AI Foundation under the Linux Foundation, alongside Anthropic’s MCP and Block’s goose. I covered that announcement in what MCP is. The format is now vendor-neutral, which is the point: one file instead of a separate rules file for every tool.

What should go in an AGENTS.md file?

The agents.md site lists the popular sections: project overview, build and test commands, code style guidelines, testing instructions and security considerations, plus “anything you’d tell a new teammate”, such as commit message rules and deployment steps. A short, realistic one:

# AGENTS.md

## Commands
- Install: `uv sync`
- Test: `uv run pytest -q` (must pass before you finish)
- Lint and types: `uv run ruff check . && uv run mypy src`

## Rules
- Never edit files under `generated/`; run `make codegen` instead.
- Money is integer paise. Never use floats for amounts.
- New SQL goes in `src/repo/`, nowhere else.

## Where to look
- Architecture: docs/ARCHITECTURE.md
- How we test payments: docs/testing-payments.md

What I’d keep out: a description of the folder structure the agent can see for itself, a restatement of the README, and generic advice like “write clean code”. Each line costs tokens on every session and dilutes the lines that matter.

How do coding agents load AGENTS.md?

The basic convention from agents.md: put one at the repository root, and in a monorepo add more inside packages, because “agents automatically read the nearest file in the directory tree, so the closest one takes precedence”. When instructions conflict, “the closest AGENTS.md to the edited file wins; explicit user chat prompts override everything.” The site notes that the main OpenAI repo had 88 AGENTS.md files at the time of writing.

Each agent implements the details differently, so it’s worth knowing the two most common ones.

Codex builds an instruction chain once per run, per the Codex AGENTS.md guide. It reads a global file from ~/.codex first, then walks from the project root down to the current directory. In each directory an AGENTS.override.md takes precedence over AGENTS.md. Files are concatenated root first, so closer files appear later and win, and Codex stops adding files once the total reaches project_doc_max_bytes, 32 KiB by default.

Claude Code has its own file, CLAUDE.md, and its memory docs now say it reads AGENTS.md directly (from v2.1.277) when there’s no CLAUDE.md or CLAUDE.local.md in the working directory or above it. If both exist, it reads CLAUDE.md only, unless you change the “Project instructions” setting or import AGENTS.md from CLAUDE.md with @AGENTS.md. The docs recommend keeping each CLAUDE.md under 200 lines.

How can I check which instructions an agent will see?

Here’s Codex’s discovery rule as a small script. It builds a fake home directory and repo, then prints the instruction chain an agent would assemble from two different working directories.

# agents_chain.py: which AGENTS.md text does an agent actually see from this directory?
# Implements the discovery rules in OpenAI's Codex AGENTS.md guide: global file first,
# then walk from the repo root down to the working directory; in each folder an
# AGENTS.override.md beats AGENTS.md; files are joined root-down, capped at 32 KiB.
import pathlib, tempfile

MAX_BYTES = 32 * 1024  # project_doc_max_bytes default

def chain(home, root, cwd):
    picked = []
    for name in ("AGENTS.override.md", "AGENTS.md"):  # global scope: first non-empty file
        f = home / name
        if f.exists() and f.read_text().strip():
            picked.append(f); break
    rel = cwd.relative_to(root)
    for d in [root, *[root.joinpath(*rel.parts[:i + 1]) for i in range(len(rel.parts))]]:
        for name in ("AGENTS.override.md", "AGENTS.md"):
            f = d / name
            if f.exists() and f.read_text().strip():
                picked.append(f); break
    out, size = [], 0
    for f in picked:
        text = f.read_text().strip()
        if size + len(text.encode()) > MAX_BYTES:
            print(f"  (stopped at {f}: 32 KiB limit)"); break
        out.append(text); size += len(text.encode())
    return picked, "\n\n".join(out)

tmp = pathlib.Path(tempfile.mkdtemp())
files = {
    "home/.codex/AGENTS.md": "- Use uv, never pip.",
    "repo/AGENTS.md": "# Repo\n- Test: `uv run pytest -q`\n- Never edit generated/ by hand.",
    "repo/services/payments/AGENTS.md": "- Old rule: mock the bank API.",
    "repo/services/payments/AGENTS.override.md": "- Use the sandbox bank API, never mocks.\n- Amounts are integer paise.",
    "repo/web/AGENTS.md": "- Run `bun test` here.",
}
for path, text in files.items():
    (tmp / path).parent.mkdir(parents=True, exist_ok=True)
    (tmp / path).write_text(text)

for cwd in ("repo", "repo/services/payments"):
    picked, prompt = chain(tmp / "home/.codex", tmp / "repo", tmp / cwd)
    print(f"cwd={cwd}: {[str(p.relative_to(tmp)) for p in picked]}")
    print("  " + prompt.replace("\n", "\n  ") + "\n")

Output (Python 3.13.11):

cwd=repo: ['home/.codex/AGENTS.md', 'repo/AGENTS.md']
  - Use uv, never pip.
  
  # Repo
  - Test: `uv run pytest -q`
  - Never edit generated/ by hand.

cwd=repo/services/payments: ['home/.codex/AGENTS.md', 'repo/AGENTS.md', 'repo/services/payments/AGENTS.override.md']
  - Use uv, never pip.
  
  # Repo
  - Test: `uv run pytest -q`
  - Never edit generated/ by hand.
  
  - Use the sandbox bank API, never mocks.
  - Amounts are integer paise.

Two details are easy to miss. From the repo root, the payments rules and web/AGENTS.md aren’t loaded at all, because Codex walks only down to the current directory. And in services/payments/, the old “mock the bank API” rule is gone, because the override file replaced that folder’s AGENTS.md entirely. If you start an agent at the root and ask it to change payments code, check whether your agent picks up nested files as it works (Claude Code does when it reads files in a subdirectory) or only at startup.

Do AGENTS.md files actually help?

The research is mixed, and I think that’s the most useful thing to know about the format.

  • Lulla et al. (January 2026) ran agents on 124 pull requests across 10 repositories with and without an AGENTS.md. With the file, median runtime was 28.64% lower and output tokens 16.58% lower, with comparable task completion.
  • Gloaguen et al. (February 2026) found that context files “do not generally improve task success rates, while increasing inference cost by over 20% on average”, for both LLM-generated and developer-written files. Agents followed the instructions well, but “repository overviews, although popular and recommended by model providers, are not helpful.” Their conclusion: context files are useful “for specifying non-standard coding practices”.
  • Zarzycki (October 2026) surveyed 22,854 popular GitHub repositories and found agent instructions in 26.3% of them and 59.6% of the most-starred; where both files exist, CLAUDE.md usually points to AGENTS.md. 74.0% of directives give no reason.

My reading: AGENTS.md pays off when it says things the agent can’t infer from the code (the exact test command, the non-obvious rule, the trap), and costs you when it describes what the agent could see for itself. OpenAI’s harness engineering post reached the same place from practice: a “one big AGENTS.md” failed, and a “roughly 100 lines” file used as “a map, not a 1,000-page instruction manual” worked.

What I would do

I’d write the first AGENTS.md by hand, not with /init, and keep it under 100 lines: the commands, the rules a new engineer always breaks, and pointers to deeper docs. I’d give each rule its reason in a few words, since the census found most rules don’t, and reasons help the model generalize. Then I’d follow Mitchell Hashimoto’s habit from My AI Adoption Journey: add a line only when an agent actually makes a mistake.

For repos used with both Claude Code and other agents, I’d keep AGENTS.md as the source of truth and either let Claude Code read it directly or have CLAUDE.md import it. And I’d review AGENTS.md changes as carefully as CI config, because a rule file is a prompt injection surface that every agent trusts. Everything an AI coding agent does starts from this file, so it deserves the same review as code.

FAQ

Is AGENTS.md the same as CLAUDE.md?

They do the same job. CLAUDE.md is Claude Code’s own format with extra features like @path imports; AGENTS.md is the vendor-neutral one. Current Claude Code reads AGENTS.md when no CLAUDE.md is present, and many repos keep a CLAUDE.md that just imports AGENTS.md.

Does AGENTS.md have a required format?

No. The agents.md FAQ says it is “just standard Markdown” with any headings you like.

Where should AGENTS.md go?

At the repository root, with optional nested files in subprojects. Codex also reads a personal global file from ~/.codex/AGENTS.md.

Should I generate AGENTS.md with an LLM?

Use one for a first draft if you like, then cut it hard. Gloaguen et al. found LLM-generated context files didn’t improve success rates and raised cost; the lines worth keeping are the ones a model couldn’t have guessed.

Will the agent run the commands listed in AGENTS.md?

Usually, yes. The agents.md FAQ says agents will try to run the relevant checks you list and fix failures before finishing.

Sources

Get new posts in your inbox

© 2026 Malhar Ujawane. Built with Astro.