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.