AGENTS.md for a Team: Ownership, Review and Onboarding
A solo developer's AGENTS.md only has to satisfy one person. A team's file has to be a shared artifact — written together, owned clearly, and changed through the same process as any other code. The principles do not change, but a few practices become important that a solo project can skip.
Treat It Like Code
The single most useful shift is to stop thinking of AGENTS.md as documentation and start treating it as code. It lives in the repository, changes through pull requests, and gets reviewed like anything else. A change to it shapes what every agent does for every developer, so it deserves the same care as a change to a shared configuration file. Reviewing it also spreads understanding of the conventions it encodes.
Give It an Owner
Shared files with no owner drift toward two failure modes: nobody updates them and they go stale, or everybody does and they bloat. Give the file a clear owner — a person or small group responsible for keeping it sharp, approving additions, and periodically pruning. The owner does not write every line; they hold the bar against bloat, which is the one pressure a team applies constantly.
Resist the Committee Effect
The characteristic way a team file goes wrong is accretion: each person adds the rule that bit them, nobody removes anything, and within a quarter the important rules are lost among the once-relevant ones. The defence is ruthless pruning — but it has to be someone's explicit job, because the natural gradient of a shared file is always toward more. A periodic prune keeps it honest.
Onboarding for Free
A well-kept AGENTS.md turns out to be one of the better onboarding documents a team has, even though it was written for agents. A new hire can read it in a minute and learn how to build and test, the real conventions, and what not to touch — without wading through prose written to impress. Because the agents depend on it being accurate, it tends to stay more current than traditional onboarding docs.
Keep It in Sync Across Tools
Different developers use different agents, so the single-source-of-truth pattern — one real file, symlinked where a tool needs another name — is what keeps everyone's tools agreeing. Commit the symlink so it is there on clone, and the whole team works from identical context no matter which agent each person prefers.