AGENTS.md 작성 가이드: 정확성 25% 향상 vs 30% 하락

Augment Code는 모노레포 전반에 걸쳐 AGENTS.md 파일에 대한 체계적인 연구를 수행했습니다. 최고의 파일은 코딩 에이전트에 Haiku에서 Opus로 업그레이드한 것과 맞먹는 품질 향상을 제공했으며, 최악의 파일은 AGENTS.md가 전혀 없을 때보다 출력을 더 나쁘게 만들었습니다. 동일한 파일이 일상적인 버그 수정에서 best_practices를 25% 향상시킨 반면, 같은 모듈의 복잡한 기능 작업에서는 completeness를 30% 떨어뜨렸습니다. 다음은 효과가 있었던 방법들입니다.

측정 방법

내부 평가 스위트인 AuggieBench를 사용했습니다. 대규모 저장소에서 일상적인 에이전트 작업을 반영하는 고품질 PR로 시작하여, 환경과 프롬프트를 설정하고 에이전트가 PR을 재현하도록 요청했습니다. 여러 선임 엔지니어의 검토를 거친 골든 PR(최종 버전)과 출력을 비교했습니다. PR은 단일 모듈 또는 앱 내에 포함되어야 하며, 범위는 AGENTS.md가 도움이 될 만한 작업이어야 했습니다. 각 작업은 파일 유무에 따라 두 번씩 실행되었습니다.

효과적인 방법

1. 점진적 공개 > 포괄적 범위

일반적인 케이스와 워크플로우를 높은 수준에서 다루고, 세부 사항은 에이전트가 필요 시 로드할 수 있는 참조 파일에 넣으세요. 각 참조 파일의 범위를 명확히 유지하세요. 100~150줄의 파일과 몇 개의 집중된 참조 문서가 중간 규모 모듈(~100개 핵심 파일)에서 지표 전반에 걸쳐 10~15%의 개선을 가져왔습니다. 그 길이를 넘어서면 이점이 역전되었습니다.

2. 절차적 워크플로우

번호가 매겨진 다단계 워크플로우는 에이전트를 실패에서 완료로 이끌 수 있습니다. 예: 새 통합을 배포하기 위한 6단계 워크플로우. 누락된 연결 파일이 40%에서 10%로 줄었고, 에이전트가 더 빨리 완료했으며, 정확도가 25% 올라갔고, 완전성도 20% 향상되었습니다. 메인 파일은 간결하게 유지하고 분기 사례는 참조 파일을 사용하세요.

3. 의사 결정 테이블

두세 가지 합리적인 방법이 있을 때(예: 상태 관리를 위한 React Query vs Zustand), 테이블을 사용하여 미리 선택을 강제하세요. 예:

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

해당 영역의 PR에서 best_practices 점수가 25% 더 높았습니다.

4. 짧은 프로덕션 예제

실제 프로덕션 코드에서 가져온 3~10줄의 스니펫은 재사용성과 패턴 준수를 향상시켰습니다. 예: Redux Toolkit 기본 요소를 위한 복사-붙여넣기 템플릿(타입이 지정된 초기 상태의 createSlice, 오류 처리가 포함된 createAsyncThunk, 타입이 지정된 useAppSelector). code_reuse가 20% 증가했습니다.