Solo vs team
A solo AGENTS.md satisfies one person. A team's is a shared artifact — and it needs a little process.
Treat it like code
It lives in the repo, changes via PR, gets reviewed like anything else. A change shapes every agent's behaviour for every dev — same care as a shared config change.
Give it an owner
Unowned shared files either go stale (nobody updates) or bloat (everybody does). An owner keeps it sharp and guards the bar against bloat — the one pressure a team applies constantly.
Resist the committee effect
Each person adds the rule that bit them, nobody removes anything, and in a quarter the important rules are buried. The fix — ruthless pruning — has to be someone's explicit job.
Free onboarding
A good AGENTS.md is one of the best onboarding docs you have. A new hire reads it in a minute: how to build, the real conventions, what not to touch. And because agents depend on it, it stays current.
Keep it in sync across tools
Different devs, different agents → one real file, symlinked where a tool needs another name. Commit the symlink so everyone's on identical context on clone.
Free cheat sheet: the format, an annotated example, and the one-line test — AGENTS.md Cheat Sheet.
Go deeper: the full reference — cross-tool setup, the monorepo hierarchy, and a 30-day plan — AGENTS.md: The Complete Guide to the Cross-Tool Agent Standard.
Who owns the AGENTS.md on your team — or is it nobody's job yet? 👇
Top comments (0)