The useful stuff is different from a README. A README tells humans how to use the project. An AGENTS.md tells the AI how to work on it.

Mine typically includes:

- Build/test commands that aren't obvious from package.json (e.g. "run migrations before tests") - Architecture decisions that would take the agent 10 minutes to reverse-engineer ("auth goes through middleware X, not controller Y") - Known gotchas ("don't touch the legacy billing module, it's being replaced next sprint") - Deploy process specifics ("push to main auto-deploys staging, prod needs a manual tag") - Coding conventions that aren't in the linter ("we use Result types for errors, never throw")

The ones that look like READMEs are indeed useless. The good ones read more like the notes you'd give a new senior engineer on their first day. Stuff that's obvious to the team but invisible to an outsider.

[delayed]

Seems like that is knowledge a human would want too, and you are dumping it in the agents file for lack of a clearer place to put it.