784 Ways to Say Don't: What the Biggest Repos Put in AGENTS.md (2026)

Two real AGENTS.md files side by side — neovim's single 35-word rule against Next.js's twenty-one sections — above the finding that 90% of top repos write in must/always/never and 784 don't bullets exist across them — Two correct answers to the same question. What separates them is not length or effort — it is how many times an agent has already gone wrong in that repo.

Someone on r/AI_Agents did the work nobody else had: they read the AGENTS.md of the 100 most-starred GitHub repositories that have one — about 27% of the top 1,000, by their count — and tallied what was in them.

The structural finding was unsurprising. Architecture and repo layout, how to test, build commands, dos-and-don'ts, PR etiquette, code style. The most common headings were testing, commands, project overview, architecture. Fine.

The interesting finding was the tone. Roughly 90% of those files are written in must/always/never. Across the corpus there are 784 explicit "don't" bullets, and most of them are oddly, forensically specific.

The best one they found:

"Do not claim that an interrupted or timed-out test passed."

Nobody writes that sentence in the abstract. Somebody writes that sentence because an agent did it.

1. It is not documentation. It is a scar record.

This is the reframe worth taking away, and it changes how you write the file.

A README is written outward — it explains a project to a person who has never seen it. An AGENTS.md written the same way produces a polished project overview that helps nobody, because the agent can already read your package.json, your directory tree, and your test file names.

What the agent cannot infer is the set of things it has already gotten wrong here. That is what those 784 bullets are. Read a good AGENTS.md closely and you can reconstruct the incident log: someone's agent marked a hung test as green, someone's agent force-pushed, someone's agent invented a script that does not exist, someone's agent quietly rewrote a migration.

Why the prohibitive voice actually works

The must/always/never phrasing is not authoritarianism, it is compression. "Prefer to run the full suite" is a sentiment an agent can weigh against other sentiments and lose. "Never mark a test as passing unless you saw it exit 0" is a checkable predicate with no room to negotiate. When the reader is a model that is optimising to seem finished, ambiguity is not politeness — it is an exploit.

2. Two correct files, 20x apart in length

The shortest file in the sample is neovim's, at 35 words. It is one rule, and it is worth reproducing in full because it makes the point better than any argument:

# AGENTS.md

## AI Disclosure

If AI was used in any way for a commit, add an `AI-assisted: <tool name>`
trailer to the commit message.
If the user commits manually, remind them to add it.

That is the entire file. It encodes exactly one thing the project cares about that an agent could not possibly derive on its own — a provenance convention — and it says nothing else.

Now compare Next.js. Twenty-one sections: codebase structure, build commands, bundler selection, testing, writing tests, linting and types, "prefer a throwaway worktree," PR status and CI failures, secrets and env safety, context-efficient workflows, task decomposition and verification, rebuilding before running tests, development anti-patterns. Including this, which will be familiar to anyone who has reviewed an agent's PR:

"Do NOT add 'Generated with Claude Code' or co-author footers to commits or PRs"

Both files are correct. The variable is not diligence — it is how much agent traffic the repo has absorbed and how expensive its failure modes are. Next.js has agents running through a monorepo with a Rust bundler and a CI matrix that costs real money to redo. Neovim has one convention it will not compromise on.

The right length for your AGENTS.md is the number of mistakes your agents have actually made, plus the small number of conventions they could never have guessed. Every line beyond that is something you pay for on every single session, forever.

3. The cost model nobody prices

Here is the part founders consistently miss, and it is the reason "just write a thorough one" is bad advice.

AGENTS.md is read at the start of every session. Every sentence in it is recurring spend, on every task, whether or not that sentence is relevant to what the agent is doing right now. A 400-line file explaining your architecture is not free context — it is a fixed tax levied against every bug fix, every dependency bump, every typo correction.

That is the entire design constraint of the file, and it explains the neovim answer.

It also explains why the ecosystem grew a second mechanism. A skill — SKILL.md in a folder — is loaded lazily: at session start the agent reads only the YAML frontmatter, a name and a description. The body loads only when a task actually matches. Ten skills sitting unused cost you almost nothing.

The line to draw between them

A constraint every session needs → AGENTS.md. "Never commit secrets." "Run npm run test:unit -- --coverage, not the full suite." "Migrations are append-only."
A capability you invoke occasionally → a skill folder. Your deploy sequence. The internal API nobody touches monthly. The report generator with six steps.
A fact the agent can read off the repo → neither. Delete it.

That third bullet is where most bloated files come from. If your AGENTS.md opens with three paragraphs describing a directory layout the agent will list in its first tool call, you are paying tokens to tell it something it was about to learn for free.

4. What GitHub's own numbers say

GitHub ran a larger version of this study across 2,500+ agents.md files, and the findings converge with the Reddit sample in a useful way.

Specificity beats completeness

"React 18 with TypeScript, Vite, and Tailwind CSS" outperforms a paragraph of prose about the stack. Vague helper personas — "you are a helpful coding assistant" — fail consistently. The file earns its keep on precision, not coverage.

Commands go early, with flags

The highest-performing files put executable commands near the top, complete with flags and options — not tool names. pytest -v tests/unit is usable. "Run the tests appropriately" gets ignored, because it is not an instruction, it is a hope.

Three tiers, not two

The pattern that works is always do / ask first / never do. The middle tier is the one teams skip and the one that matters most — it is where schema changes, deploys, and dependency additions belong.

The single most useful line

Across the whole corpus, the most frequently valuable boundary was the simplest: never commit secrets. If you write nothing else this week, write that one and the exact test command.

5. Don't let the agent write it

This comes up in every thread on the topic, and the mechanical reason is more convincing than the anecdotes.

Ask an agent to generate your AGENTS.md and it will produce a competent, well-formatted, three-hundred-line summary of your repository — because that is what it can see. It will describe your folder structure, list your dependencies, and characterise your test setup. All of which it could have derived on demand.

What it cannot write is the part that matters: the 784 don'ts. Those come from watching it fail. A generated file is, almost by construction, the fixed per-session tax with none of the value.

I am not aware of a rigorous public benchmark on this — practitioners report generated files performing worse and some vendor-adjacent research points the same way, but treat that as a strong prior rather than a settled number. The structural argument stands on its own: a file that only contains derivable facts costs tokens and buys nothing.

A practical middle path: let the agent draft the commands section, since it can read your scripts accurately and that part is tedious. Write the boundaries yourself, one line at a time, as things go wrong. Never accept a generated architecture overview.

6. It is now a standard, which matters more than it sounds

AGENTS.md is used by 60,000+ open-source projects and is stewarded by the Agentic AI Foundation under the Linux Foundation — the same body that now holds MCP and, as of this week, Agent2Agent. It is read by Codex, Cursor, Gemini CLI, Jules, Copilot's coding agent, Aider, goose, opencode, Zed, Devin, Windsurf, JetBrains Junie, and a long tail of others.

We wrote two days ago about every agent protocol landing under one roof. This is the same consolidation showing up at the file level, and it has a concrete payoff: one file, not five.

The failure mode it replaces is real and expensive. You tighten a boundary in CLAUDE.md, forget .cursorrules, switch tools mid-week, and the agent that did not get the update runs the destructive command. Rule drift across CLAUDE.md, .cursorrules, .windsurfrules, and copilot-instructions.md is the single most reported operational complaint from teams running more than one agent — several people are shipping sync harnesses purely to solve it.

If you are starting now, the correct move is boring: make AGENTS.md the source of truth and generate the tool-specific files from it. A ten-line script beats remembering.

7. What it will not do

Two honest limits, because the file is being oversold in places.

It is not memory. AGENTS.md is static. It does not know that PR #184 settled the Postgres-versus-Mongo argument three months ago, so your agent will cheerfully re-propose Mongo in a fresh session, and a stale "we use X" line will be served with total confidence long after X is gone. That is a genuinely unsolved gap — several people are building decision-memory tooling against it — and no amount of careful writing closes it.

It does not constrain anything. Every line is a suggestion to a probabilistic system. "Never force-push" in a markdown file is a request; a hook that blocks git push --force is a control. Teams confusing the two is a pattern we covered in AI Agents Need Permission Systems, Not Better Prompts, and the last twelve months have not changed the conclusion. AGENTS.md reduces the rate of the mistake. It does not remove the possibility.

8. The file to write this afternoon

If you have no AGENTS.md, do not start from a template. Start from this, and let it grow only when something goes wrong.

# AGENTS.md

## Commands
- Install: `pnpm install --frozen-lockfile`
- Dev: `pnpm dev`
- Test (default): `pnpm test:unit`
- Test (single file): `pnpm test:unit -- path/to/file.test.ts`
- Typecheck: `pnpm typecheck`
- Lint: `pnpm lint --fix`

## Always
- Run `pnpm typecheck && pnpm test:unit` before saying a change is done.
- Match the conventions of the file you are editing over any global style guide.

## Ask first
- Adding a dependency.
- Changing anything in `prisma/migrations/` or `src/db/schema.ts`.
- Touching `.github/workflows/` or anything under `infra/`.

## Never
- Commit secrets, `.env` files, or credentials of any kind.
- Report a test as passing unless you saw it exit 0. A timed-out or
  interrupted run is a failure.
- Force-push, rewrite history, or amend a commit that is already pushed.
- Add "Generated with <tool>" or co-author trailers to commits or PRs.

That is roughly 150 words of actual instruction. It contains no architecture overview, no description of what the product does, and nothing the agent could have read off the repo — and it covers the four boundaries that account for most of the damage an agent does to a small codebase.

Then treat it like an incident log. Every time an agent does something you have to undo, add one line, in the imperative, as specific as the mistake was. In six months you will have your own version of those 784 don'ts, and every one of them will have been paid for.

The honest summary

The most-starred repositories in open source converged on a format that looks nothing like documentation, because the reader is not a person. It is prohibitive, specific, command-heavy, and — in the best cases — very short.

For a founder shipping an MVP with agents doing most of the typing, that file is plausibly the highest-leverage 150 lines in the repository. It is also the only file in your project that you pay for on every task, which is precisely why the instinct to make it thorough is the instinct to resist.

Write the mistakes. Skip the tour. Let it grow one scar at a time.

Sources: r/AI_Agents, "What the 100 biggest GitHub repos put in their AGENTS.md files" · GitHub Blog, "How to write a great agents.md: lessons from over 2,500 repositories" · agents.md, on the format, its adoption and Agentic AI Foundation stewardship · neovim/neovim AGENTS.md · vercel/next.js AGENTS.md

Context Engineering: The Skill That Makes or Breaks AI MVPs in 2026April 2026

Agentic AI with Claude Code: A 2026 Founder's Guide to Shipping Without Losing the PlotApril 14, 2026

AI Agents Need Permission Systems, Not Better Prompts — A Founder’s GuideJuly 14, 2026

IdeaToMVP Academy

Want to build with AI — not just read about it?

4-week live cohort for founders. Learn to ship AI agents, scope MVPs, and automate your business — taught by the same team that writes these guides.

Explore the Academy →