A good AGENTS.md is a model upgrade. A bad one is worse than no docs at all
Summary
The post analyzes AGENTS.md files in a monorepo and finds that well-structured AGENTS.md can significantly boost agent performance, while poorly written ones can degrade results below having no docs. It identifies patterns that work (progressive disclosure, procedural workflows, decision tables, concrete code examples, domain-specific rules, pairing don't with do) and warns about pitfalls like overexploration, doc sprawl, and mismatched guidance across tasks. It also offers guidance on migrating existing docs to be more agent-friendly.