AGENTS.md Field Notes

OpenAI published the format in August 2025, shaped together with Amp, Google's Jules, Cursor, Factory and others. That December it was donated, alongside MCP (see No. 1), to the new Agentic AI Foundation (AAIF) under the Linux Foundation, so it now belongs to no single company. According to the official site, more than 60,000 open-source projects use it and over 30 agents and IDEs can read it.

The difference from a README is the reader. A README is for people: what the project is and how to use it. AGENTS.md is for an agent doing the work: which command proves a change is right, what it must never touch. As the official site puts it, the agent-specific detail gets its own home instead of cluttering the README.

• Some things can't be inferred — “this HTML is generated, don't edit it” or “a person signs off before anything goes live” appear nowhere in the code
• Inference costs time and money — hunting for how to run the tests means opening file after file and trying things that fail. One written line saves all that
• Instructions drift between people — moving spoken reminders into a file means every teammate's agent, whichever tool it is, follows the same rules

Think of it as onboarding notes for a new colleague, with one difference: this colleague reads every word, every time, and follows it quite literally. That is exactly why it has to be short and precise.

A simple test: have you told an agent the same thing twice? If so, you will be saying it a third time. That is the moment to add one line to AGENTS.md, and the least wasteful way to grow the file.

• Give commands exactly as they run — not “run the tests” but npm test -- --run. Agents really do execute what you write
• Add the reason in a few words — “generated, don't edit (fix build.py instead)”. With the reason, the agent handles similar cases you never wrote down
• Pair every don't with what to do instead — a bare prohibition sends the agent looking for another way round
• Keep it short — Claude Code's documentation suggests under 200 lines for a CLAUDE.md; Codex caps what it reads at 32 KiB by default. Longer files are followed less reliably, and you pay for them every session
• No secrets — passwords and API keys never belong in the repo, and this file is shared with everyone
• Enforce what must never happen — AGENTS.md is context, not configuration; it has no power to stop anything. Use branch protection to keep changes off main, and CI or hooks (such as Claude Code's hooks) to keep formatting intact

In a monorepo, subfolders can carry their own AGENTS.md. The official rule: the nearest file takes precedence, and your request overrides them all. OpenAI's own main repository reportedly has 88 of them.

With Claude Code, an AGENTS.md is read directly when there is no CLAUDE.md. To keep both, the documented approach is a one-line @AGENTS.md import at the top of CLAUDE.md, with Claude-only instructions below it. A symlink (ln -s AGENTS.md CLAUDE.md) also works, but if anyone clones on Windows, the import is safer.

As an example, here is the AGENTS.md we would put in this site's own repository, kiji-site: a small repo where a single Python file generates pages in three languages, published on Cloudflare Pages. From building this blog with AI, I kept only what I kept having to explain and the mistakes that nearly happened.

What is left out matters just as much. No project tour: nothing like “written in Python” or “blog.html lists the posts”. Anything the agent can see by opening a file, it will read for itself. At around 30 lines, the file is also the size the research in the next chapter points to.

The ETH paper explains why: agents follow the instructions faithfully and test and explore more, which makes the task itself harder. More text does not mean better results.

The practical lesson: don't commit a file generated by /init or similar as it is. If you generate one, read it and delete every line the code already makes obvious. That is the most reliable way to use AGENTS.md today.

The third paper is a preprint by an independent researcher. Every figure holds only under its own experimental setup.

• What you can read in the code (the project overview, the language, the folder layout) — already unnecessary today, and the research says it doesn't help
• What you can find out by trying (build and test commands, how to run it locally) — as models get smarter, faster and cheaper, searching costs less and less. Writing it down becomes purely a way to save time and money
• Intent that is written down nowhere (why it was done this way, what must never happen, who decides) — no amount of reading code or history will surface it. It isn't a question of intelligence; the information simply isn't there

Think of people. However brilliant an engineer is, on their first day in a new job they don't know that “we never touch the production database on Fridays” or that “changes to this table need sign-off from finance”. The best engineers are the ones who ask about those rules first.

What will change is the form. There are already ways for agents to note what they learn (such as Claude Code's auto memory), instructions loaded only when needed (skills), and mechanisms that enforce (hooks and CI), so less needs to go into one AGENTS.md. Still, a place where people write down what people decided, and where people and AI read the same thing, should remain, for the same reason the README never went away.

This chapter is the author's reading of the facts above.