좋은 AGENTS.md 는 모델 업그레이드다. 나쁜 것은 문서가 아예 없는 것보다 더 나쁘다

우리는 모노레포 전반에 걸쳐 수십 개의 AGENTS.md 파일을 추출하여 코드 생성에 미치는 영향을 측정했습니다. 가장 훌륭한 파일들은 코딩 에이전트의 품질 향상을 Haiku 에서 Opus 로 업그레이드하는 것과 동등한 수준으로 끌어올렸습니다. 반면, 가장 나쁜 파일들은 AGENTS.md 가 아예 없는 경우보다 출력을 더 악화시켰습니다.

이 격차는 놀라울 정도로 커서, 우리는 이를 중심으로 체계적인 연구를 수행했습니다.

우리가 발견한 바에 따르면, 사람들이 AGENTS.md 에 넣는 대부분의 내용은 도움이 되지 않거나 오히려 해가 되며, 효과가 있는 패턴들은 구체적이고 학습 가능한 것입니다.

하나의 파일은 한 작업에는 도움을 주지만 다른 작업에서는 30% 나 떨어뜨릴 수도 있습니다

단일 AGENTS.md 파일이 항상 좋거나 나쁜 것은 아닙니다. 같은 파일이 일상적인 버그 수정(best_practices) 작업에서는 25% 를 향상시켰지만, 동일한 모듈 내의 복잡한 기능 개발(feature task) 작업에서는 완성도(completeness)를 30% 로 떨어뜨렸습니다.

버그 수정 작업에서는 두 가지 유사한 데이터 가져오기 접근법 중 하나를 선택하기 위한 결정 표(decision table)가 에이전트가 즉시 올바른 패턴을 선택하고 코드베이스 표준을 준수하도록 도왔습니다. 기능 개발 작업에서는 에이전트가 같은 파일을 읽었으나, 참고 섹션(reference section)에 끌려 들어갔고, 모든 가이드라인과 비교하여 접근법을 검증하기 위해 수십 개의 다른 마크다운 파일을 열었습니다. 그 결과 불필요한 추상화를 생성하고 불완전한 솔루션을 출시했습니다.

문서의 다른 블록들은 서로 다른 작업에 반대되는 영향을 미쳤습니다.

다음은 어떤 패턴이 작동하는지, 어떤 것이 실패하는지, 그리고 코드베이스별로 어떻게 구분할 수 있는지 설명합니다.

우리는 이를 어떻게 측정했는가

우리는 에이전트가 내부 개발 업무를 얼마나 잘 수행하는지 평가하기 위해 내부 평가套件(AuggieBench) 중 하나를 사용했습니다. 우리는 대규모 리포에서 고품질의 PR 을 시작점으로 하여, 일반적인 일일 에이전트 작업을 반영한 환경을 설정하고 프롬프트를 구성한 후, 에이전트에게 동일한 작업을 수행하도록 지시했습니다. 그런 다음 에이전트의 출력을 여러 선임 엔지니어의 검토를 거쳐 실제로 출시된 버전인 골든 PR(golden PR) 과 비교했습니다. 우리는 작업 범위가 확장되거나 알려진 버그가 있는 PR 은 제외했습니다.

이번 연구에서는 두 가지 추가 필터를 적용했습니다. PR 은 단일 모듈이나 앱 내에 포함되어야 하며, AGENTS.md 의 정보가 도움이 될 수 있을 만한 범위를 가져야 했습니다. 그런 다음 각 작업을 파일이 있고 없는 경우로 나누어 두 번 실행하고 점수를 비교했습니다.

작동하는 것들

1. 점진적 공개(progressive disclosure) 가 포괄적인 커버리지보다 낫다

AGENTS.md 를 기술(skill)처럼 취급하세요. 일반적인 사례와 워크플로우를 상위 수준에서 다루고, 세부 사항은 에이전트가 필요할 때 로드할 수 있는 참고 파일(reference files)로 이동시키세요. 각 참고 자료의 범위를 명확히 하여 에이전트가 언제 불러야 하는지 알도록 하세요.

100150 줄 정도의 AGENTS.md 파일과 몇 가지 집중된 참고 문서가 포함된 것이 우리 연구에서 최고의 성과를 보였습니다. 약 100 개의 핵심 파일을 가진 중형 모듈에서 모든 지표에 걸쳐 1015% 의 향상을 가져왔습니다. 메인 파일이 그 길이보다 길어지면 이득이 반전되기 시작했습니다.

2. 절차적 워크플로우(procedural workflows) 는 에이전트가 실패에서 완결로 이끌다

작업을 번호가 매겨진 다단계 워크플로우로 설명하는 것은 우리가 측정한 가장 강력한 패턴 중 하나였습니다. 잘 작성된 워크플로우는 에이전트를 작업 완수 불가능 상태에서 첫 시도 만에 올바른 솔루션을 생성하는 상태로 전환할 수 있습니다.

우리의 코드베이스에서 나온 한 예시: 새로운 통합을 배포하기 위한 6 단계 워크플로우입니다. 에이전트는 이를 단계별로 따랐습니다. 누락된 와이어링 파일(wiring files) 이 포함된 PR 의 비율은 40% 에서 10% 로 떨어졌고, 에이전트의 평균 완료 속도가 빨라졌습니다. 정확도는 25% 향상되었고, 완성도는 20% 향상되었습니다.

복잡한 워크플로우의 경우 메인 파일은 간결하게 유지하고 분기되는 경우는 참고 파일로 사용하세요.

3. 결정 표(decision tables) 는 에이전트가 코드를 작성하기 전에 모호성을 해결한다

코드베이스에 어떤 작업을 수행하는 데 합리적인 방법이 두 가지나 세 가지 있을 때, 결정 표는 선택을 미리 강제합니다. 이는 코드베이스 관례 준수를 가장 직접적으로 개선한 패턴입니다.

예시: 상태 관리 위해 React Query 와 Zustand 중 하나를 선택하는 것.

질문	→ React Query	→ Zustand
서버가 유일한 데이터 소스인가?	✅
여러 코드 경로에서 이 상태를 수정하는가?	✅
낙관적 업데이트와 로컬 상태를 혼합해야 하는가?	✅

이 분야의 PR 점수는 25