Skip to content

AGENTS.md: what goes in ours, and the bug behind each rule

18 Nov 2026

·

8 minute read

AGENTS.md is a Markdown file at the root of a repository that coding agents such as Codex and Claude Code read before they start work. Put in it what an agent cannot work out from the code: what the project is and what must never break, how to build and check it, what needs a person's approval, and the mistakes it must not repeat. Ours at Elroot Labs runs to 395 lines. Below is what is in it, the size it costs us, and the bug behind each rule we quote.

How Codex and Claude Code read AGENTS.md

The two tools find the file differently, and the difference decides how you lay it out.

Codex walks from the repository root down to the folder you are working in, takes at most one AGENTS.md per folder, and lets files closer to your folder override earlier ones. It stops adding files once their combined size reaches a limit, 32 KiB by default.

Claude Code reads CLAUDE.md files at the start of every session. It can read AGENTS.md directly when no CLAUDE.md exists, or a CLAUDE.md can import it with an @ path. Ours is the import: our CLAUDE.md is a single line, @AGENTS.md, so every agent reads the same file and there is one copy to keep true. Until 18 November our CLAUDE.md was a separate 25-line file.

What goes in ours, section by section

SectionLinesWhat it holds
Standing rules20180 rules in 8 groups, each from a real bug or wrong answer
Current state50A dated snapshot: branches, what is live, what is waiting
Non-negotiables30The owner's hard rules: what never ships, what is never invented
Stack25Frontend, backend, database, hosting, and how to install locally
Sub-agents and models23Which jobs go to which model, and what is never delegated
Owner-only actions16Decisions an agent must ask for by name
Where to start10Which files to read, in order
Marketing work10The skills to load before any marketing task
Shipping10Branches, and how a change reaches the live site
What this is7One paragraph on the product and what must never break
Blog on the new site4Where posts live and what not to edit by hand

Bar chart of our AGENTS.md lines by section: standing rules 201, current state 50, non-negotiables 30, stack 25, sub-agents 23, owner-only actions 16, and four short sections of 10 lines or fewer.

Half the file is standing rules, which is where the value is. The next largest part, current state, is the one most guides tell you to leave out, and we keep it for a specific reason: several agent sessions work in this repository at the same time, and each needs to know what is live and what another session is changing before it starts. The file's own instruction keeps that part honest: "This is a snapshot, not a log: replace it, never append to it." The dated log goes to a separate history file, and the snapshot is meant to stay under about 30 lines.

Each standing rule names the bug that produced it

The rules are grouped as Verify, Build, Ship, Security, Work, Cloudflare Workers, Web UI and This project. The general groups came from earlier projects; the last group is headed "each from a real bug or wrong answer here". A few, quoted as they stand:

  • "The Worker has no filesystem at run time ... /api-v2/blog-posts failed on every request from 16 to 18 Nov while next dev worked." Local development passed for two days while production failed every request, so the rule tells the next agent to test the way the server runs.
  • "A CSP wildcard *.example.com does not match example.com." Our security policy silently blocked every analytics hit until a fix in pull request #41.
  • "Ad domains (doubleclick, googlesyndication, googleadservices) stay blocked: #45 nearly sent visitor data to one." Pull request #45 would have done it with the owner's approval; it was dropped when the conflict with our privacy policy came up.
  • "Local OpenSSL 3 refuses TLS 1.0/1.1 itself, which looks like the server refusing." Our first security audit reported that the server refused the two old protocols; it was the test tool refusing them, and the server accepted both until we raised its minimum.
  • "Blog posts carried ~1.5 MB of unused upstream code until #48." Components imported from the template the site started from brought their JavaScript, including error-reporting and analytics libraries, onto every blog page.

A rule written with its incident does two jobs. The agent learns the mechanism, so it can spot the same bug in a new shape. And a person reviewing the file can tell which rules still describe the system and which describe something already replaced.

Claude Code's documentation says to target under 200 lines per CLAUDE.md file, because longer files use more context and agents follow them less reliably. Ours is 395 lines and 27,847 bytes. For Codex the harder number is its 32 KiB default for all instruction files combined: our root file uses most of it, which leaves little room for a nested file or a personal one before Codex stops reading.

The file grew fast. It was created on 18 November at 348 lines with 76 standing rules, and 14 commits later the same evening it was 395 lines with 80 rules. The growth came from the current-state snapshot, the search-planning rule and four new standing rules. Three of those rules came from incidents that same day (pull requests #45 and #48, and link previews on X); the fourth says where to read the live logs.

Three habits keep it from growing without limit. A rule is added only when a task taught something reusable, one bullet at a time. The history goes to its own file, so the agent file never carries the story of how a decision was made. And the file states who sees it: general-purpose sub-agents get the copy that existed when their session started, and search sub-agents get none, so anything they need goes in their prompt. That last point is the strongest argument for short: every line we add is read by every session.

What we would cut next: the four shortest sections could become two, and the Stack section repeats some of what the package files already say.

A rule in AGENTS.md is a request; the ones that matter also live in a test

Claude Code's documentation is plain about this: instruction files are context, not enforced configuration, and to block an action whatever the model decides, you need a hook. We reached the same conclusion from the other side. The rules that would hurt most if ignored are also checks that fail on their own:

  • The ad-domain rule is a worker test that fails if the security policy ever allows any of the three domains.
  • The bundle-size rule is a test on the blog route's JavaScript.
  • The image rule is enforced by the blog post gate and by the site check that runs before every release.
  • The rule that every blog topic carries a full search plan is a test that fails any backlog topic whose plan is missing a part.

The file says what to do and why; the test catches the day an agent does not read it, or reads it and decides otherwise.

What should go in an AGENTS.md file?

From what has earned its place in ours:

  1. One paragraph on what the project is and what must never break.
  2. How to install, build, test and ship it, as commands an agent can run.
  3. Where to start reading, in order.
  4. A dated snapshot of the current state, replaced after each task, if several agents work at once.
  5. The hard rules and the owner-only decisions, listed by name.
  6. Standing rules, each with the incident or mechanism behind it.
  7. Which jobs may go to sub-agents, and what they will not see.

And what to keep out: the history of decisions (a separate file), secrets of any kind, anything the code already states, and rules that no longer change behaviour.

How the agents reading this file are allowed to act is a separate question, and we answer it in our AI agent governance rules. For what else we put around the prompt and how much of it there is, see context engineering, measured in words. If you want help setting up coding agents on your own codebase, tell us about the project.

AI tools

Ask ChatGPTAsk Claude

Start with the problem that matters