Internal eval study found AGENTS.md quality gap equivalent to jumping from Haiku to Opus, with bad files actively degrading output below baseline.
Key Takeaways
100-150 line AGENTS.md with focused reference docs delivered 10-15% cross-metric gains; files longer than that reversed the gains.
Procedural step-by-step workflows cut missing-wiring PRs from 40% to 10% and boosted correctness 25% in a deploy-integration task.
Decision tables (e.g. React Query vs Zustand) resolved ambiguity before the agent wrote code, raising best_practices scores 25%.
Excessive “don’t” lists without paired “do” alternatives trigger overexploration: the agent verifies every warning against unrelated code, stalling on simple tasks.
Orphan docs in _docs/ folders get read in under 10% of sessions; AGENTS.md is the only location with reliable 100% discovery.
Hacker News Comment Review
Commenters split on whether hierarchical AGENTS.md placement is worth the effort: VS Code Copilot reportedly misses nested files, pushing some practitioners toward agent skills instead of deeper nesting.
Experienced practitioners report spreading multiple focused AGENTS.md files into important subdirectories as table-of-contents plus spark-notes, with homegrown agents that auto-inject context based on file proximity.
One dissenting voice frames all of this as coping behavior forced by model limitations, not genuine capability uplift.
Notable Comments
@verdverm: Spreading AGENTS.md into subdirectories and forcing them into context without a tool call via file-proximity detection outperforms root-only placement.
@forgotusername6: VS Code Copilot inconsistently discovers lower-level AGENTS.md files, undermining the 100% discovery claim outside controlled harnesses.
