AI 코딩 에이전트 성능, CLAUDE.md가 오히려 독이 될 수 있다

AI 코딩 에이전트 성능을 높이려고 CLAUDE.md를 꼼꼼하게 채워두셨나요? 사실 그 파일이 오히려 에이전트를 느리고 비효율적으로 만들고 있을 수 있습니다. 2026년 2월 arXiv에 게재된 논문 "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?"(논문 번호 2602.11988)가 이를 데이터로 증명했는데, LLM이 자동 생성한 컨텍스트 파일은 작업 성공률을 떨어뜨리고 비용을 20% 이상 끌어올린다는 결과가 나왔습니다. 다만 인간이 직접 최소한의 정보만 담아 작성한 컨텍스트 파일은 성공률을 평균 약 19% 향상시킨다는 것도 함께 확인됐습니다. 어떻게 쓰느냐가 전부인 셈입니다.

 

 

컨텍스트 파일이 뭔가요? AI 기억의 구조부터 이해하기

Claude Code나 다른 AI 에이전트를 다루는 분들 중에서 CLAUDE.md나 AGENTS.md가 낯설 수 있으니, 잠깐 짚어보겠습니다. AI 에이전트가 대화를 처리할 때 컨텍스트는 크게 네 가지 계층으로 구성됩니다.

 

가장 먼저 들어오는 것이 시스템 프롬프트입니다. Anthropic이나 OpenAI가 직접 모델을 특정 방향으로 운영하기 위해 설정한 프롬프트로, 일반 사용자는 접근하거나 변경할 수 없습니다. 그다음이 바로 우리가 직접 다룰 수 있는 영역인 메모리 파일입니다. CLAUDE.md(Claude Code 전용)나 AGENTS.md(범용 에이전트용)가 여기에 해당합니다. 기능적으로는 동일하고, 어떤 에이전트를 사용하느냐에 따라 파일명이 달라지는 것뿐입니다. 세 번째는 우리가 직접 입력하는 유저 프롬프트, 네 번째는 같은 세션 안에서 AI가 낸 답변 기록이 순서대로 쌓입니다.

 

이 구조에서 중요한 포인트가 하나 있습니다. 사람이든 AI든 정보를 가장 잘 기억하는 위치는 처음과 끝이라는 점입니다. 심리학에서 말하는 초두 효과와 최신 효과가 AI 컨텍스트에도 그대로 적용됩니다. 메모리 파일은 컨텍스트의 가장 앞에 배치되므로 이론적으로 가장 높은 우선순위를 갖습니다. 그래서 프로젝트 아키텍처, 코딩 규칙, 필수 명령어를 여기에 담아두면 에이전트가 항상 참고할 것이라 기대하게 되는 거죠.

 

이론적으로는 완벽합니다. 하지만 실제로는 그렇지 않은 경우가 훨씬 많습니다.

 

 

논문이 밝힌 결과: CLAUDE.md 효과의 진실

이 논문이 해외 개발자 커뮤니티에서 화제가 된 이유는 결과가 직관에 반했기 때문입니다. 연구팀은 새로운 벤치마크인 AGENTbench를 만들었습니다. GitHub의 실제 PR들을 수집해 12개 Python 레포지토리에서 138개 인스턴스를 구성했고, 신뢰도를 높이기 위해 SWE-bench Lite(300개 인스턴스)와 병행 사용했습니다. Claude Code, Codex, Qwen Code 등 4개 코딩 에이전트를 세 가지 조건으로 나눠 테스트했습니다.

 

조건	성공률 변화	비용 변화
컨텍스트 파일 없음	기준값	기준값
LLM 자동 생성 파일 (/init 등)	AGENTbench -2%, SWE-bench -0.5%	+20~23% 증가
인간 개발자가 직접 작성한 파일	평균 약 +19% 향상	최대 +19% 증가

LLM이 자동 생성한 컨텍스트 파일은 아무것도 없는 것보다 성공률이 낮았습니다. 작업당 소요되는 단계도 2.45~3.92단계 더 늘어났고, 추론 비용은 20~23% 더 들었습니다. 더 많은 비용을 쓰고도 결과는 더 나빴습니다.

 

흥미로운 발견이 하나 더 있습니다. 이미 문서화가 잘 된 레포지토리에서 LLM이 생성한 컨텍스트 파일을 아예 제거했더니 성능이 오히려 2.7% 향상됐습니다. 기존 문서와 컨텍스트 파일이 겹치는 내용을 많이 담고 있었기 때문입니다.

 

추론 비용이 더 드는 구체적인 수치

논문은 추론 비용 증가를 모델별로 분석했습니다. GPT 5.2 계열 모델은 컨텍스트 파일을 처리하기 위해 추론 토큰을 22% 더 사용했고, GPT 5.1 mini는 14% 더 사용했습니다. 더 오래 생각하고 더 많은 비용을 쓴 결과가 더 낮은 성공률이었다는 점이 논문이 전하는 핵심 메시지입니다.

 

 

왜 이런 결과가 나올까? AI가 느려지는 진짜 이유

이 결과를 처음 접하면 고개를 갸웃하게 됩니다. 더 많은 정보를 주면 더 잘해야 하는 거 아닌가 싶으니까요. 논문과 실무 개발자들의 분석을 종합하면 크게 네 가지 원인으로 정리됩니다.

 

첫 번째, 현대 에이전트는 이미 자율적으로 탐색합니다. 오늘날 코딩 에이전트는 어떤 파일을 읽어야 하는지 스스로 결정할 수 있습니다. 레포지토리 구조를 직접 탐색하고, 필요한 파일을 골라 읽는 능력이 충분합니다. 컨텍스트 파일에 프로젝트 구조나 주요 파일 위치를 써놓더라도, 에이전트는 어차피 자기 방식으로 탐색을 시작합니다. 그 결과 컨텍스트 파일의 정보와 실제 탐색으로 얻은 정보가 중복되면서 오히려 처리 부담이 늘어납니다.

 

두 번째, 관련 없는 정보가 노이즈로 작용합니다. S3 버킷에 파일을 업로드하는 기능을 구현하는데 컨텍스트 파일에 인증 모듈 구조, 테스트 코드 작성 규칙, 다른 폴더의 설명이 가득 담겨 있다고 상상해보세요. 에이전트는 현재 작업과 관계없는 정보들을 모두 처리한 뒤 작업에 집중해야 합니다. 목표까지 가는 경로에 불필요한 갈림길이 계속 생기는 셈입니다.

 

세 번째, "하지 말라"는 금지 규칙의 역효과입니다. 사람도 "분홍색 코끼리를 생각하지 마세요"라는 말을 들으면 즉시 분홍색 코끼리를 떠올리게 됩니다. 에이전트도 비슷하게 반응합니다. 컨텍스트에 금지 사항이 많을수록 에이전트는 그 경우를 더 많이 검토합니다. 주의하라고 쓴 내용이 오히려 불필요한 탐색을 유발하는 것입니다.

 

네 번째, 도구 사용 횟수가 급격히 늘어납니다. 논문 분석에 따르면 에이전트는 컨텍스트 파일에 언급된 도구를 1.6~2.5배 더 자주 사용하는 경향이 있습니다. 언급됐다는 사실 자체가 에이전트가 그 도구를 더 많이 활용하도록 유도하는 것입니다. 광범위한 탐색으로 이어지고, 결국 더 많은 단계와 비용이 발생합니다.

 

그런데 인간이 작성한 파일은 왜 효과가 있나?

인간 개발자가 직접 작성한 컨텍스트 파일은 달랐습니다. 그 차이는 단순합니다. 사람은 지금 이 작업에 진짜 필요한 것만 골라서 씁니다. LLM이 컨텍스트 파일을 생성할 때는 "망라적으로" 정보를 포함하는 경향이 있습니다. 관련성이 낮더라도 있을 법한 내용들을 채워 넣습니다. 반면 실제 개발자는 자기가 작업하면서 "이거 에이전트가 모르면 헤매겠다"고 느낀 것만 씁니다. 결과적으로 노이즈가 없고 작업 지향적인 파일이 됩니다.

 

올바른 CLAUDE.md / AGENTS.md 작성법

논문 결과와 Anthropic 공식 문서, 실무 개발자들의 조언을 종합하면 컨텍스트 파일 작성의 방향이 명확해집니다. "이것도 넣고, 저것도 넣자"가 아니라 "이것만 넣자"가 핵심입니다.

 

포함해야 할 것 5가지

다음 다섯 가지는 에이전트가 코드만 봐서는 파악하기 어렵거나, 알고 있으면 작업 품질이 확실히 달라지는 정보들입니다.

 

• 프로젝트 한 줄 설명: "이 프로젝트는 Stripe 결제 시스템과 연동되는 Next.js 전자상거래 앱입니다"처럼 핵심 맥락을 한 문장으로
• 코드 스타일 규칙: 모듈 시스템, export 패턴, 포매팅 도구 등 이 프로젝트 고유의 컨벤션
• 빌드/테스트/린트/배포 명령어: 에이전트가 스스로 유추하기 어렵고, 틀리면 치명적인 명령어들
• 프로젝트 고유 주의사항: 일반적인 베스트 프랙티스가 아닌, 이 프로젝트만의 특이점이나 알아야 할 사항
• 주요 디렉토리 구조와 핵심 파일 위치: 복잡한 구조인 경우 핵심 경로만 간결하게

 

제외해야 할 것들 (흔한 실수)

채우고 싶은 마음은 이해하지만, 다음 내용들은 오히려 에이전트의 집중을 흐트러뜨립니다.

 

• 에이전트가 코드를 보면 스스로 파악할 수 있는 일반적인 베스트 프랙티스
• 코드 스니펫 (빠르게 구식이 되므로 파일 참조 방식인 @path/to/file으로 대체하는 것이 좋습니다)
• 현재 작업과 무관한 다른 모듈이나 기능 설명
• 린터/포매터가 처리하는 들여쓰기 스타일 같은 규칙들
• 가능한 모든 명령어 나열 (자주 쓰는 것만으로 충분합니다)

 

구조화와 경량화 팁

Anthropic 공식 문서는 "Claude가 이미 알고 있지 않은 정보만 추가하라"고 명시하고 있습니다. 모든 컨텍스트 토큰은 실제 작업 토큰과 경쟁하므로, 짧을수록 효과적입니다. 실무에서 검증된 구조화 방법은 다음과 같습니다.

 

구조화 체크리스트

• 300줄 미만 유지: 초과하면 즉시 검토하고 불필요한 내용 삭제
• 명확한 헤딩과 글머리 기호: 에이전트가 구조를 빠르게 파악할 수 있도록
• 모듈화: 주제별로 .claude/rules/ 서브디렉토리에 파일 분리
• 파일 참조 방식: @path/to/file로 CLAUDE.md 자체를 경량화
• 개인 설정 분리: CLAUDE.local.md를 .gitignore에 추가해 개인 설정만 별도 관리
• 활성 도구 80개 이하 유지: Anthropic 권장 기준

스킬 분리 전략: 핵심 조언

실무 개발자들 사이에서 주목받는 접근법이 있습니다. CLAUDE.md에 모든 것을 담으려 하지 말고, 특정 작업에만 필요한 정보는 스킬(Skill) 파일로 분리하는 방식입니다.

 

작동 방식은 간단합니다. 배포 절차, 특정 모듈 가이드, 코드 리뷰 규칙처럼 매번 필요한 건 아니지만 해당 작업을 할 때는 반드시 필요한 정보들을 스킬 파일로 분리해 둡니다. 에이전트가 해당 작업을 시작할 때만 그 스킬이 호출되어 필요한 컨텍스트만 주입되는 구조입니다. CLAUDE.md에는 정말 항상 필요한 최소 정보만 남고, 각 스킬에는 작업별 전문 정보가 담기게 됩니다.

 

이렇게 하면 어떤 작업을 하든 그 작업과 꼭 필요한 컨텍스트만 에이전트에게 전달됩니다. 논문이 입증한 "인간이 작성한 최소화된 컨텍스트 파일"의 효과를 작업별로 최대한 활용하는 방법입니다.

 

주기적인 정리와 유지보수

CLAUDE.md는 한 번 작성하고 잊어버리는 파일이 아닙니다. 프로젝트가 발전하면서 더 이상 필요 없어진 내용이 쌓이고, 어느 순간 파일이 비대해집니다. 몇 가지 습관을 들여두면 좋습니다.

 

파일 크기가 300줄에 가까워지면 직접 검토하면서 실제로 매번 필요한 내용인지 확인합니다. 실무에서 에이전트가 헤매는 패턴이 발견될 때마다 그 내용을 추가하는 피드백 루프를 만들면 파일이 살아있는 문서가 됩니다. 그리고 AI가 자동으로 생성한 내용은 그대로 두지 말고 반드시 직접 검토하고 수정한 다음 사용하세요. 논문 결과가 보여주듯, 그 차이가 성공률 약 19%를 결정합니다.

 

 

자주 하는 오해: CLAUDE.md를 아예 쓰지 말아야 하는 건가요?

논문이 발표된 뒤 해외 개발자 커뮤니티에서도 "그러면 CLAUDE.md를 다 지워야 하냐?"는 반응이 나왔습니다. 국내에서도 비슷한 오해가 퍼지고 있습니다. 결론부터 말씀드리면, 그게 아닙니다.

 

논문의 결론은 컨텍스트 파일의 폐지가 아니라 올바른 작성법에 대한 것입니다. 정확히는, LLM이 자동 생성한 파일이 문제이고 문서처럼 꽉 채워서 작성하는 방식이 문제입니다. 인간 개발자가 직접 필요한 것만 골라 작성한 파일은 성공률을 약 19% 높였습니다.

 

컨텍스트 파일은 새 팀원에게 주는 온보딩 문서와 비슷합니다. 두꺼운 매뉴얼보다 핵심만 담은 1페이지 요약이 실제로 더 도움이 됩니다. 100페이지짜리 매뉴얼을 주면 읽는 것 자체가 부담이 되고, 정작 필요한 내용을 찾기도 어려워집니다.

특히 위험한 패턴이 있습니다. CLAUDE.md를 일반 프로젝트 문서처럼 가득 채우는 것입니다. 이렇게 되면 LLM이 자동 생성한 파일과 비슷한 효과, 즉 성공률 하락과 비용 증가를 경험하게 됩니다.

 

최근 에이전트가 왠지 예전보다 덜 똑똑하게 느껴지거나, 불필요하게 많은 단계를 거쳐 결과를 내는 것 같다면 CLAUDE.md를 먼저 점검해보시길 권합니다. 파일이 언제 마지막으로 정리됐는지, 지금 진행 중인 작업과 관계없는 내용들이 얼마나 쌓였는지 확인해보면 생각보다 많은 내용이 정리될 겁니다.

 

 

정리: AI 코딩 에이전트 성능 최적화를 위한 핵심 원칙

논문 "Evaluating AGENTS.md"(arXiv 2602.11988)가 증명한 것은 명확합니다. 컨텍스트 파일의 존재 자체가 문제가 아니라, 어떻게 작성하느냐가 AI 코딩 에이전트 성능을 결정한다는 것입니다. 오늘부터 바로 적용해볼 수 있는 핵심 원칙 세 가지로 정리합니다.

 

핵심 원칙 3가지

1. LLM이 자동 생성한 컨텍스트 파일은 그대로 사용하지 않기. /init 등으로 생성된 파일은 반드시 직접 검토하고 필요한 것만 남겨서 사용하세요. 검토 없이 그대로 쓰면 성공률이 떨어지고 비용이 늘어납니다.
2. CLAUDE.md에는 "항상 필요한" 최소 정보만. 지금 진행하는 작업과 무관한 내용은 과감히 제거하세요. 모든 컨텍스트 토큰이 실제 작업과 경쟁한다는 점을 기억하세요.
3. 특정 작업에만 필요한 정보는 스킬(Skill)로 분리. 해당 작업 시에만 관련 스킬이 호출되도록 설계하면, 불필요한 컨텍스트가 주입되지 않습니다.

 

추가로, 파일 크기가 커지면 주기적으로 직접 검토하고 불필요한 내용을 정리하는 습관을 들이세요. 살아있는 문서로 관리하는 것이 처음 잘 쓰는 것만큼 중요합니다.

 

논문이 증명했듯이, 인간이 직접 작성한 최소화된 컨텍스트 파일은 에이전트 성공률을 약 19% 높입니다. 그 19%는 파일을 비우는 것이 아니라, 올바르게 채우는 데서 옵니다.