AGENTS.md는 코딩 에이전트에 실제로 도움이 되는가? — ETH Zürich 논문 분석

코딩 에이전트를 쓰다 보면 한 번쯤 마주치는 파일이 있다. AGENTS.md, CLAUDE.md, CODEX.md 같은 컨텍스트 파일이다. 레포지토리의 구조, 빌드 방법, 코딩 컨벤션 등을 에이전트에게 알려주는 일종의 "에이전트용 README"인데, Anthropic·OpenAI·Alibaba 할 것 없이 모든 에이전트 벤더가 적극 권장하고 있고, GitHub에만 6만 개 이상의 레포에 포함돼 있다.

그런데 정말 효과가 있는 걸까?

ETH Zürich의 Thibaud Gloaguen 등이 ICML 2026에 발표한 논문 "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?"은 이 질문에 처음으로 정량적 답을 내놓았다. 결론부터 말하면, 현재 방식의 컨텍스트 파일은 기대만큼 효과적이지 않다.

실험 설계: 두 개의 벤치마크, 세 가지 조건

연구진은 두 가지 벤치마크를 사용했다.

SWE-bench Lite: 11개 유명 Python 프로젝트에서 추출한 300개 GitHub 이슈. 컨텍스트 파일이 없는 레포들이다.
AGENTbench (신규): 연구진이 직접 구축한 벤치마크. 개발자가 실제로 컨텍스트 파일을 커밋한 12개 니치 레포에서 138개 이슈를 수집했다.

각 벤치마크에서 세 가지 조건으로 실험했다.

None: 컨텍스트 파일 없음
LLM: 에이전트의 /init 명령으로 자동 생성한 컨텍스트 파일
Human: 개발자가 직접 작성한 컨텍스트 파일 (AGENTbench만)

코딩 에이전트는 Claude Code(Sonnet 4.5), Codex(GPT-5.2, GPT-5.1 mini), Qwen Code(Qwen3-30b-coder) 4종을 테스트했다.

핵심 결과: LLM 생성 파일은 오히려 역효과

결과를 요약하면 이렇다.

LLM이 자동 생성한 컨텍스트 파일:

8개 설정 중 5개에서 성능 하락 (평균 -0.5%~-2%)
추론 비용은 20~23% 증가
스텝 수도 평균 2.5~3.9개 증가

개발자가 직접 쓴 컨텍스트 파일:

Claude Code를 제외한 3개 에이전트에서 소폭 성능 향상 (평균 +4%)
하지만 비용은 마찬가지로 증가 (최대 19%)

한마디로, LLM이 자동 생성한 컨텍스트 파일은 돈만 더 들고 성능은 떨어뜨린다. 개발자가 직접 쓴 파일은 약간의 개선 효과가 있지만, 그것도 비용 대비 효율이 좋진 않다.

왜 이런 결과가 나왔을까?

1. 기존 문서와의 중복

LLM이 생성한 컨텍스트 파일은 대부분 README, docs/, 예제 코드 등 이미 레포에 있는 정보를 반복하고 있었다. 연구진이 레포에서 모든 문서를 삭제한 뒤 실험하자, LLM 생성 컨텍스트 파일이 오히려 평균 2.7% 성능 향상을 보였다. 즉 문서가 충분한 레포에서는 컨텍스트 파일이 순수한 노이즈가 되는 셈이다.

2. 레포 개요는 실질적으로 무의미

컨텍스트 파일의 대표적 권장 사항이 "레포 구조 개요를 넣어라"인데, 실험 결과 관련 파일을 더 빨리 찾는 데 전혀 도움이 되지 않았다. 오히려 GPT-5.1 mini는 컨텍스트 파일이 있으면 그 파일을 여러 번 반복해서 읽는 비효율적 행동을 보였다.

3. 불필요한 요구사항이 태스크를 어렵게 만든다

컨텍스트 파일에 "이 프로젝트는 uv를 사용합니다", "테스트는 pytest로 돌려주세요" 같은 지시가 들어가면, 에이전트는 그걸 충실히 따른다. 문제는 그 과정에서 더 많은 탐색, 더 많은 테스트, 더 많은 추론 토큰을 소비한다는 것이다. GPT-5.2의 reasoning 토큰은 컨텍스트 파일이 있을 때 22% 증가했다. 에이전트가 지시를 무시해서 문제가 아니라, 너무 잘 따라서 문제다.

4. 강한 모델이 더 좋은 컨텍스트 파일을 만드는 것도 아니다

GPT-5.2로 생성한 컨텍스트 파일을 다른 에이전트에 넣어봤지만, SWE-bench Lite에서는 소폭 개선(+2%)이 있었어도 AGENTbench에서는 오히려 -3%였다. 프롬프트를 바꿔도 일관된 차이는 없었다.

실무 시사점

지금 당장 할 수 있는 것

LLM 자동 생성 컨텍스트 파일은 쓰지 마라. /init으로 자동 생성하는 것은 현 시점에서 비용만 늘리고 성능 이득은 없다.

수동으로 쓸 거면 최소한으로 써라. 논문의 결론은 명확하다: "레포 개요", "디렉토리 설명", "아키텍처 다이어그램" 같은 것은 넣지 마라. 에이전트는 이미 grep과 find로 레포를 탐색할 수 있다. 오히려 에이전트가 스스로 알 수 없는 정보만 넣어야 한다.

효과적인 컨텍스트 파일의 예시:

이 프로젝트는 uv로 의존성을 관리한다 (pip 아님)
테스트 실행: make test-unit (pytest 직접 호출 금지)
CI에서 Python 3.12만 지원
src/legacy/는 건드리지 마라

비효과적인 컨텍스트 파일의 예시:

프로젝트 개요 및 목적 설명
디렉토리 구조 나열
코딩 스타일 가이드 (lint가 잡아줌)
아키텍처 설명

문서가 부족한 레포에서는 효과적

흥미로운 반전은, 문서가 거의 없는 레포에서는 컨텍스트 파일이 실제로 도움이 된다는 점이다. 내부 프로젝트나 문서화가 미흡한 레포에서 에이전트를 쓴다면, 빌드/테스트 명령어와 핵심 의존성 정도를 적어두는 것은 유의미한 효과가 있다.

Python 외 언어에서는?

이 논문은 Python만 다뤘다. Python은 LLM 학습 데이터에 풍부하게 포함된 언어라, 모델이 이미 pip, pytest, Django, Flask 등의 관습을 잘 알고 있다. Rust, Zig, Elixir 같은 니치 언어에서는 컨텍스트 파일의 효과가 달라질 수 있다. 이건 향후 연구 과제로 남아 있다.

우리 워크플로우에의 적용

이 논문의 교훈을 정리하면:

AGENTS.md에 레포 구조를 장황하게 쓰지 마라 — 에이전트는 이미 탐색 능력이 있다
에이전트가 알 수 없는 것만 써라 — 빌드 도구, 특수 명령어, 금지 영역
자동 생성(/init)은 피하라 — 기존 문서와 중복되면 순해(純害)
비용 모니터링 필수 — 컨텍스트 파일 추가 후 토큰 사용량이 20%+ 증가할 수 있다
문서가 없는 프로젝트에서만 적극적으로 작성하라

결국 좋은 컨텍스트 파일은 짧고, 구체적이며, 에이전트가 스스로 발견할 수 없는 정보만 담고 있어야 한다. "더 많은 정보 = 더 좋은 결과"라는 직관은 적어도 현재의 코딩 에이전트에게는 통하지 않는다.

논문: Gloaguen et al., "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?", ICML 2026. arXiv:2602.11988

벤치마크 코드: github.com/eth-sri/agentbench