AI 코딩 에이전트와 함께 작업할 때 CLAUDE.md나 agents.md 같은 컨텍스트 파일을 제공하면 성능이 향상될 것이라 믿어왔습니다. 하지만 최근 발표된 논문은 정반대의 결과를 보여줍니다. 컨텍스트 파일이 오히려 AI를 멍청하게 만들고 비용은 20% 이상 증가시킨다는 것입니다.
AI 컨텍스트의 구조와 우선순위
AI가 코드를 생성할 때 참조하는 컨텍스트는 크게 세 가지 계층으로 구성됩니다. 첫 번째는 사용자가 접근할 수 없는 시스템 프롬프트로, Anthropic이나 OpenAI가 모델을 특정 방향으로 유도하기 위해 사전에 설정한 지시사항입니다. 두 번째는 메모리 파일로, CLAUDE.md나 agents.md 같은 프로젝트 컨텍스트 파일이 여기에 해당합니다. 세 번째는 사용자 프롬프트와 AI의 이전 응답들입니다.
중요한 점은 우선순위입니다. 인간의 기억과 마찬가지로 AI도 처음과 마지막 정보에 가장 높은 가중치를 둡니다. 따라서 메모리 파일은 사용자 프롬프트보다 먼저 주입되므로 더 높은 우선순위를 가집니다. 이론적으로는 프로젝트 아키텍처, 필수 명령어 등을 담은 메모리 파일이 AI 성능을 향상시켜야 하는데, 왜 실제로는 그렇지 않을까요?
논문의 연구 방법론과 놀라운 결과
이 연구는 Repository level context files helpful for coding agent라는 제목으로, 실제 GitHub의 Pull Request를 모아 AgentBench라는 새로운 벤치마크를 구축했습니다. PR 정보만 AI에게 제공하고 테스트를 통과할 수 있는지 평가하는 방식입니다. 업계 표준인 SWE-bench도 함께 사용하여 신뢰도를 높였습니다.
테스트는 세 가지 조건에서 진행되었습니다. 첫째, 컨텍스트 파일이 전혀 없는 경우. 둘째, LLM이 자동으로 생성한 컨텍스트 파일을 제공한 경우. 셋째, 인간 개발자가 직접 작성한 컨텍스트 파일을 제공한 경우입니다.
결과는 충격적입니다. AI가 자동 생성한 컨텍스트 파일은 아무것도 주지 않았을 때보다 작업 성공률을 AgentBench에서 평균 2%, SWE-bench Lite에서 0.5% 떨어뜨렸습니다. 추론 비용은 20% 이상 증가했습니다. 모델별로 살펴보면 QWen 3 30B를 제외한 대부분의 모델에서 컨텍스트 파일이 없을 때 더 적은 스텝으로 첫 응답을 내놓았고, 비용도 더 적게 발생했습니다.
인간이 직접 작성한 컨텍스트 파일의 경우는 다릅니다. LLM이 생성한 파일보다 성공률이 높았고, Claude Sonnet을 제외한 대부분의 모델에서 컨텍스트가 없을 때보다 약 19% 높은 성공률을 보였습니다. 이는 개발자가 AI를 다루는 능력이 AI가 스스로를 다루는 것보다 우수하다는 반증입니다.
왜 컨텍스트 파일이 오히려 방해가 될까
논문은 에이전트가 PR과 관련된 파일의 첫 인터랙션까지 필요한 스텝 수를 분석했습니다. 메모리 파일이 있으면 AI가 레포지토리 구조를 더 빨리 파악할 것 같지만, 실제로는 오히려 더 많은 스텝이 필요했습니다. 컨텍스트 파일이 프로젝트 가이드로서 제대로 역할을 하지 못한다는 의미입니다.
툴 사용 횟수 분석에서도 같은 패턴이 나타납니다. 컨텍스트 파일을 제공하면 에이전트가 더 많은 툴을 실행하고 코드베이스를 불필요하게 넓게 탐색하며 에너지를 낭비합니다. GPT-4o의 경우 컨텍스트 파일 처리를 위해 추론 토큰을 22% 더 사용했고, GPT-4o mini는 14% 더 사용했습니다.
핵심 원인은 중복과 노이즈입니다. 레포지토리에서 에이전트가 쉽게 파악할 수 있는 요소가 CLAUDE.md나 agents.md에 이미 들어가 있는 경우가 많습니다. 게다가 현재 작업과 무관한 내용들이 섞여 있으면 AI가 목표를 향해 가는 과정에서 혼란을 겪습니다.
실전 가이드
컨텍스트 파일을 효과적으로 관리하려면 다음 접근법을 따르세요.
먼저 CLAUDE.md 파일의 크기를 정기적으로 점검합니다. 파일이 커질수록 불필요한 내용이 쌓일 가능성이 높습니다. 현재 진행 중인 작업과 직접 관련 없는 설명, 예시, 가이드라인은 과감히 제거하세요. 특히 “하지 말아야 할 것” 목록은 오히려 AI의 주의를 그쪽으로 끌 수 있으므로 최소화합니다.
다음으로 스킬 기반 컨텍스트 분리 전략을 채택합니다. CLAUDE.md에는 모든 작업에 공통적으로 필요한 최소한의 정보만 남기고, 특정 작업에 필요한 상세 문서와 가이드라인은 별도의 스킬로 분리합니다. 예를 들어 S3 버킷에 비디오를 업로드하는 작업을 할 때, 그 작업에 필요한 스킬만 트리거하여 인증, 프레임워크, 다른 폴더 구조 같은 무관한 정보가 주입되지 않도록 합니다.
마지막으로 컨텍스트 파일을 작성할 때는 다큐멘테이션이 아닌 필수 지시사항 모음으로 접근합니다. 프로젝트 전체를 설명하려 하지 말고, AI가 반드시 따라야 할 제약사항과 필수 패턴만 간결하게 명시하세요. 이 과정에서 대략 10-15분 정도 걸리며, 한 달에 한 번 정도 점검하면 충분합니다.
비판적 검토
이 논문은 AI 에이전트와의 협업에서 컨텍스트 파일의 실제 효과를 정량적으로 분석한 첫 연구라는 점에서 가치가 큽니다. 특히 AgentBench라는 새로운 벤치마크를 구축하고 SWE-bench와 교차 검증한 방법론은 신뢰할 만합니다.
다만 논문의 결론을 “컨텍스트 파일은 필요 없다”로 단순화해서는 안 됩니다. 인간이 작성한 컨텍스트 파일이 19% 성공률 향상을 보인 점은 명백한 증거입니다. 진짜 문제는 잘못 작성된 컨텍스트 파일입니다. 실무에서는 벤치마크 환경보다 훨씬 복잡한 상황이 많으므로, 프로젝트 특성에 맞게 컨텍스트 관리 전략을 조정해야 합니다.
19%라는 상승률을 어떻게 평가할지도 논쟁의 여지가 있습니다. 컨텍스트 파일을 지속적으로 관리하는 데 드는 시간과 노력을 고려하면, 그 비용 대비 효과가 충분한지 프로젝트마다 달라질 수 있습니다. 에이전틱 AI 시대에 컨텍스트 파일 관리에 투입되는 리소스를 실제 작업 검증에 사용하는 것이 더 효율적일 수도 있습니다.
데이터 기반 인사이트
논문의 Figure 3에서 AI 생성 컨텍스트 파일은 AgentBench에서 평균 2%, SWE-bench Lite에서 0.5%의 성공률 감소를 기록했습니다. 동시에 Table에서 컨텍스트 파일이 없을 때 첫 응답까지의 스텝 수가 가장 적었고 비용도 최소화되었습니다.
Figure 6의 툴 사용 횟수 분포를 보면, 컨텍스트 파일이 있을 때 분포가 오른쪽으로 치우쳐 더 많은 툴 호출이 발생했습니다. 다만 인간이 작성한 컨텍스트 파일의 경우 유의미하게 툴 사용이 줄어든 케이스들이 관찰되었습니다.
Figure 7에서 GPT-4o는 컨텍스트 파일 처리를 위해 추론 토큰을 22% 더 소비했고, GPT-4o mini는 14% 증가했습니다. 이는 직접적인 비용 증가로 이어집니다.
가장 중요한 데이터는 인간이 작성한 컨텍스트 파일이 LLM 생성 파일 대비 일관되게 더 나은 성능을 보였다는 점입니다. Claude Sonnet을 제외한 대부분의 모델에서 19% 정도의 성공률 향상이 확인되었습니다. 이는 개발자의 도메인 지식과 판단력이 여전히 AI 성능을 좌우하는 핵심 요소임을 증명합니다.
핵심 요점
- CLAUDE.md나 agents.md를 다큐멘테이션처럼 꽉 채워 작성하면 AI 성능이 오히려 저하되고 비용은 20% 이상 증가합니다. 컨텍스트 파일은 필수 지시사항만 담은 간결한 가이드여야 하며, 현재 작업과 무관한 정보는 노이즈가 되어 AI의 집중력을 분산시킵니다.
- 인간이 직접 작성한 컨텍스트 파일은 평균 19% 성공률 향상을 가져오지만, LLM이 자동 생성한 파일은 오히려 성능을 떨어뜨립니다. 이는 개발자가 프로젝트의 핵심 요구사항을 판별하는 능력이 AI보다 우수함을 보여줍니다. 따라서 슬래시 명령어로 자동 생성한 컨텍스트를 맹신하지 말고 반드시 검토하고 다듬어야 합니다.
- 스킬 기반으로 컨텍스트를 분리하면 작업별로 필요한 정보만 선택적으로 주입할 수 있습니다. CLAUDE.md에는 모든 작업 공통 사항만 남기고, 특정 기능 개발에 필요한 상세 가이드는 해당 스킬에 포함시키세요. 이렇게 하면 S3 업로드 작업 시 인증 로직이나 다른 모듈 정보가 불필요하게 주입되지 않습니다.
- AI 에이전트는 컨텍스트 파일의 지시사항을 매우 충실히 따르려 하므로, 잘못된 가이드는 탐색 범위를 불필요하게 넓히고 툴 사용을 증가시킵니다. 논문에서 컨텍스트 파일이 있을 때 PR 관련 파일까지의 첫 인터랙션 스텝이 오히려 늘어난 것이 이를 증명합니다. 따라서 “하지 말아야 할 것” 목록은 최소화하고, 해야 할 것만 명확히 명시하세요.
- 최근 AI가 멍청해졌다고 느낀다면 99% 확률로 컨텍스트 파일 관리 문제입니다. 정기적으로 CLAUDE.md를 점검하여 불필요한 내용을 제거하고, 프로젝트가 변화함에 따라 더 이상 유효하지 않은 지시사항을 업데이트하세요. 이 작업에 한 달에 10-15분만 투자해도 AI 협업 효율이 크게 개선됩니다.
참고자료
- 논문: Repository level context files helpful for coding agent
- AgentBench: 논문에서 새로 구축한 GitHub PR 기반 벤치마크
- SWE-bench: 소프트웨어 엔지니어링 벤치마크
- 스킬 매니지먼트 시스템: 코드팩토리 채널의 설날 선물로 제공된 컨텍스트 분리 방법론