AGENTS.md가 코딩 에이전트 성능에 미치는 영향 분석

섹션별 상세

AGENTS.md 파일의 품질은 에이전트의 작업 성능을 30% 이상 변화시킬 수 있는 핵심 요소이다. 잘 작성된 문서는 모델을 Haiku에서 Opus로 업그레이드한 것과 같은 효과를 주지만, 잘못된 문서는 문서가 아예 없는 것보다 못한 결과를 초래한다. 실제 테스트에서 동일한 파일이 루틴한 버그 수정에는 도움이 되었으나 복잡한 기능 구현 시에는 에이전트를 불필요한 탐색으로 유도해 완수율을 30% 떨어뜨렸다.

AGENTS.md의 품질이 모델 업그레이드와 같거나 혹은 문서가 없는 것보다 나쁠 수 있음을 경고하는 이미지 — Infographic문서화의 품질이 에이전트 성능에 미치는 극단적인 차이를 시각적으로 강조합니다. 좋은 문서는 모델 체급을 올리는 효과를 주지만, 나쁜 문서는 성능을 저하시킨다는 아티클의 핵심 주장을 뒷받침합니다.

정보를 한꺼번에 제공하기보다 점진적으로 공개하는 방식이 에이전트의 컨텍스트 관리에 유리하다. 100~150라인 정도의 핵심 요약 파일과 구체적인 세부 사항을 담은 참조 문서를 분리했을 때 성능이 10~15% 향상됐다. 메인 파일이 이 길이를 넘어서면 에이전트가 너무 많은 정보를 처리하느라 오히려 성능이 저하되는 역전 현상이 발생한다.

번호가 매겨진 단계별 워크플로와 결정 테이블은 에이전트의 의사결정 정확도를 획기적으로 높인다. 특정 통합 배포 과정을 6단계 워크플로로 제공했을 때 배포 누락률이 40%에서 10%로 감소하고 정확도는 25% 향상됐다. 또한 React Query와 Zustand 중 무엇을 사용할지 결정하는 표를 제공하자 코드 작성 전 모호함이 해소되어 모범 사례 준수 점수가 25% 상승했다.

금지 사항만 나열하는 것보다 대안을 함께 제시하는 'Do'와 'Don't' 쌍의 구성이 필수적이다. 15개 이상의 금지 사항만 나열된 문서는 에이전트를 지나치게 보수적으로 만들어 작업 속도를 늦추고 탐색 비용을 높였다. 반면 'HTTP 클라이언트를 직접 생성하지 말고 공용 API 클라이언트를 사용하라'는 식의 구체적인 지침은 에이전트가 즉시 올바른 코드를 작성하게 돕는다.

에이전트의 문서 발견 경로를 이해하고 이에 맞춰 문서를 배치해야 한다. 실험 결과 AGENTS.md는 100% 확률로 자동 로드되며 참조된 문서도 90% 이상의 세션에서 활용되지만, 참조되지 않은 독립 문서는 읽힐 확률이 10% 미만으로 떨어진다. 따라서 에이전트가 반드시 알아야 할 정보는 AGENTS.md에 직접 넣거나 해당 파일에서 명시적으로 링크해야 한다.

기술

Augment
Claude Haiku
Claude Opus
React Query
Zustand

활용 사례

모노레포 내 모듈별 에이전트 가이드 작성
신규 팀원의 온보딩을 위한 자동화된 워크플로 구축
코드베이스 컨벤션 준수 자동화

언급된 리소스

문서Augment Code Blog