AGENTS.md 품질이 코딩 에이전트 성패를 결정, 프로브-정제 튜닝 제안

LLM 기반 코딩 에이전트에게 저장소 안내 파일이 도움이 되는지는 그동안 논쟁적이었다. 이 논문은 결정적 변수가 안내 파일의 존재 여부가 아니라 생성 방식임을 실험으로 보여준다. 합성 프로브를 활용한 반복 정제로 에이전트가 올바른 파일을 찾아가는 능력이 크게 향상됐으며, 이는 코드 수정 능력이 아닌 탐색 능력이 실제 병목임을 시사한다.

안내 파일이 중요한 이유

LLM 기반 코딩 에이전트가 코드베이스를 다루는 방식은 인간 개발자와 근본적으로 다르다. 인간은 저장소를 처음 접할 때 동료에게 묻거나, 위키 문서를 뒤지거나, 히스토리를 천천히 익히면서 "이 프로젝트에서는 이런 식으로 일한다"는 암묵적 지식을 체득한다. 에이전트에게는 그런 유기적 온보딩 과정이 없다. 코드 자체에는 담기지 않은 운영 지식, 즉 어떤 서브시스템이 어느 파일에 있는지, 테스트는 어떻게 실행하는지, 어떤 수정 방식이 역사적으로 잘못된 결과를 낳았는지 같은 정보를 에이전트는 처음부터 갖추고 있지 않다.

그 공백을 메우기 위해 엔지니어들은 AGENTS.md 파일(혹은 CLAUDE.md, COPILOT-INSTRUCTIONS.md 같은 다양한 이름의 파일)을 유지 관리한다. 에이전트가 작업을 시작하기 전 읽어야 할 지침서로, 저장소의 구조와 관행을 압축해 담는다. 그런데 이 파일이 실제로 도움이 되는지는 놀랍도록 논쟁적이었다. 최근 연구들 사이에서도 LLM이 생성한 안내 파일이 에이전트 성능을 올린다는 결과와 오히려 해친다는 결과가 공존하며 서로 상충한다.

Asa Shepard와 Jeannie Albrecht의 논문은 이 논쟁에서 결정적 변수를 찾아낸다. 안내 파일 자체의 존재 여부나 내용의 세부 사항보다, 그 파일이 어떻게 만들어졌느냐가 성능을 결정한다는 것이다.

프로브-정제 튜닝의 작동 방식

이 논문이 제안하는 방법은 "프로브-정제 튜닝(probe-and-refine tuning)"이다. 핵심 아이디어는 단순하다. 실제 버그 수정 과제를 에이전트에게 시키기 전에, 합성 버그 수정 프로브를 활용해 현재 안내 파일이 어디서 실패하는지를 진단하고, 그 진단 결과로 파일을 패치한다. 이 과정은 에이전트 루프나 툴 사용 없이 단일 LLM 호출만으로 반복적으로 수행된다.

튜닝 과정이 끝나면 정제된 안내 파일을 얻는다. 이 파일은 정적으로 구축된 지식 베이스와 달리, 실제 실패 사례에서 귀납된 운영 지식을 담고 있다. SWE-bench Verified에서 Qwen3.5-35B-A3B 모델로 200 스텝, 4회 독립 시험을 진행한 결과, 프로브-정제 튜닝은 33.0%의 평균 해결률을 달성했다. 이 수치는 정적 지식 베이스 초기화 결과(28.3%)보다 유의미하게 높고, 안내 없이 에이전트를 실행했을 때(25.5%)와는 더욱 큰 격차를 보인다(p < 0.001).

정밀도가 아닌 범위의 문제

이 실험 결과에서 가장 흥미로운 해석은 성능 향상의 원인 분석에 있다. 연구진은 개선이 정밀도(precision)가 아닌 범위(coverage)에서 비롯된다는 점을 밝혀냈다. 정제된 안내 파일을 받은 에이전트는 14.5 퍼센트포인트 더 많은 인스턴스에서 평가 가능한 패치를 생성했다. 반면 패치당 정밀도, 즉 패치를 만들었을 때 그것이 올바를 확률은 약 59%로 통계적으로 유의미한 변화를 보이지 않았다(p = 0.119).

이것이 의미하는 바는 뚜렷하다. 정제된 안내 파일은 에이전트가 변경해야 할 파일을 찾아가는 능력을 높인다. 일단 올바른 파일에 도달했을 때 변경의 품질을 높이지는 않는다. 에이전트의 병목은 코드 수정 능력이 아니라 저장소 탐색 능력에 있다는 뜻이다.

스텝 예산 실험은 이 해석을 더욱 강화한다. 안내 파일 없이 에이전트의 스텝 수를 늘리면 성능이 나아지지 않거나 오히려 악화된다. 그러나 정제된 안내 파일이 있을 때는 더 많은 스텝을 생산적으로 활용할 수 있다. 안내 파일은 단순히 에이전트에게 힌트를 주는 것을 넘어, 더 큰 계산 예산을 효율적으로 활용하는 조건이 된다는 의미다.

한편 NVIDIA Nemotron-3-Nano-30B-A3B로의 교차 모델 실험에서는 주의할 점도 드러났다. 해당 모델이 충분히 진단적인 출력을 생성하지 못할 경우 튜닝 루프의 효과가 저하됐다. 프로브-정제 방식이 효과를 내려면 LLM 자체가 어디서 실패했는지를 의미 있게 설명할 수 있는 능력을 갖춰야 한다. 이는 방법론의 한계이자 적용 조건이다.

코딩 에이전트의 성능을 높이려는 논의는 대부분 모델 능력이나 강화학습, 또는 툴 활용 방식에 집중된다. 이 논문은 그 대신 저장소 안내 파일이라는 훨씬 저렴하고 유지 가능한 지점을 겨냥한다. 어떤 파일을 수정해야 하는지 아는 것, 이 당연해 보이는 지식이 에이전트 성능의 핵심 병목임을 실험으로 보여준다는 점에서 주목할 만하다.