기술 요약: AGENTS.md 평가

문제 정의

소프트웨어 엔지니어링 업계는 코딩 에이전트를 빠르게 도입하고 있으며, 모델 및 에이전트 개발자들은 컨텍스트 파일(예: AGENTS.md 또는 CLAUDE.md)을 사용하여 이러한 에이전트를 특정 저장소에 맞춤화할 것을 권장하는 추세입니다. 이러한 파일들은 일반적으로 탐색, 빌드 실행 및 작업 해결 능력을 향고하기 위해 설계된 저장소 개요, 도구 지침 및 스타일 가이드를 포함합니다. 60,000개 이상의 오픈 소스 저장소에서 보고될 만큼 광범위한 채택과 강력한 업계의 권장에도 불구하고, 이러한 컨텍스트 파일이 실제 작업에서 코딩 에이전트의 성능을 실제로 개선하는지에 대한 엄격하고 대규모인 조사는 이루어지지 않았습니다. SWE-bench와 같은 기존 벤치마크는 컨텍스트 파일을 포함하지 않으며, 해당 벤치마크에서 사용되는 인기 있는 저장소들은 컨텍스트 파일이 실제로 배포되는 코드베이스를 대표하지 못하는 경우가 많습니다.

방법론

이 간극을 메우기 위해 저자들은 두 가지 상호 보완적인 환경에 걸쳐 종합적인 평가를 수행했습니다.

1. 새로운 벤치마크 (CTXBENCH): 저자들은 개발자가 커밋한 컨텍스트 파일을 이미 포함하고 있는 12개의 니치(niche)한 Python 기반 저장소에서 추출한 138개의 인스턴스로 구성된 새로운 벤치마크를 구축했습니다. 인기 있는 저장소에 의존하는 SWE-bench와 달리, CTXBENCH는 컨텍스트 파일이 활발하게 사용되는 저장소를 대상으로 합니다. 데이터셋 생성 과정은 다음과 같습니다:

   • AGENTS.md 또는 CLAUDE.md가 있고 최소 400개의 Pull Request(PR)가 있는 저장소를 필터링함.
   • 결정론적이고 테스트 가능한 동작을 도입하는 PR을 선택함.
   • 원래의 PR에 테스트가 없는 경우, LLM 에이전트를 사용하여 표준화된 작업 설명과 새로운 단위 테스트를 생성함. 이때 테스트는 수정된 코드에서는 통과하지만 베이스 코드에서는 실패하도록 보장함.
   • 개발자가 제공한 컨텍스트 파일이 LLM이 생성한 파일과 구별됨을 검증함 (더 짧고, 낮은 AI 탐지 점수).

2. 실험 설정: 본 연구는 다양한 모델(SONNET-4.5, GPT-5.2, GPT-5.1 Mini, QWEN3-30B-CODER)과 결합된 네 가지 코딩 에이전트(CLAUDE CODE, CODEX, QWEN CODE)를 두 가지 데이터셋에서 평가했습니다:

   • SWE-BENCH Lite: 개발자 컨텍스트 파일이 없는 인기 저장소의 300개 작업.
   • CTXBENCH: 개발자 컨텍스트 파일이 있는 저장소의 138개 작업.

3. 평가 조건: 각 작업에 대해 에이전트는 세 가지 설정에서 테스트되었습니다:

   • None: 컨텍스트 파일 미제공.
   • LLM: 에이전트의 권장 초기화 명령에 의해 자동으로 생성된 컨텍스트 파일.
   • DEV: 실제 개발자가 커밋한 컨텍스트 파일 (CTXBENCH에서만 사용 가능).

4. 지표: 성능은 성공률(생성된 패치가 모든 테스트를 통과하는 작업의 백분율), 상호작용 단계 수, 총 추론 비용에 의해 측정되었습니다. 도구 사용 빈도 및 추론 토큰 소비를 포함한 행동 변화를 이해하기 위해 트레이스(trace) 분석이 수행되었습니다.

주요 기여

1. CTXBENCH: 활발하게 사용되는 개발자 제공 컨텍스트 파일이 코딩 에이전트 성능에 미치는 영향을 평가하기 위해 특별히 설계된 새로운 벤치마크로, 12개 저장소에서 추출한 138개의 인스턴스를 특징으로 합니다.
2. 종합적 평가: SWE-BENCH 및 CTXBENCH 모두에서 여러 모델과 에이전트에 걸친 광범위한 연구를 통해, 컨텍스트 파일이 작업 성공률을 유의미하게 개선하지 못한다는 점을 밝혀냈습니다.
3. 행동 분석: 에이전트 트레이스에 대한 상세한 조사를 통해, 에이전트가 컨텍스트 파일의 지침을 엄격히 따르지만(이는 테스트 및 탐색 증가로 이어짐), 이 파일들이 효과적인 저장소 개요 역할을 하지 못하며 운영 비용을 증가시킨다는 점을 입증했습니다.

결과

본 연구는 컨텍스트 파일의 효능에 대해 몇 가지 반직관적인 발견을 제시합니다:

• 성능 향상 없음: 컨텍스트 파일을 제공하는 것이 일반적으로 작업 성공률을 개선하지 않습니다.
  • SWE-BENCH에서 LLM 생성 컨텍스트 파일은 성공률의 미미하고 통계적으로 유의하지 않은 감소(-0.5%)를 초래했습니다.
  • CTXBENCH에서도 LLM 생성 파일은 유의미한 개선을 보이지 않았습니다 (평균 -2%).
  • 개발자 커밋 파일은 "None" 설정 대비 평균 2.4%의 미미한 개선을 보였으나, 이는 통계적으로 유의하지 않았습니다 ($p=0.21$). 그러나 개발자 파일은 LLM 생성 파일보다 유의미하게 높은 성능을 보였습니다 ($p=0.038$).
• 비용 및 단계 증가: 컨텍스트 파일은 일관되게 작업 해결의 비용과 복잡성을 증가시킵니다.
  • LLM 생성 파일은 두 벤치마크 모두에서 평균 20% 이상의 추론 비용을 증가시켰습니다.
  • 개발자 커밋 파일은 비용을 최대 19%까지 증가시켰습니다.
  • 컨텍스트 파일이 있는 모든 설정에서 상호작용 단계 수가 유의미하게 증가했습니다.
• 행동 메커니즘:
  • 지침 준수: 에이전트는 컨텍스트 파일의 지침을 엄격히 따릅니다. 특정 도구(예: uv, pytest)가 언급되면 해당 도구의 사용이 급격히 증가합니다. 이는 더 철저한 테스트, 파일 탐색 및 저장소 특화 도구 사용으로 이어집니다.
  • 효과 없는 개요: 코드베이스 개요를 포함하라는 권장 사항에도 불구하고, 이러한 섹션은 에이전트가 관련 파일을 더 빨리 찾는 데 도움이 되지 않습니다. 실제로 에이전트는 이미 컨텍스트 윈도우에 있는 컨텍스트 파일을 검색하고 다시 읽는 데 추가 단계를 소비하는 경우가 많습니다.
  • 추론 오버헤드: 컨텍스트 파일의 존재는 적응형 모델(예: LLM 생성 파일 사용 시 GPT-5.2에서 +22%)의 추론 토큰 사용량을 증가시키며, 이는 추가된 지침이 필요한 정보를 제공하지 못한 채 작업을 인지적으로 더 어렵게 만든다는 것을 시사합니다.
• 중복성: 컨텍스트 파일은 종로 종종 중복된 문서 역할을 합니다. 기존 문서(README, docs 폴더)가 제거되었을 때 LLM 생성 컨텍스트 파일이 오히려 성능을 향상시키는 것으로 보아, 일반적인 설정에서 이들의 주요 가치는 고유한 통찰력이 아닌 중복성에 있음을 시사합니다.

의의 및 결론

본 논문은 AGENTS.md와 같은 컨텍스트 파일을 자동으로 생성하거나 광범위하게 포함하는 현재의 업계 관행이 코딩 에이전트 성능을 향상시킨다는 경험적 근거를 뒷받받지 못한다고 결론짓습니다. 에이전트가 이 파일 내의 지침을 따르기는 하지만, 이는 더 철저하고(비용이 많이 드는) 탐색으로 이어질 뿐, 컨텍스트 파일이 작업 해결을 가속화하는 효과적인 저장소 개요를 제공하는 데는 일반적으로 실패합니다.

저자들은 컨텍스트 파일이 저장소의 README에 이미 존재하는 내용이 아닌, 비표준 코딩 관행이나 특정 컨벤션을 지정하는 용도로 제한되어야 한다고 주장합니다. 또한, 자동 생성이나 광범위한 권장에 의존하기보다 배포 전에 컨텍스트 파일 사용을 엄격하게 평가할 것을 권장합니다. 이 연구는 에이전트 개발자의 권장 사항과 관찰된 결과 사이의 간극을 강조하며, 코딩 에이전트를 위한 원칙적이고 간결하며 작업 관련성이 높은 가이드 생성에 대한 향후 연구의 필요성을 시사합니다.