Everyone argues about whether to write an AGENTS.md. Almost nobody looks at what the good ones actually say. So I pulled the file from the most-starred open source projects that ship one and read all ten side by side.
They agree on a shape. It is not the shape most people write.
How I picked them
I fetched AGENTS.md from around 60 of the most popular OSS repositories, dropped the ones that were empty or just a pointer to another file (a surprising number are under ten bytes long), and kept the ten highest-profile projects with a real, substantive file. Frameworks, inference engines, AI agents, web tooling. Star counts are approximate and the sample is broad rather than exhaustive, but the patterns held with almost no exceptions.
| Project | What it is | ~Stars | Tokens | Headings |
|---|---|---|---|---|
| n8n | Workflow automation | 122k | 3,200 | 24 |
| langchain | LLM framework | 115k | 3,600 | 27 |
| browser-use | AI browser agent | 72k | 9,600 | 106 |
| OpenHands | AI dev agent | 62k | 6,700 | 29 |
| lobe-chat | AI chat UI | 60k | 1,800 | 17 |
| react-router | Web routing | 55k | 1,800 | 13 |
| vLLM | LLM serving | 53k | 1,200 | 32 |
| Astro | Web framework | 52k | 1,900 | 14 |
| codex | AI coding agent CLI | 42k | 5,400 | 26 |
| prisma | Database ORM toolkit | 40k | 7,100 | 2 |
The shared skeleton
Across all ten, the same ingredients show up:
- Runnable commands: 10/10. Every file contains shell blocks with build commands, and all ten spell out test and lint commands too. This is the core job of the file.
- Code conventions: 10/10. Naming, formatting, typing, the patterns this codebase expects.
- Environment setup: 10/10. How to install dependencies, which package manager, which language version. Many name the tool explicitly (uv, pnpm, poetry).
- A map of the repo: 9/10. Where things live, especially in the monorepos. langchain, Astro, and prisma all walk their package structure.
- Direct address to the agent: 8/10. These files talk to the model in the second person. "When you", "you should", "do not".
- PR and commit rules: 6/10. How to shape a change, commit message format, what a good PR looks like.
If you want a template, that is the template. Five things show up in all ten: build commands, test commands, lint rules, environment setup, and code conventions. Everything else is where they diverge.
Which file has what
Here is the breakdown, project by project, ordered by stars.
| Project | Build | Conv | Test | Lint | Env | Struct | Agent | PR | Sec | Nest | Over | Total |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| n8n | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 11/11 |
| langchain | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 11/11 |
| browser-use | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | ✓ | ✓ | ✓ | 10/11 |
| OpenHands | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | · | 9/11 |
| lobe-chat | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | ✓ | ✓ | · | ✓ | 9/11 |
| react-router | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | · | · | · | · | 6/11 |
| vLLM | ✓ | ✓ | ✓ | ✓ | ✓ | · | ✓ | ✓ | · | · | · | 7/11 |
| Astro | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | · | · | · | 7/11 |
| codex | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | ✓ | · | 9/11 |
| prisma | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | ✓ | ✓ | · | 9/11 |
| Total | 10 | 10 | 10 | 10 | 10 | 9 | 8 | 6 | 6 | 5 | 4 |
Columns: Build (build commands), Conv (code conventions), Test (test commands), Lint (lint or format rules), Env (environment setup), Struct (repo structure map), Agent (speaks to the agent directly), PR (PR or commit rules), Sec (secrets or security), Nest (nested files), Over (project overview).
A few things fall out of the grid. Five columns are full: every file carries build commands, test commands, lint rules, environment setup, and code conventions. That is the real floor. Only n8n and langchain hit all eleven, and langchain gets there by being byte-identical to its CLAUDE.md, so it is really one file doing double duty. At the other end, react-router is the leanest of the ten at 6 of 11, sticking to commands, conventions, setup, and structure. The variation lives almost entirely in the back half of the grid: PR rules, security, nesting, and an overview.
What they leave out is the interesting part
The first surprise is that they barely describe the project. Only 4 of the 10 have any kind of overview or "about" section. The top files assume the agent can read the README and the code, so they do not re-explain the product. AGENTS.md is for doing, not for knowing.
The second surprise is that the spec's headline feature is underused. AGENTS.md is designed to nest, with the nearest file in the tree winning, which is sold as the way to give each package its own context in a monorepo. Only half the files (5 of 10) nest at all. Even large monorepos mostly keep a single root file.
The third is that security is not standard. Despite all the noise about agents leaking secrets, only 6 of the 10 say anything about secrets or credentials, and none of the ten give it a dedicated section. Make of that what you will.
They are mostly lists of what not to do
The strongest shared trait is tone. These files are not gentle documentation. They are guardrails.
The average count of "do not", "never", "must not", and "avoid" across the ten is about twelve per file. OpenAI's codex file has thirty-five. Astro opens not with a description but with four instructions about how to behave before writing any code: think first, keep it simple, make surgical changes, stay goal-driven. The content these teams care about most is the content that stops the agent from doing the wrong thing.
vLLM takes it furthest. Its file opens with a mandatory contribution policy aimed squarely at agents: check for duplicate work, "no low-value busywork PRs", fail closed when unsure. That is not onboarding. It is a project defending itself against AI slop, written into the same file that configures the agents producing it.
So what
If you are writing your first AGENTS.md, the lesson from the top of the ecosystem is clear. Skip the prose about what your project is. Write the commands exactly. Write the conventions plainly. Then spend most of your effort on the constraints: the things the agent must not touch, the patterns it must not invent, the checks it must not skip.
Which leads to the uncomfortable part. The bulk of a good AGENTS.md is constraints, and constraints are exactly the content that rots without anyone noticing. A "never edit the generated client" that points at a directory you renamed last quarter. An "always run this command" that no longer exists. The file that was supposed to keep the agent in line slowly stops matching the repo, and nothing errors when it does.
The top projects have figured out what to put in the file. Almost none of them have figured out how to keep it true. That second problem is the one we work on at Blume.
One question to leave you with: when did anyone on your team last read your AGENTS.md against the actual repo?