좋은 AGENTS.md는 모델 업그레이드다. 나쁜 AGENTS.md는 문서가 없는 것보다 못하다

AGENTS.md를 수십 개 분석한 결과, 문서의 품질에 따라 에이전트 성능이 크게 갈렸다. 잘 만든 문서는 코딩 에이전트를 Haiku에서 Opus로 올린 수준의 개선을 냈지만, 잘못된 문서는 아예 없는 것보다 결과를 더 나쁘게 만들었다.

핵심은 문서의 양이 아니라 구조와 범위였다. 100~150줄 정도의 짧은 메인 문서에 필요한 참조 문서를 연결하는 방식이 가장 좋았고, 긴 설명보다 절차적 워크플로우, 의사결정 표, 실제 코드 예시가 성능을 끌어올렸다.

특히 두 가지 패턴이 강했다. 하나는 React Query vs Zustand처럼 선택지가 있을 때 결정을 미리 고정하는 표였고, 다른 하나는 "하지 말 것"만 나열하지 말고 반드시 **"무엇을 할지"**를 함께 적는 방식이었다. 이 조합은 best_practices, completeness, code_reuse 같은 지표를 개선했다.

반대로 실패 패턴도 분명했다. 아키텍처 설명을 과도하게 늘리거나 경고를 남발하면 에이전트가 관련 없는 문서를 계속 읽는 overexploration에 빠졌고, 결과는 더 느리고 덜 완성된 코드였다. 새 패턴을 도입하는 작업처럼 기존 문서가 오히려 방향을 틀 수 있는 경우에는 AGENTS.md보다 spec-driven development가 더 맞는 해법으로 제시됐다.

문서 발견 경로도 중요했다. AGENTS.md는 거의 항상 자동 발견됐고, 그 밖의 참조 문서는 필요할 때 읽혔다. 반면 중첩 README나 _docs/ 아래 고립된 문서는 잘 읽히지 않았기 때문에, 중요한 정보는 AGENTS.md에 두거나 거기서 직접 참조해야 한다는 결론을 내렸다.