컨텍스트 파일이 코딩 에이전트에 미치는 실제 효과

초록

본 논문은 AGENTS.md와 같은 저장소 수준 컨텍스트 파일이 실제 코딩 에이전트의 작업 성공률에 미치는 영향을 실증적으로 평가한다. SWE‑bench과 새로 만든 AGENT‑BENCH 두 벤치마크에서 자동 생성된 파일과 개발자가 직접 작성한 파일을 각각 적용해 본 결과, 컨텍스트 파일은 오히려 성공률을 낮추고 추론 비용을 20 % 이상 증가시킨다. 다만 파일이 에이전트의 탐색·테스트 범위를 넓히는 행동 변화를 유도한다는 부수적 효과도 확인하였다.

상세 분석

이 연구는 두 가지 주요 벤치마크, 즉 기존의 SWE‑bench(LIT‑level)과 새로 구축한 AGENT‑BENCH(컨텍스트 파일이 실제로 커밋된 소규모 레포지토리)에서 코딩 에이전트의 성능을 정량적으로 비교한다. 실험에 사용된 에이전트는 OpenAI Sonnet‑4.5, GPT‑4.2, GPT‑4.1, Mini‑Qwen‑3‑30B 등 네 가지 LLM 기반 모델이며, 각각의 하니스가 동일한 도구 집합(파일 읽기/쓰기, 쉘 실행, 테스트 실행 등)을 제공한다.

컨텍스트 파일은 크게 두 종류로 나뉜다. 첫 번째는 “LLM‑generated” 방식으로, 논문에서 제시한 프롬프트와 가이드라인에 따라 자동으로 생성된 AGENTS.md 파일이다. 두 번째는 “developer‑provided” 방식으로, 실제 레포지토리 소유자가 커밋한 파일이다. 두 파일 모두 레포지토리 개요, 빌드·테스트 명령, 스타일 가이드, 사용 도구 등을 기술한다.

성공률(Success Rate)은 에이전트가 제시한 패치가 모든 테스트를 통과했는지 여부로 정의한다. 결과는 다음과 같다. (1) 컨텍스트 파일이 전혀 없을 때 평균 성공률은 약 45 % 수준이었다. (2) 자동 생성된 컨텍스트 파일을 제공하면 성공률이 평균 3 %포인트 감소했다. (3) 개발자가 직접 작성한 파일을 제공하면 오히려 4 %포인트 정도 소폭 상승했지만, 통계적으로 유의미한 차이는 아니었다.

비용 측면에서는, 컨텍스트 파일을 포함했을 때 LLM 호출 토큰 수와 실행 시간 모두 20 % 이상 증가했다. 이는 에이전트가 파일을 파싱하고, 명시된 명령을 따르며, 추가적인 테스트를 수행하려는 “탐색적 행동”이 늘어났기 때문이다. 트레이스 분석 결과, 컨텍스트 파일이 존재하면 에이전트는 (a) 더 많은 파일을 열어보고, (b) 테스트 스위트를 확대 실행하며, (c) 빌드·런타임 명령을 정확히 재현하려는 경향을 보였다. 이러한 행동은 궁극적으로 비용을 높이지만, 코드 품질이나 버그 회피 측면에서 긍정적인 부작용을 만들 수 있다.

핵심 인사이트는 다음과 같다. 첫째, 현재 일반적인 AGENTS.md 템플릿은 “불필요한 요구사항”을 과도하게 포함하고 있어, 에이전트가 문제 해결에 집중하기보다 템플릿을 해석하는 데 리소스를 소모한다. 둘째, 인간이 직접 작성한 파일도 최소한의 요구사항(예: 사용해야 할 빌드 도구, 테스트 명령)만 포함한다면 약간의 성능 향상을 기대할 수 있다. 셋째, 자동 생성된 파일은 현재 프롬프트와 모델 한계 때문에 오히려 혼란을 초래한다는 점에서, 무조건 사용하기보다는 상황에 맞게 선택해야 한다.

이러한 결과는 코딩 에이전트 개발자와 레포지토리 관리자가 컨텍스트 파일을 설계할 때 “필수적인 정보만 제공”하고, 과도한 스타일 가이드나 비핵심 요구사항은 배제해야 함을 시사한다. 또한, 자동 생성 파이프라인을 개선하려면 LLM이 레포지토리 구조와 테스트 의존성을 정확히 파악하도록 사전 학습 데이터와 프롬프트를 정교화할 필요가 있다.