AGENTS.md를 올바르게 사용하는 방법 - /init 자동 생성이 오히려 비용을 높이는 이유
목차
개요
AI 코딩 에이전트가 코드베이스를 이해하도록 돕는 컨텍스트 파일(AGENTS.md, CLAUDE.md 등)의 사용이 점점 보편화되고 있습니다. 많은 AI 도구들이 /init 명령어로 이 파일을 자동 생성하는 기능을 제공하지만, 최신 연구에 따르면 이 방식이 오히려 역효과를 낼 수 있습니다. Addy Osmani의 분석에 따르면 자동 생성된 AGENTS.md는 작업 성공률을 낮추고 비용을 20% 이상 증가시킬 수 있습니다.
연구 결과의 역설
상충되는 두 연구
2026년에 발표된 두 연구는 서로 상충되는 결과를 보여줍니다. 첫 번째 연구는 AGENTS.md가 에이전트 런타임을 28.64% 단축시켰다는 긍정적인 결론을 냈습니다. 반면 두 번째 연구는 LLM이 자동 생성한 컨텍스트 파일이 작업 성공률을 2~3% 낮추고 비용을 20% 이상 증가시킨다는 반대 결론에 도달했습니다.
이 두 연구 결과를 분석하면 중요한 차이점이 드러납니다. 성공적인 AGENTS.md는 사람이 직접 작성한 파일이었고, 실패한 AGENTS.md는 LLM이 자동 생성한 파일이었습니다.
진짜 문제는 자동 생성
자동 생성된 AGENTS.md의 핵심 문제는 에이전트가 이미 스스로 발견할 수 있는 정보를 반복한다는 것입니다. 디렉토리 구조, 기술 스택, 파일 목록 같은 내용은 에이전트가 코드베이스를 탐색하면서 자연스럽게 파악할 수 있습니다. 이런 중복된 정보는 토큰만 낭비하고 처리 비용만 증가시킵니다.
올바른 AGENTS.md 작성법
포함해야 할 내용
AGENTS.md에는 에이전트가 코드를 읽어서는 발견할 수 없는 정보만 포함해야 합니다.
| 항목 | 예시 |
|---|---|
| 도구 선택 규칙 | pip 대신 uv를 사용할 것 |
| 비직관적 패턴 | 특정 모듈은 절대 직접 임포트 금지 |
| 시스템 제약사항 | 특정 포트나 환경변수 이름 규칙 |
| 외부 의존성 정보 | 내부 패키지 레지스트리 위치 |
| 코드베이스 주의사항 | 알려진 버그나 우회 방법 |
제외해야 할 내용
에이전트가 스스로 파악 가능한 정보는 AGENTS.md에서 제외해야 합니다.
| 항목 | 이유 |
|---|---|
| 디렉토리 구조 | ls 명령으로 즉시 파악 가능 |
| 기술 스택 개요 | package.json, requirements.txt 등에서 확인 가능 |
| 설치 방법 | README에 이미 있거나 표준적임 |
| 파일 목록 | glob 탐색으로 발견 가능 |
더 나은 아키텍처: 계층적 컨텍스트
단일 모놀리식 AGENTS.md 파일은 복잡한 코드베이스에 적합하지 않습니다. 더 나은 접근법은 작업 유형에 따라 필요한 컨텍스트만 선택적으로 로드하는 계층적 컨텍스트 시스템입니다.
예를 들어, 프론트엔드 작업을 할 때는 백엔드 관련 컨텍스트를 로드할 필요가 없습니다. 루트 AGENTS.md에는 공통 규칙만 두고, 서브디렉토리별로 별도의 컨텍스트 파일을 두어 해당 영역에서만 로드되도록 하는 구조가 효과적입니다.
Addy Osmani는 AGENTS.md를 “아직 해결하지 못한 마찰의 살아있는 문서”로 생각하라고 권장합니다. 즉, 문제를 문서화하는 대신 근본 원인을 수정하고, 더 이상 필요 없어진 컨텍스트 라인은 삭제하는 것이 이상적인 접근법입니다.
결론
AGENTS.md는 AI 에이전트의 성능을 높이는 강력한 도구가 될 수 있지만, 자동 생성에 의존하면 오히려 역효과가 납니다. 핵심은 에이전트가 스스로 발견할 수 없는 정보만을 담는 것입니다. 올바르게 작성된 AGENTS.md는 처리 비용을 낮추면서도 에이전트의 작업 성공률을 높일 수 있습니다. AI 코딩 도구를 적극적으로 활용하는 개발팀이라면 AGENTS.md 파일을 지속적으로 검토하고 불필요한 내용을 제거하는 것을 권장합니다.