💻 computer science

Do Context Files Help Coding Agents? A Two-Agent Ablation Study on Real Repositories

이 논문은 지속적인 컨텍스트 파일(예: AGENTS.md)이 코딩 에이전트의 정확도를 측정 가능한 수준으로 향상시키지 못한다는 것을 입증하는 통제된 절제 연구를 제시하는데, 이는 실패의 원인이 누락된 저장소 지식이 아니라 구현 기술의 결핍에서 비롯되기 때문이며, 또한 에이전트별 작업 난이도 차이를 통해 이전의 모순된 연구 결과들을 설명한다.

원저자: Prakhar Khatri

게시일 2026-07-31

📖 4 분 읽기☕ 가벼운 읽기

CC BY 4.0

원저자: Prakhar Khatri

원본 논문은 CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/) 라이선스로 제공됩니다. ✨ 이것은 아래 논문에 대한 AI 생성 설명입니다. 저자가 작성하거나 승인한 것이 아닙니다. 기술적 정확성을 위해서는 원본 논문을 참조하세요. 전체 면책 조항 읽기

디지털 사서 vs. 숙련된 건축가

당신이 아주 똑똑하지만 갓 태어난 로봇 조수에게 거대하고 지저한 작업장에서 복잡한 기계를 고치는 법을 가르치려 한다고 상상해 보세요. 당신에게는 두 가지 주요 방법이 있습니다. 첫째, 작업장에 대한 상세한 지도, 도구 사용법에 대한 규칙 목록, 그리고 기계가 보통 어떻게 작동하는지에 대한 가이드를 주는 것입니다. 컴퓨터 프로그래밍의 세계에서 이것은 '컨텍스트 파일'(종종 AGENTS.md 또는 CLAUDE.md라고 불림)이라고 불립니다. 이것은 마치 로봇의 책상 위에 놓인 포스트잇처럼 "기억해, 여기서는 항상 빨간색 나사를 사용해야 해!"라고 적혀 있는 것과 같습니다.

둘째, 그냥 로봇이 작업장 안을 돌아다니며 기계 자체를 보고 스스로 깨우치도록 내버려 두는 것입니다.

오랫동안 이러한 AI 코딩 어시스턴트를 만드는 사람들은 첫 번째 방식에 집착해 왔습니다. 그들은 로봇이 규칙을 더 잘 알게 된다면 더 좋은 코드를 작성할 것이라고 믿으며, 이 지침 매뉴얼을 작성하는 데 수 시간을 보냅니다. 하지만 여기서 중요한 질문이 생깁니다. 매뉴얼을 읽는 것이 실제로 로봇을 더 나은 건축가로 만드는 걸까요, 아니면 똑같은 실수를 저지르면서도 로봇이 더 자신감 있게 느끼게만 만드는 걸까요? 이것이 새로운 연구가 해결하고자 했던 미스터리입니다. 이 연구는 이러한 디지털 지침 매뉴얼이 더 나은 AI 코딩을 위한 마법의 열쇠인지, 아니면 그저 종이 낭비일 뿐인지를 테스트했습니다.

위대한 매뉴얼 테스트

이 연구에서 연구자들은 엄격한 과학 선생님 역할을 했습니다. 그들은 오늘날 가장 똑똑한 두 가지 AI 코딩 에이전트—Anthropic의 Claude와 OpenAI의 Codex—를 데려와 일련의 실제 코딩 과제를 주었습니다. 이것은 가짜 숙제 문제가 아니었습니다. 클라우드 툴킷의 버그를 수정하거나 컴파일러를 미세 조정하는 것과 같은 실제 소프트웨어 프로젝트에서 가져온 실제 작업들이었습니다.

매뉴얼이 도움이 되는지 확인하기 위해, 연구진은 각 로봇에게 동일한 작업을 세 가지 방식으로 수행하게 했습니다:

"노트 없음" 실행: 로봇이 작업은 받되 매뉴얼은 받지 못함.
"항상 켜짐" 실행: 로봇의 뇌 속에 매 단계마다 전체 매뉴얼이 통째로 주입됨.
"온 디맨드(요청 시)" 실행: 로봇이 막혔을 때 선택해서 읽을 수 있도록 정리된 작은 노트들의 라이브러리를 가짐.

연구진은 총 288번의 실험을 수행했으며, 최종 코드가 실제로 작동하는지 확인하기 위해 숨겨진 "골드 스탠다드(표준)" 테스트와 대조했습니다.

큰 놀라움: 매뉴얼은 서툰 건축을 고치지 못한다

결과는 매뉴얼을 쓰는 사람들에게 다소 충격적이었습니다. 연구 결과, 컨텍스트 파일이 있는 것이 AI가 작업을 성공적으로 완수하는 데 거의 아무런 차이를 만들지 못했다는 사실이 밝혀졌습니다.

로봇이 매뉴얼을 가지고 있든, 라이브러리를 가지고 있든, 혹은 아무것도 없든 성공률은 거의 비슷하게 유지되었습니다. Claude 로봇의 경우, 매뉴얼이 결과에 10%포인트 이상의 변화를 주지 못했습니다. Codex 로봇의 경우에도 15%포인트 이상의 변화를 주지 못했습니다. 과학의 세계에서 이것을 "귀무 결과(null result)"라고 부릅는데, 이는 우리가 중요할 것이라고 생각했던 것이 실제로는 그렇지 않음을 의미합니다.

연구진은 왜 매뉴얼이 도움이 되지 않았는지 알아내기 위해 더 깊이 파고들었습니다. 그들은 로봇이 정답에 거의 근접했지만 실패했던 순간들을 살펴보았습니다. 그들은 로봇이 매뉴얼에 있는 사실(예: "빨간색 나사를 사용하지 마시오")을 몰라서 실패한 것이 아니라, 건축 기술이 부족했기 때문에 실패했다는 것을 발견했습니다.

이렇게 생각해 보세요. 만약 당신이 천재적인 건축가에게 집의 완벽한 설계도를 주었지만, 그가 벽돌을 쌓거나 전등 스위치를 연결하는 법을 모른다면, 그 설계도는 그를 구원하지 못할 것입니다. 연구에 참여한 AI 에이전트들은 읽는 능력은 뛰어났지만, 실제 '행하는 것'에서 넘어졌습니다. 그들은 기능을 설계하고, 적절한 패턴을 선택하며, 조각들을 올바르게 연결하는 데 어려움을 겪었습니다. 매뉴얼은 그들에게 건축하는 법을 가르쳐 줄 수는 없었습니다. 단지 건물이 어떻게 생겼는지만 알려줄 수 있을 뿐이었습니다.

"모두에게 적용되는 것은 없다"는 반전

또 다른 흥ًا로운 발견이 있었습니다. 연구진은 한 로봇에게는 매우 쉬운 작업이 다른 로봇에게는 매우 어려울 수 있다는 점을 주목했습니다. 이는 어떤 사람은 수학 퍼즐은 잘 풀지만 저글링은 엉망인 반면, 그 친구는 그 반대인 것과 같습니다.

이 때문에 연구는 이전의 연구들이 혼란을 겪었을 수 있다고 시사합니다. 만 만약 한 과학자가 매뉴얼이 쉬운 과제를 수행하는 로봇을 대상으로 테스트했다면, 다른 과학자가 어려운 과제를 수행하는 로봇을 대상으로 테스트했을 때 서로 다른 결과를 얻었을 것입니다. 매뉴얼이 실제로 도움이 될 수 있는 "스윗 스팟(최적의 지점)"은 모든 AI의 뇌마다 다를 수 있습니다.

매뉴얼이 조금이라도 도움이 되었나?

그렇다면 매뉴얼은 완전히 쓸모없는 것이었을까요? 전적으로 그렇지는 않았지만, 그 이점은 매우 구체적이고 작았습니다.

속도와 비용: 특정 프로젝트에서 로봇이 매뉴얼을 가지고 있을 때, 불필요하고 느린 테스트를 실행하지 않았습니다. 마치 로봇이 "이 테스트는 20분이 걸립니다"라는 표지판을 읽고 이를 건너뛰기로 결정한 것과 같았습니다. 이는 시간을 절약해주었지만, 코드를 더 '좋게' 만들지는 않았습니다.
"아까운 실패(Near-Miss)" 테스트: 연구진은 로봇이 거의 해결할 뻔했던 과제들을 가져와서, 고품질의 실제 매뉴얼을 제공하여 그것이 성공으로 이어지는지 확인하는 특별한 실험을 했습니다. 결과는 실패였습니다. 최고의 지침이 있어도 로봇은 여전히 "아까운 실패"를 "성공"으로 바꾸지 못했습니다.

결론

이 연구는 테스트된 AI 코딩 에이전트들에게 완벽한 지침 매뉴얼(AGENTS.md)을 작성하는 데 시간을 쏟는 것이 아마도 더 나은 코드를 작성하게 만들지는 못한다고 결론짓습니다. 문제는 로봇이 규칙을 모르는 것이 아니라, 소프트웨어를 만드는 실제 기술(craft)을 익혀야 한다는 것입니다.

이러한 매뉴얼이 로봇이 조금 더 빠르게 작업하거나 나쁜 습관을 피함으로써 아주 약간의 비용을 아끼는 데는 도움이 될 수 있지만, 깨진 코드를 고치는 마법 지팡이는 아닙니다. 만약 당신의 AI 어시스턴트가 더 나은 건축가가 되기를 원한다면, 이 연구는 단순히 더 많은 규칙을 읽게 하는 것보다 작업을 더 작은 단계로 나누거나 어떻게 만드는지에 대한 더 좋은 예시를 제공하는 것이 더 나은 결과를 가져올 것이라고 제안합니다.

기술 요약: 컨텍스트 파일이 코딩 에이전트에게 도움이 되는가?

문제 정의

지속적인 컨텍스트 파일(예: AGENTS.md, CL_AUDE.md)은 AI 코딩 에이전트를 가이드하기 위한 표준 인프라로 자리 잡았으며, Claude Code와 같은 플랫폼들은 세션 중에 이를 자동으로 로드합니다. 실무자들은 코딩 컨벤션, 아키텍처 제약 조건, 워크플로우 가이드를 정의하기 위해 이 파일들을 작성하는 데 상당한 노력을 기울이며, 이를 통해 코드 생성 능력이 향상될 것을 기대합니다. 그러나 컨텍스트 파일의 효과에 대한 경험적 증거는 상충됩니다. 일부 연구는 효율성 향상(런타임 감소, 토큰 절감)을 보고하는 반면, 다른 연구들은 작업 완료 정확도에 유의미한 효과가 없다고 보고합니다. 기존 문헌은 에이전트 제품군(Codex vs. Claude), 평가 방법, 특히 컨텍스트가 주입되는 방식에 따른 실험 제어의 차이로 인해 이러한 결과들을 화해시키지 못하고 있습니다.

방법론

본 연구는 두 가지 프런티어 코딩 에이전트(Claude Code 및 Codex)를 대상으로 실제 저장소와 작업을 사용하여 컨텍스트 주입 전략에 대한 통제된 절제 연구(ablation study)를 제시합니다.

실험 설계

에이전트: 두 가지 구별되는 에이전트를 평가했습니다: Claude Code (claude-sonnet-4-6)와 Codex CLI (gpt-5.5).
저장소 및 작업: 본 연구는 다양한 AGENTS.md 품질과 길이를 가진 3개의 Python 저장소(pdm, firebase-admin-python, opshin)를 활용했습니다. 작업은 머지된 풀 리퀘스트(PR)에서 추출되었으며, 에이전트가 변경 사항을 구현하고 숨겨진 "골드(gold)" 테스트를 통해 검증해야 하는 과제들로 구성되었습니다(SWE-bench Tier-C 스타일). 최종 세트는 Codex의 경우 17개, Claude의 경우 15개의 작업을 포함했습니다.
주입 전략 (독립 변수): 세 가지 구별된 전략을 테스트했습니다:
1. NONE (없음): 워크스페이스에서 AGENTS.md 파일을 제거합니다. 컨텍스트가 제공되지 않습니다.
2. ALWAYS ON (항상 켬): 전체 AGENTS.md 내용을 매 턴 시스템 프롬프트에 주입합니다.
3. SELECTIVE (선택적): 주제별로 정리된 위키 파일들을 워크스페이스에 배치하고, 시스템 프롬프트 힌트를 통해 에이전트가 필요 시 'Read' 도구를 사용하여 관련 파일을 직접 검색하도록 유도합니다.
평가: 각 작업은 세 가지 전략 모두에서 3회 독립 반복 실행되었습니다(총 288회 실행). 성공 여부는 모든 골드 테스트가 통과했는지 여부로 엄격히 정의되었습니다. 효율성 지표에는 도구 호출 횟수, 실제 소요 시간(wall-clock time), 토큰 사용량이 포함되었습니다.
통계 분석: 본 연구는 옴니버스스 퍼뮤테이션 테스트(omnibus permutation tests), 효율성 측정을 위한 쌍체 윌콕슨 부호 순위 검정(paired Wilcoxon signed-rank tests), 그리고 컨텍스트 주입의 효과 크기를 제한하기 위한 일방 검정(Two One-Sided Tests, TOST)을 사용했습니다.

주요 기여

통제된 이중 에이전트 절제 연구: 288회의 실행을 통한 엄격한 연구를 통해, 컨텍스트 주입 전략이 두 에이전트 모두에서 정확도를 유의미하게 변화시키지 않음을 입증했습니다. 효과는 등가 검정(equivalence testing)을 통해 10~15%포인트(pp) 이내로 제한되었습니다.
실패 모드 분류 및 조작 프로브: 에이전트가 실패하는 주된 원인이 저장소 지식의 부재가 아니라 구현 기술(기능 설계, 패턴 선택, 정확한 연결/wiring)에 있다는 증거를 제시했습니다. 특정 프로브를 통해 실제 AGENTS.md 파일이 두 에이전트 모두에서 "아쉬운 실패(near-miss)"를 성공으로 전환시키지 못함을 확인했습니다.
에이전트별 경계 난이도: 작업 난이도가 에이전트마다 다름을 입증했습니다. 동일한 작업이라도 한 에이전트에게는 사소한 수준인 반면, 다른 에이전트에게는 도전적인 과제가 될 수 있습니다(통과율의 Spearman $\rho=0.75$ 상관관계가 있으나, 서로 다른 "정보적 밴드(informative bands)"를 가짐). 이는 단일 에이전트 연구에서 나타나는 이전의 상충되는 결과들에 대한 후보 설명을 제공합니다.

결과

정확도

효과 없음: 컨텍스트 주입이 정확도 향상에 통계적으로 유의미한 영향을 미치지 않았습니다.
- Claude: 통과율은 53.3% (NONE), 55.6% (ALWAYS ON), 55.6% (SELECTIVE)였습니다.
- Codex: 통과율은 58.8% (NONE), 56.9% (ALWAYS ON), 52.9% (SELECTIVE)였습니다.
등가 범위: TOST 분석 결과, 쌍별 전략 차이는 Claude의 경우 <10pp, Codex의 경우 <15pp로 제한되었습니다.
경계선상의 작업: 컨텍스트 주입이 효과를 감지할 수 있는 통계적 검정력을 가진 경계 난이도의 작업에서도, 컨텍스트 주입은 통과율을 개선하지 못했습니다. 예를 들어, 4개의 Codex 경계 작업에서 NONE은 58%의 통과율을 보인 반면, ALWAYS ON과 SELECTIVE는 모두 42%였습니다.

효율성

Claude: SELECTIVE 전략은 NONE과 비교했을 때 캐시 생성 토큰을 유의미하게 줄였습니다. 이는 매 턴 전체 파일을 주입하는 대신 짧은 힌트만 주입하는 메커니즘의 차이 때문입니다.
Opshin 특이사항: 테스트 스위트 실행 시간에 대한 명시적 경고가 컨텍스트 파일에 포함되어 있던 opshin 저장소의 경우, Claude는 컨텍스트가 존재할 때 무분별한 전체 스위트 테스트 실행과 실제 소요 시간이 용량 의존적으로(dose-dependent) 감소하는 양상을 보였습니다. 이는 결과적 효과(정확도)가 아닌 프로세스 수준의 효과(에이전트의 작동 방식)입니다.
Codex: 모든 효율성 지표가 전략 간에 평이한 수준을 유지했습니다.

실패 분석

아쉬운 실패(near-miss) 사례들을 조사한 결과, 오류는 엔지니어링의 정밀도, 아키텍처 패턴 선택, 타입 시스템 추론의 공백에서 기인했습니다. 이러한 실패 중 어느 것도 컨텍스트 파일이 제공할 수 있는 "누락된 사실"을 나타내지 않았습니다. 또한, 조작 타당성 프로브(manipulation-validity probe)를 통해 고품질의 AGENTS.md 파일조차 아쉬운 실패를 구제할 수 없음을 확인했습니다.

의의 및 주장

본 논문은 일반적인 컨텍스트 문서를 작성하는 광범위한 관행이 코딩 에이전트의 정확도 측면에서 수확 체감(diminishing returns)을 가져올 수 있다고 주장합니다. 실제 코딩 작업에서의 주요 실패 메커니즘은 저장소 지식의 부족이 아니라 구현 기술의 부족입니다.

이전 연구와의 화해: 이전 문헌(예: Lulla et al. 대 Gloaguen et al.)의 상충되는 결과는 에이전트마다 서로 다른 "정보적 밴드"의 작업 난이도를 가지고 있기 때문인 것으로 보입니다. 한 에이전트에게는 (컨텍스트가 이론적으로 도움이 될 수 있는) 경계 영역에 있는 작업이 다른 에이전트에게는 바닥(floor) 또는 천장(ceiling) 영역에 위치하여 컨텍스트 효과가 보이지 않을 수 있습니다.
실무적 시사점: 일반적인 컨텍스트 문서가 정확도를 눈에 띄게 개선하지는 못하더라도, 에이전트의 행동(예: 특정 경고가 있을 때 불필요한 테스트 실행 감소)에는 영향을 미칠 수 있습니다. 그러나 저자들은 일반적인 컨텍스트 문서를 작성하는 노력보다는 작업 분해(task decomposition), 툴링(tooling), 또는 예시 중심의 프롬프팅에 집중하는 것이 더 나을 수 있다고 제안합니다.
방법론적 기여: 본 연구는 향후 절제 연구에서 정보적인 동적 범위를 확보하기 위해 작업 선별(screening)의 필요성을 강조하며, 10pp의 작은 효과 크기를 적절한 검정력으로 탐지하기 위해서는 약 120개의 작업 규모가 필요함을 명시합니다.

저자들은 향후 이 설계를 확장할 수 있도록 모든 코드, 데이터 및 분석을 공개합니다.