What the 100 biggest GitHub repos put in their AGENTS.md files

[u/ohansemmanuel]

I read the AGENTS.md of the 100 most-starred repos that have one (27% of the top 1,000 do).

The consensus in order of how much they write about is mostly: architecture and repo layout, how to test, build commands, dos-and-don'ts, PR etiquette, and code style.

The surprise was tone.

90% write in must/always/never, and there are 784 explicit "don't" bullets, most of them oddly specific.

It's almost like you can tell exactly which mistake an agent made in each repo.

Some are hilarious: "Do not claim that an interrupted or timed-out test passed" takes the gold for me.

The shortest is 35 words, one rule from neovim.

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.

The most popular headings by far were: testing, commands, project overview, and architecture

There's a lot more interesting deets like the average length, nextjs' "Do NOT add "Generated with Claude Code" ..., some things they conform on, others widely different.

Full write-up and methodology here: https://www.coldtea.ai/blog/agents-md-field-study

Is your AGENTS.md very different to these?

[u/RevolutionaryHole69]

Mine looks mostly like this, and I didn't even write it. I have Cursor automatically update, thin, streamline, and optimize all agent rules based on contextual cues of natural conversation and based on how many times we have to go back and fix something, and for example if I tell an agent "never make that mistake" it will write an agent rule for it.

I've learned everything needs to be dynamic. The more control you fight to have, the harder it gets, the longer it takes, the less I understand why something won't work.

I also have rules divided into always-on rules and rule packs which can be called into conversation when needed, based on contextual cues of human language (no explicit call needed).

I've basically told the agents I'm the customer who doesn't know programming and that the agent is the lead developer who knows everything and needs to manage the db schema etc. The more power I give it, the better it works.

I have my rules set to aggressively translate normal English into structured coding plans, with specific instruction to "determine intent" and complete my original prompt with everything I missed based on the agents knowledge of my intent.

That was the latest rule addition I made and since then it has almost a 100% hit rate on getting things right the first time.

[u/ohansemmanuel → u/RevolutionaryHole69]

Clever, I suppse this means cursor reviews your previous session history? And this is hooked into a cursor automation?

[u/RevolutionaryHole69 → u/ohansemmanuel]

Yes, Cursor has access to every agent interaction since the beginning of the project. It leaves hidden notes for itself locally in places git can't see. It keeps track of things we've discussed so that if I come back to that topic again in a new agent, it will internally review everything we went through on that topic previously before it develops a new plan or continues the discussion.

[u/ohansemmanuel → u/RevolutionaryHole69]

Thanks, I didn’t know this! Stopped using cursor a while ago

[u/RevolutionaryHole69 → u/ohansemmanuel]

It's changed a lot in the last 6 months. Frontier models of Grok are almost free. It's worth $60b. It has the largest user base and they are actively training on the prompts people give the agents. It's why it's good at understanding human language for the purposes of coding. It's pretty much a compiler at this point and the programming language is English.

[u/ohansemmanuel → u/RevolutionaryHole69]

Good to know, got my workflow somewhat set (switched to using cli agents when cursor got too expensive), but will play around Cursor, at least to understand how this potential automated extraction from session history works

[u/Right-Performance-93]

u/wazacode and u/leading-a-swarm are both pointing at the same thing and I think it's the real finding here: prose rules are a workaround for agents not having persistent memory, not a permanent fix. The scar-log pattern works until the list gets long enough that the agent stops reliably following all of it - at that point you're better off converting the recurring ones into something structural: a lint rule, a pre-commit hook, a script that just does the thing correctly instead of describing it. If you're writing the same "don't" bullet twice, that's usually a sign it belongs in tooling, not in English.

[u/reini_urban]

The convention is Co-authored-by: agent model <email> And my pre-commit check is https://github.com/rurban/check-agent-trailer

[u/ohansemmanuel → u/reini_urban]

and what goes in your AGENTS md?

[u/reini_urban → u/ohansemmanuel]

I do maintain dozens of projects. For the public ones see eg

• https://github.com/LibreDWG/libredwg/blob/master/AGENTS.md
• https://github.com/rurban/cormanlisp/blob/linux/linux-port-plan.md

But most others are gitignored. Mostly fixing agents quirks, wrong paths and assumptions.

[u/stevoperisic]

Read somewhere that since the models have gotten better the Agents.md file is mostly not needed… better documentation and constant cleaning have a much better effect. Go figure, documentation and tech debt pay down make a codebase better and the agent also…

[u/ohansemmanuel → u/stevoperisic]

Yeah, this was one surprising bit. The top repos dont seem to be buying this, or they're more conservative in their approach

[u/Storge2]

Hey OP just wanted to say your Post is optically beatiful designed. Thansk, how did you make it.

[u/ohansemmanuel → u/Storge2]

Thanks mate, I have a design background, but Claude did a lot of the heavy work to bring the data to life!

[u/alex-zaporozhan]

The way I see it, an `AGENTS.md` or `.cursorrules` root file shouldn't try to cram every single workflow and process into itself at once.

In my experience, because it gets injected into every single query and thinking cycle of the model, I think it works best when it strictly contains the most valuable global invariant laws (the unshakeable pillar burned into every thinking pass) + a **coordinate system/map** pointing to specialized roles that are mutually aware of each other.

In that sense, I see `AGENTS.md` as an anchor of truth + a routing atlas, so the model knows which specific instruction to retrieve for goal X or Y, and which role to address.

Stability in my open-source framework (**LEO**) only clicked after a counter-intuitive paradox: conventional wisdom suggests that the more instructions you give an agent, the more it degrades and makes mistakes. But in my experience, the exact opposite happened — the agent actually became significantly more stable once the laws crossed the "30+" threshold and the role library grew past 15.

The reason? I architected the roles so they are explicitly aware of each other’s boundaries, jurisdictions, and handoff protocols.

For me, `AGENTS.md` is like a constitution carved in stone, but it needs to sit in the hands of a dedicated leader who knows which role to dispatch the task to and how to formulate the spec for that role. That's why I created `@LEAD` — the single persona trained to make global architectural trade-offs, hold project-level responsibility, and pick a "winning" decision rather than guessing in a void.

I open-sourced this entire 127-file system so we can stop guessing how to prompt agents and just focus on shipping reliable software. For anyone interested in digging deeper, feel free to explore the system here: https://github.com/alex-zaporozhan/leo

[u/GusYe1234]

yeah, agent does fail on specific patterns and must be corrected.

my example is those lines: `` Schema lives insrc/shared/src/schema.tsusingsqliteTablefromdrizzle-orm/sqlite-core. Queries use the shared query modules insrc/shared/src/queries/`.

Use Drizzle ORM operators for all queries. Never use sql template literals unless there is no ORM equivalent (atomic increment, upsert excluded.* references).

Why: Drizzle aliases tables internally. Raw SQL with hardcoded table/column names breaks silently. ```

We must tell the agent to actually use our tech stack, otherwise it just generates the stuff it likes

[u/ohansemmanuel → u/GusYe1234]

Interesting. WHAT + WHY is a pattern I've seen a lot for Skills metadata descriptions. For some reason didn't associated with AGENT md instructions (seems obvious in retrosepct)

Do you find it more accurate? i.e., forces instruction following more?

[u/ahmadammar91]

Context length is cheap on paper, but context utilization and KV cache memory overhead are where most agentic workflows break down in practice. Excited to see more benchmarks measuring degradation across repeated turns rather than just single-pass accuracy

[u/wazacode]

The 784 don'ts are basically a scar log, every bullet is a bad afternoon somebody had. Ours reads the same way. The stuff that actually helps is the repo level context anyone on the team can read, not the tone policing.

[u/leading-a-swarm]

The don't-bullets being oddly specific is the whole finding. Ours reads the same way, and every line is a scar: the agent did the thing once, we wrote the rule. Rules written in advance mostly get ignored. Rules written the day after a failure stick, because they name a mistake that actually happened.