The strongest point here is that AGENTS.md works best when it captures repository-specific decisions, not generic engineering advice.
We've seen the same pattern with AI coding tools: vague rules like "write clean code" barely change outputs, but concrete examples, forbidden patterns, and architectural constraints do. A short file with "Preferred/Avoid" examples often outperforms a massive document full of principles.
I also like the idea of the five-minute verification test. Removing the context file and comparing diffs is a practical way to measure whether your instructions are actually influencing agent behavior or just adding tokens.
One thing I'd add: include a small "Why this exists" section for non-obvious constraints (e.g., "don't simplify this retry logic because of production rate limits"). Agents are good at following patterns, but preserving past decisions is what prevents them from repeatedly proposing the same rejected ideas.
Thanks for reading, Mateo Ruiz . I think you may be thinking of a different article, this one is about business chatbots answering from approved sources rather than coding agents, but your point about concrete examples beating vague rules holds there too. A handful of real example phrasings per intent does more for classification than any amount of instruction text.
The strongest point here is that
AGENTS.mdworks best when it captures repository-specific decisions, not generic engineering advice.We've seen the same pattern with AI coding tools: vague rules like "write clean code" barely change outputs, but concrete examples, forbidden patterns, and architectural constraints do. A short file with "Preferred/Avoid" examples often outperforms a massive document full of principles.
I also like the idea of the five-minute verification test. Removing the context file and comparing diffs is a practical way to measure whether your instructions are actually influencing agent behavior or just adding tokens.
One thing I'd add: include a small "Why this exists" section for non-obvious constraints (e.g., "don't simplify this retry logic because of production rate limits"). Agents are good at following patterns, but preserving past decisions is what prevents them from repeatedly proposing the same rejected ideas.