CLAUDE.md를 지워야 할까? 레포지토리 컨텍스트 파일의 실제 효과
📺 원본 영상: CLAUDE.md 지워 🎙️ 채널: 코드팩토리 📅 정리 일자: 2026-02-25 ⚠️ Note: 본 리포트는 영상의 음성을 텍스트로 변환(STT)하여 정리한 것입니다. 화면에 표시된 자료(차트, 코드, 슬라이드 등)는 포함되지 않을 수 있습니다.
개요
“CLAUDE.md를 쓰면 AI가 더 멍청해지고, 비용도 더 많이 든다.” 이 충격적인 결론은 최근 해외 개발자 커뮤니티에서 뜨거운 논쟁을 불러일으키고 있는 논문 한 편에서 나왔다. 하지만 강연자는 이 결과를 액면 그대로 받아들이기보다는, 왜 이런 결과가 나왔는지를 면밀히 분석하면서 실무에서 컨텍스트 파일을 어떻게 관리해야 하는지에 대한 실질적인 가이드를 제시한다. 잘못된 해석이 “CLAUDE.md를 아예 삭제해도 된다”는 오해로 번지고 있는 상황에서, 이 영상은 논문이 실제로 말하는 바를 정확히 짚어준다.
AI 컨텍스트 구조의 이해
현대 AI 에이전트가 작업을 수행할 때 참조하는 컨텍스트는 크게 두 가지 계층으로 나뉜다. 먼저 시스템 프롬프트(System Prompt) 계층이 있는데, 이는 Anthropic이나 OpenAI 같은 AI 개발사가 자사 모델을 특정 방향으로 유도하기 위해 직접 삽입한 프롬프트다. 사용자는 이 영역에 접근하거나 수정할 수 없다. API를 직접 사용하는 경우라면 커스텀 시스템 프롬프트를 추가할 수 있지만, 일반 구독 형태로 사용하는 경우에는 해당이 없다.
사용자가 직접 컨트롤할 수 있는 영역은 두 번째 계층인 메모리 파일과 사용자 프롬프트다. CLAUDE.md, agents.md 같은 컨텍스트 파일이 바로 여기에 속한다. 강연자는 이 두 요소의 우선순위에 관한 흥미로운 분석을 제시하는데, 인간의 기억 방식과 AI의 컨텍스트 처리 방식에 대한 연구에 따르면 컨텍스트의 가장 앞부분과 가장 뒷부분이 처리 우선순위가 가장 높다고 한다. 메모리 파일은 사용자 프롬프트보다 먼저 주입되므로, 자연스럽게 더 높은 우선순위를 갖게 된다. 바로 그렇기 때문에 메모리 파일의 내용이 AI의 행동 방향에 강하게 영향을 미칠 수 있고, 동시에 내용이 잘못되면 그 악영향도 크다.
논문 소개: “Are Repository-Level Context Files Helpful for Coding Agents?”
이 영상에서 다루는 논문의 제목은 “Are Repository-Level Context Files Helpful for Coding Agents?”, 즉 레포지토리 수준의 컨텍스트 파일이 코딩 에이전트에게 실제로 도움이 되는가를 엄밀히 검증한 연구다. 논문의 핵심 문제 의식은 간결하다. agents.md와 같은 컨텍스트 파일을 수동 또는 자동으로 생성해 코딩 에이전트를 각 레포지토리에 맞게 조정하는 방식이 에이전트 개발자들 사이에서 적극적으로 권장되고 있지만, 이것이 실제 작업에서 효과가 있는지를 검증한 엄밀한 연구가 존재하지 않았다는 것이다.
연구팀은 이 공백을 메우기 위해 GitHub의 실제 PR(Pull Request)들을 수집해 AgentBench라는 새로운 벤치마크를 직접 구축했다. AI 에이전트가 PR을 해결했다고 선언하는 첫 시점에 실제로 해결됐는지를 즉시 검증하는 방식으로 성공률을 측정했다. 기존에 광범위하게 신뢰받아온 SWE-bench Lite도 함께 사용했기 때문에, 결과의 신뢰도는 상당히 높다고 볼 수 있다. 강연자도 “비슷하게 나온다”며 두 벤치마크의 결과가 일관성을 보였음을 확인해준다.
실험 설계: 세 가지 조건
연구팀은 여러 코딩 에이전트와 LLM을 대상으로, 세 가지 조건에서 테스트를 진행했다. 첫 번째는 컨텍스트 파일이 전혀 없는 경우(No Context), 두 번째는 LLM이 자동으로 생성한 컨텍스트 파일을 제공한 경우, 세 번째는 실제 개발자가 직접 작성하여 레포지토리에 커밋한 컨텍스트 파일을 제공한 경우다. 이 세 가지 조건의 비교 결과가 개발자 커뮤니티를 충격에 빠뜨렸다.
실험 결과: 충격적인 수치들
LLM 자동 생성 컨텍스트 파일의 역설
가장 놀라운 발견은 LLM이 자동 생성한 컨텍스트 파일이 오히려 성능을 끌어내렸다는 점이다. AgentBench에서 평균 약 2%, SWE-bench Lite에서 약 0.5%의 작업 성공률 감소가 관찰됐다. 다시 말해, /init 명령이나 이에 준하는 방법으로 자동 생성된 CLAUDE.md를 검토 없이 그대로 사용하는 것은 아무것도 제공하지 않는 것보다 오히려 나쁜 결과를 낳는다는 뜻이다.
💡 [영상 참조] 강연자는 이 시점에서 모델별 성공률을 비교한 Figure 3 차트를 보여줍니다. Y축은 작업 성공률, X축은 테스트된 모델이며, 컨텍스트 없음(None)과 LLM 생성(LLM) 조건이 나란히 비교됩니다. 상세 내용은 원본 영상을 확인하세요.
테스트된 모델 중 Qwen 계열의 특정 모델[원본 영상 참조]은 이 경향과 다른 결과를 보였는데, 강연자는 해당 모델의 전반적인 성능 수준 자체가 낮아서 나타나는 현상으로 추론했다.
인간이 작성한 컨텍스트 파일의 효과
반면, 실제 개발자가 직접 작성한 컨텍스트 파일은 유의미한 성능 향상을 이끌어냈다. 평균적으로 약 19%의 성공률 상승이 관찰됐으며, 이 수치를 어떻게 평가할 것인지는 각자의 판단에 달려 있다고 강연자는 말한다. 컨텍스트 파일을 최신 상태로 유지·관리하는 데 투입해야 하는 노력을 감안했을 때 19%의 향상이 충분한 값어치를 하는지, 아니면 그 에너지를 실제 작업 검증에 쓰는 것이 더 나은지를 저울질해볼 필요가 있다는 것이다. 강연자 개인적으로는 이 수치가 충분히 의미 있다고 본다고 밝혔다. 단, Claude Sonnet의 경우 예외적으로 컨텍스트 파일이 없을 때가 더 효율적이었다.
비용: 20% 이상 증가
컨텍스트 파일 사용으로 인한 비용 증가도 무시할 수 없다. OpenAI의 추론 모델 두 가지를 비교한 결과[원본 영상 참조], 한 모델은 컨텍스트 파일 처리를 위해 출력 토큰과 추론 토큰(Reasoning Token)을 22% 더 소비했고, 경량 버전 모델은 14% 더 소비했다. 전반적으로 컨텍스트 파일이 제공된 경우 추론 비용이 20% 이상 증가하는 일관된 경향이 나타났다.
왜 이런 결과가 나오는가? 행동 분석
불필요한 코드 탐색의 증가
강연자는 이 현상의 구체적 원인을 Figure 4와 Figure 6의 데이터를 통해 설명한다. 메모리 파일이 존재할 경우 AI 에이전트가 레포지토리 구조를 더 빨리 파악할 것이라는 기대와 달리, 실제로는 PR과 직접 연관된 파일에 처음 도달하기까지 필요한 스텝(tool use 횟수)이 오히려 늘어났다. 컨텍스트 파일이 주어지면 에이전트가 더 폭넓은 탐색(broader exploration)을 하도록 유도되기 때문이다.
💡 [영상 참조] Figure 6은 tool use 횟수 분포를 히스토그램으로 비교합니다. 0 기준선이 컨텍스트 파일 미제공 상태이며, 짙은 초록색은 인간 작성 컨텍스트, 연한 초록색은 LLM 생성 컨텍스트에 해당합니다. 전반적으로 컨텍스트 파일이 있을수록 오른쪽(더 많은 tool use)으로 분포가 치우칩니다. 상세 내용은 원본 영상을 확인하세요.
결과적으로 컨텍스트 파일이 없을 때 첫 번째 관련 파일까지의 스텝이 가장 적었고, 사람이 작성한 컨텍스트 파일을 제공했을 때도 마찬가지이거나 오히려 더 높았다. 이 결과는 “컨텍스트 파일이 레포지토리의 요약본 역할을 해 AI가 빠르게 핵심에 접근하게 해줄 것”이라는 직관적 기대를 정면으로 반박한다.
현재 작업과 무관한 정보가 만드는 노이즈
강연자가 핵심 원인으로 지목하는 것은 현재 수행 중인 작업과 무관한 컨텍스트 정보의 혼입이다. 레포지토리 자체가 이미 구조 정보를 담고 있는 데다, 현대 코딩 에이전트들은 서브 에이전트를 활용해 코드를 자율적으로 탐색하고 분석하는 능력이 매우 뛰어나다. 이런 상황에서 CLAUDE.md에 폴더 구조, 테스트 코드 작성 방식, 금지 사항 목록, 인증 로직, 사용 중인 프레임워크와 라이브러리 목록 등이 모두 들어가 있으면 어떻게 될까.
S3 버킷 업로드 서비스를 구현하는 작업을 예로 들면, 해당 작업과 직접 관련 없는 온갖 정보들이 AI의 컨텍스트 윈도우를 잠식하면서 목표 달성을 방해하는 노이즈로 작용한다. 강연자는 사람도 “하지 말라고 하면 오히려 더 생각이 난다”는 점을 언급하며, AI도 이와 유사하게 작용할 수 있다고 설명한다. 지시사항을 충실히 따르려는 에이전트의 성질이 불필요한 탐색과 처리를 유발하는 것이다.
실무 전략: 최소화와 컨텍스트 분리
CLAUDE.md를 지워야 한다는 오해
강연자는 이 논문을 잘못 읽고 “이제 CLAUDE.md를 아예 써도 된다”거나 “지워도 된다”고 해석하는 경향이 해외는 물론 국내에서도 퍼지고 있다고 지적한다. 이는 명백한 오독이다. 이 논문이 진짜로 경고하는 것은 문서화(documentation) 파일처럼 꽉꽉 채워 작성된 컨텍스트 파일의 위험성이지, 컨텍스트 파일 자체의 무용론이 아니다. 인간이 정성껏 최소화하여 작성한 컨텍스트 파일은 여전히 평균 19%의 성공률 향상을 가져왔다. 그러므로 올바르게 관리된 CLAUDE.md는 여전히 가치가 있다.
핵심 원칙: 최소 필수 요구사항만 명시
논문의 최종 결론은 명확하다. “사람이 직접 작성하는 컨텍스트 파일은 최소한의 필수 요구사항만을 명시해야 한다.” 강연자는 이것이 자신이 오래전부터 권장해온 방식임을 언급하며, CLAUDE.md의 크기가 일정 수준 이상으로 커지면 반드시 직접 검토해 불필요한 내용을 제거하라고 당부한다. LLM이 자동 생성한 컨텍스트 파일을 검토 없이 사용하는 것도 물론 금물이다.
스킬(Skill) 기반 컨텍스트 분리 전략
강연자가 제안하는 구체적인 해법은 CLAUDE.md와 Skills의 역할을 분리하는 것이다. CLAUDE.md에는 어떤 작업을 하든 항상 필요한 핵심 정보만 최소한으로 담는다. 특정 작업에서만 필요한 상세 지침, 문서, 아키텍처 설명 등은 각 작업에 특화된 별도 스킬 파일로 이전한다. 이렇게 하면 AI가 특정 작업을 수행할 때 해당 스킬만 트리거되어 그 작업에 꼭 필요한 컨텍스트만 주입받는다. 결과적으로 CLAUDE.md는 늘 슬림한 상태를 유지하고, 세부 정보는 필요한 순간에만 등장하는 구조가 만들어진다. 이 방식은 논문에서 “인간이 작성한 최소화된 컨텍스트 파일이 가장 좋은 결과를 낸다”고 한 조건을 최대로 활용하면서, 동시에 불필요한 컨텍스트 오염을 방지한다.
마무리 / 핵심 정리
이 논문이 실질적으로 전달하는 메시지는 “CLAUDE.md를 삭제하라”가 아니라 **“컨텍스트 파일을 프로젝트 문서처럼 쓰지 말라”**는 것이다. 강연자는 “AI가 요즘 예전보다 멍청해진 것 같다”는 불만의 99%는 AI 모델 자체의 문제가 아니라 사용자의 잘못된 컨텍스트 관리에서 비롯될 가능성이 매우 높다고 단언한다. CLAUDE.md를 빼곡한 문서처럼 관리해왔다면, 바로 그것이 체감 성능 저하의 원인이 되고 있을 수 있다.
실천적 결론은 세 가지로 요약된다. 첫째, CLAUDE.md는 매번 반드시 필요한 핵심 정보만으로 슬림하게 유지한다. 둘째, 세부 지침과 문서는 작업별 스킬로 분리해 필요한 순간에만 주입되도록 설계한다. 셋째, LLM 자동 생성 컨텍스트 파일은 반드시 직접 검토하고, 무분별하게 그대로 사용하지 않는다. 이 세 가지 원칙을 지키는 것만으로도 AI 코딩 에이전트의 성능과 비용 효율을 동시에 개선할 수 있다.
📚 출처 및 참고
| 구분 | 내용 |
|---|---|
| 원본 영상 | CLAUDE.md 지워 |
| 채널 | 코드팩토리 |
| 리포트 작성 | 2026-02-25 |
| 작성 방식 | YouTube 영상 STT 변환 후 에디팅 |
💬 본 리포트는 영상 내용을 바탕으로 재구성되었습니다. 정확한 내용은 원본 영상을 참조해 주세요.