CLAUDE.md를 삭제하라 — AI 코딩 에이전트에게 정보를 덜 줘야 더 잘 작동하는 이유
2026년 2월, 개발자 유튜버 Theo(t3.gg)와 Matt Pocock이 거의 같은 날 같은 주제로 영상을 올렸습니다. Theo는 "CLAUDE.md를 삭제하라"고 했고, Matt Pocock은 "절대 /init을 실행하지 마라"고 했습니다. 이름은 달라도 메시지는 하나였습니다 — AI 코딩 에이전트에게 프로젝트 정보를 정리해서 건네주는 컨텍스트 파일, 그것이 오히려 에이전트의 성능을 깎아먹고 있다는 것입니다. 이 주장은 감이 아니라 2026년 초에 나온 두 편의 학술 연구에 기반하고 있습니다.
이 글은 두 영상의 핵심 논지를 하나로 엮되, 근거가 된 연구 원문을 직접 확인하여 팩트체크한 내용을 정리합니다.
CLAUDE.md와 AGENTS.md — 그게 뭔데?
Claude Code나 Codex 같은 AI 코딩 에이전트를 프로젝트에 붙여서 쓸 때, 프로젝트 루트에 CLAUDE.md나 AGENTS.md라는 마크다운 파일을 두는 관행이 생겼습니다. 에이전트에게 프로젝트의 디렉토리 구조, 기술 스택, 코딩 규칙, 빌드 및 테스트 방법 등을 미리 알려주는 일종의 "에이전트용 README"입니다. Claude Code에서 /init을 실행하면 에이전트가 코드베이스를 훑어보고 이 파일을 자동으로 만들어 줍니다.
이 파일을 잘 다듬는 것이 에이전트 활용의 핵심이라는 인식이 널리 퍼져 있었습니다. 실제로 2026년 1월 기준 6만 개 이상의 공개 GitHub 저장소가 이런 컨텍스트 파일을 포함하고 있다고 보고되었습니다. 하지만 2026년 초 발표된 연구들은 이 상식에 정면으로 반기를 듭니다.
두 편의 연구 — 실제로 도움이 되는가?
Theo와 Matt Pocock이 공통적으로 인용한 첫 번째 연구는 ETH Zurich에서 2026년 2월에 공개한 논문입니다(Gloaguen et al., arXiv:2602.11988). 연구진은 AGENTbench라는 자체 벤치마크를 구축하여, 12개의 오픈소스 저장소에서 138개의 실제 GitHub 이슈 해결 작업을 수행했습니다. 4개의 코딩 에이전트(Claude Code with Sonnet 4.5, Codex with GPT-5.2, Codex with GPT-5.1 mini, Qwen Code with Qwen3-30b)를 세 가지 조건 — 컨텍스트 파일 없음, LLM 자동 생성 파일, 개발자 직접 작성 파일 — 으로 비교했습니다.
결과는 예상 밖이었습니다. LLM이 자동 생성한 컨텍스트 파일이 있을 때, 에이전트의 작업 성공률이 평균 약 3% 하락했고, 추론 비용은 20% 넘게 올라갔습니다. 개발자가 직접 작성한 파일은 성공률을 평균 약 4%p 끌어올렸지만, 비용 역시 20% 이상 증가하는 것은 마찬가지였습니다.
두 번째 연구는 Lulla et al.이 2026년 1월에 공개한 논문입니다(arXiv:2601.20404, ICSE JAWs 2026 발표). 이 연구는 10개의 저장소에서 124개의 실제 GitHub PR을 대상으로, OpenAI Codex(GPT-5.2)를 AGENTS.md 파일이 있을 때와 없을 때로 나누어 페어 실험을 진행했습니다. 결과는 반대 방향이었습니다 — AGENTS.md가 있을 때 작업 완료까지 걸리는 시간의 중앙값이 28.64% 줄어들었고, 출력 토큰 소비량의 중앙값도 16.58% 감소했습니다. 다만 이 연구에서 사용된 AGENTS.md는 해당 저장소의 개발자가 직접 작성하여 유지해 온 파일이었고, 코드의 정확성이 아닌 효율성만 측정했다는 점을 연구진 스스로 명시하고 있습니다.
두 연구는 모순되는 것처럼 보이지만, 실은 같은 방향을 가리킵니다. 파일의 존재 자체가 아니라 그 안에 무엇이 담겨 있느냐가 결과를 가릅니다. 잘 관리된 사람의 지식이 담긴 파일은 효율을 높이지만, 자동 생성된 뻔한 정보는 오히려 방해가 됩니다.
자동 생성 파일이 왜 해로운가
첫째, 에이전트가 이미 알아낼 수 있는 정보를 반복한다. /init으로 만들어지는 파일의 대부분은 디렉토리 구조, 사용 중인 프레임워크, 모듈 간 관계 같은 내용입니다. 하지만 코딩 에이전트는 작업을 시작하면 디렉토리를 탐색하고, 기존 README를 읽고, 설정 파일을 확인합니다. 자동 생성 파일은 에이전트가 어차피 스스로 발견할 수 있는 정보를 다시 한 번 컨텍스트에 올려놓는 셈이고, 에이전트는 이 두 가지 출처를 조율하느라 추론 토큰을 더 쓰게 됩니다. ETH Zurich 연구의 행동 분석에서도, 컨텍스트 파일이 있을 때 에이전트가 더 많은 파일을 탐색하고 더 많은 테스트를 실행하면서 추론 토큰 소모가 크게 늘어나는 현상이 관찰되었습니다.
둘째, 에이전트의 주의를 잘못된 곳으로 끌 수 있다. CLAUDE.md에 "이 프로젝트는 백엔드에 tRPC를 사용합니다"라고 적혀 있다고 가정해 봅시다. 실제로는 레거시 엔드포인트 몇 개에만 tRPC가 남아 있고 새 코드는 다른 기술을 쓰고 있더라도, 에이전트는 매 대화에서 tRPC를 컨텍스트로 가져갑니다. LLM의 특성상, 컨텍스트에 한번 올라온 정보는 현재 작업과 무관하더라도 출력에 영향을 미칩니다. 이것이 앵커링 효과입니다.
셋째, 한 장짜리 지시서로 모든 종류의 작업을 커버할 수 없다. "커밋 전 테스트 스위트 전체를 돌려라"는 코드 변경에는 맞지만, 문서 수정 작업에서는 시간 낭비입니다. CSS 리팩토링을 하는 에이전트에게 데이터베이스 마이그레이션 경고가 같이 올라옵니다. 정적인 하나의 파일이 동적인 모든 작업 유형에 동일하게 적용되기 때문에 생기는 구조적 한계입니다. Matt Pocock은 이 문제를 세 마디로 압축했습니다 — 토큰을 낭비하고, 며칠이면 구식이 되고, 시스템 프롬프트만 부풀린다고요.
에이전트는 지시를 무시한 게 아니라, 너무 성실하게 따랐다
ETH Zurich 연구에서 특히 눈에 띄는 발견이 있습니다. 에이전트들은 컨텍스트 파일의 지시를 실제로 충실하게 따랐습니다. 파일이 있을 때 더 많은 테스트를 돌리고, 더 많은 파일을 뒤지고, 저장소 전용 도구를 더 자주 사용했습니다. 문제는 에이전트가 말을 안 듣는 것이 아니었습니다. 당장 필요하지 않은 지시까지 빠짐없이 수행하면서 작업이 불필요하게 복잡해진 것이 문제였습니다.
반면, 컨텍스트 파일이 실제로 도움이 된 경우도 분명히 있었습니다. ETH Zurich 연구의 행동 분석에 따르면, 개발자가 직접 작성한 컨텍스트 파일에 uv라는 패키지 매니저를 사용하라는 지시가 있을 때 에이전트는 작업당 평균 1.6회 uv를 호출했습니다. 그 지시가 없을 때는 0.01회 미만이었습니다. uv를 쓸지 pip을 쓸지는 코드만 읽어서는 확신하기 어려운 정보입니다. 이것이 바로 컨텍스트 파일에 적어야 하는 종류의 내용입니다.
에이전트는 주어진 지시를 성실하게 수행합니다. 문제는 모든 지시가 모든 작업에 도움이 되는 것은 아니라는 점입니다. 에이전트에게 줄 지시는 "최대한 많이"가 아니라 "정말 필요한 것만"이어야 합니다.
그러면 뭘 남기고 뭘 지워야 하나
Theo, Matt Pocock, 그리고 이 주제에 대해 글을 쓴 Addy Osmani까지 세 사람이 수렴하는 원칙이 있습니다. 에이전트가 코드를 직접 읽어서 스스로 파악할 수 있는 정보는 빼고, 코드만 봐서는 알 수 없는 정보만 남기라는 것입니다.
남겨야 할 것은 코드만으로 추론하기 어려운 운영 지식입니다. 예를 들면 이런 것들입니다 — 패키지 매니저로 pip 대신 uv를 쓸 것, 테스트를 돌릴 때 반드시 --no-cache 플래그를 붙일 것(그렇지 않으면 픽스처 문제로 거짓 양성이 나옴), auth 모듈은 커스텀 미들웨어 패턴이니 표준 패턴으로 리팩토링하지 말 것, legacy 디렉토리는 deprecated이지만 프로덕션 모듈 세 개가 참조 중이니 삭제하지 말 것.
지워야 할 것은 에이전트가 스스로 발견 가능한 모든 것입니다. "이 프로젝트는 모노레포 구조이며 패키지는 /packages에 있다"는 디렉토리 목록 한 번이면 알 수 있습니다. "TypeScript와 React를 사용한다"는 package.json을 읽으면 됩니다. "깨끗하고 유지보수 가능한 코드를 작성하라" 같은 모호한 원칙은 에이전트에게 실행 가능한 지시가 아니라 잡음입니다.
분량에 대한 실무적 감각도 공유되고 있습니다. Reddit의 Claude Code 커뮤니티에서 여러 개발자가 독립적으로 보고한 바에 따르면, CLAUDE.md가 200~300줄을 넘기면 성능 저하가 감지되기 시작하고, 500줄 부근에서 급격하게 떨어지는 경향이 있다고 합니다. 한 개발자는 그 지점을 넘으면 에이전트가 "프로젝트를 이해한 상태"에서 "지시 목록에 파묻힌 상태"로 전환된다고 표현하기도 했습니다.
파일을 고칠 게 아니라, 코드를 고쳐라
두 영상에서 공유되는 더 근본적인 생각이 있습니다. CLAUDE.md에 줄을 추가하는 것은 증상에 반창고를 붙이는 것이지, 원인을 고치는 것이 아니라는 관점입니다.
에이전트가 새 유틸리티를 계속 엉뚱한 폴더에 넣는다면, "유틸리티는 /utils에 넣어라"라고 CLAUDE.md에 적기보다 디렉토리 구조 자체가 혼란스러운 건 아닌지 돌아봐야 합니다. 에이전트가 deprecated된 라이브러리를 계속 불러온다면, import 경로가 잘못된 선택을 유도하는 구조는 아닌지 확인해야 합니다. 에이전트가 타입 체크를 빠뜨린다면, 빌드 파이프라인에서 자동으로 잡히게 만드는 것이 텍스트 한 줄로 당부하는 것보다 확실합니다.
Matt Pocock은 자신의 AGENTS.md를 극도로 짧게 유지하는 것으로 알려져 있고, 대신 코드베이스 자체를 에이전트가 탐색하기 쉬운 구조로 만드는 데 집중합니다. 폴더 이름과 파일 이름이 명확하고, 코드 구조가 직관적이면 에이전트는 별도 안내 없이도 잘 찾아갑니다. 사실 이건 AI 에이전트만을 위한 조언이 아닙니다. 새로 합류한 팀원이 README 없이도 코드를 이해할 수 있는 프로젝트라면, AI 에이전트도 마찬가지입니다.
아직 열려 있는 질문들
두 영상이 답하지 않았거나 열어둔 문제들도 있습니다.
하나는 정적 파일의 한계를 넘는 구조에 대한 것입니다. 루트에 하나의 큰 파일을 두는 대신, 디렉토리별로 분산된 계층 구조의 컨텍스트 파일을 두고 작업 유형에 따라 필요한 부분만 로딩하자는 아이디어가 여러 개발자로부터 독립적으로 제안되고 있습니다. ICLR 2026에서 발표된 ACE(Agentic Context Engineering) 프레임워크는 컨텍스트를 정적 파일이 아닌 동적 플레이북으로 다루어, 정적 접근 대비 벤치마크 성능을 12.3% 높인 바 있습니다. 하지만 현재 주요 코딩 에이전트 도구들은 이런 동적 구조를 쉽게 구현할 수 있는 인터페이스를 아직 제공하지 않고 있습니다.
또 하나는 사람이 생각하는 "에이전트에게 필요한 정보"와 에이전트가 실제로 필요로 하는 정보 사이의 간극입니다. Arize AI의 프롬프트 최적화 실험에서, 수동 작성 대신 자동 최적화 루프로 CLAUDE.md 지시를 개선했을 때 교차 저장소 테스트에서 약 5%, 동일 저장소 테스트에서 약 11%의 정확도 향상을 얻었습니다. 이 결과는 사람의 직관이 에이전트의 실제 필요를 정확히 반영하지 못할 수 있음을 시사합니다.
마지막으로 모델 자체의 진화라는 변수가 있습니다. 몇 달 간격으로 개발자들은 이전에 컨텍스트 파일에 적어둔 내용 중 더 많은 부분이 불필요해졌다고 보고합니다. 모델의 코드베이스 탐색 능력이 계속 향상되고 있기 때문입니다. 오늘 작성한 CLAUDE.md가 다음 분기에는 순수한 오버헤드가 될 수도 있습니다.
결론 — 에이전트를 신입 사원처럼 온보딩하지 말자
두 영상의 메시지를 하나로 압축하면 이렇습니다. /init으로 자동 생성한 CLAUDE.md는 삭제하고, 에이전트가 코드를 읽어서 스스로 알아낼 수 없는 최소한의 정보만 직접 작성하라.
에이전트를 새 팀원처럼 온보딩하고 싶은 마음은 자연스럽습니다. 사무실 투어를 시켜주고, 조직도를 보여주고, 아키텍처를 설명해주고 싶은 본능이죠. 하지만 코딩 에이전트는 신입 사원이 아닙니다. 여러분이 프롬프트를 타이핑하는 동안 코드베이스 전체를 탐색할 수 있는 존재입니다. 이들에게 지도를 그려줄 필요는 없습니다. 지뢰가 어디 묻혀 있는지, 그것만 알려주면 됩니다.
그리고 모델이 계속 발전하고 있는 지금, 어쩌면 그것마저도 점점 필요 없어지고 있는지 모릅니다.
- Theo (t3.gg) — Delete your CLAUDE.md (and your AGENT.md too), YouTube, 2026-02-23
- Matt Pocock — Never Run claude /init, YouTube, 2026-02-24
- Gloaguen et al. (ETH Zurich) — Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?, arXiv:2602.11988, 2026-02-12
- Lulla et al. — On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents, arXiv:2601.20404, ICSE JAWs 2026
- Addy Osmani — Stop Using /init for AGENTS.md, 블로그, 2026-02-24
- THE DECODER — Context files for coding agents often don't help — and may even hurt performance, 2026-02-17
- Arize AI — CLAUDE.md Best Practices Learned from Optimizing Claude Code with Prompt Learning
- ACE Framework — Agentic Context Engineering, ICLR 2026
- Reddit r/ClaudeAI — New research: AGENTS.md files reduce coding agent success rates 커뮤니티 토론
이 글은 2026년 2월 24일 기준으로 작성되었습니다. 본문의 연구 수치는 각 논문의 원문(arXiv)에서 직접 확인한 것이며, 커뮤니티 의견은 해당 출처를 명시했습니다. 특정 도구나 기업과의 이해관계는 없습니다.
댓글
댓글 쓰기