CLAUDE.md 써야 하나 말아야 하나

코딩 에이전트(Claude Code, Codex, Cursor 등)를 쓰다 보면, CLAUDE.md나 AGENTS.md를 추가하라는 권고를 한 번쯤 들어봤을 거다.

Anthropic을 비롯한 에이전트 개발사들이 적극 권장하고, 2026년 현재 6만 개 이상의 GitHub repo가 컨텍스트 파일을 포함하고 있다.

근데 진짜 효과가 있을까?

최근 발표된 학술 논문 3편과 Anthropic 공식 가이드, Reddit/커뮤니티 반응을 종합해서 이 질문에 답해보려 한다.

결론부터 말하면 "제대로 쓰자" 다.

참고한 논문과 문서

Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? (ETH Zurich)
On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents (Heidelberg Univ.)
Codified Context: Infrastructure for AI Agents in a Complex Codebase (Aristidis Vasilopoulos)
Claude Code: Best practices for agentic coding (Anthropic)
Best Practices for Claude Code (Anthropic)

각 논문이 말하는 것

1. ETH Zurich — 컨텍스트 파일이 효과가 있는가?

ETH Zurich 연구진이 4개의 에이전트(Claude Code, Codex [GPT-5.2 / GPT-5.1 Mini], Qwen Code)를 SWE-bench LITE와 직접 구축한 AGENTBENCH에서 평가했다.

측정 지표:

테스트 통과 성공률
에이전트가 환경과 상호작용한 횟수 (스텝 수)
LLM 추론 비용

실험 설정 3가지:

NONE — 컨텍스트 파일 없음
LLM — 에이전트 권장 초기화 명령(/init 등)으로 자동 생성한 컨텍스트 파일
HUMAN — 개발자가 직접 작성한 컨텍스트 파일

결과가 꽤 충격적이었다.

컨텍스트 파일이 없는 경우(NONE)가 성공률은 다른 케이스와 엎치락뒤치락하지만, 비용과 스텝 수에서 항상 가장 저렴하고 빨랐다.

개발자가 직접 작성한 경우보다 비용이 최대 42% 증가한 케이스도 있었다.

LLM 자동 생성의 경우 비용은 증가하고 성능은 감소했다.

SWE-bench LITE: 평균 성공률 0.5%↓ / 평균 2.45 스텝 증가 / 20% 비용 증가
AGENTBENCH: 평균 성공률 2%↓ / 평균 3.92 스텝 증가 / 23% 비용 증가

Sonnet 4.5 기준 AGENTBENCH에서 인스턴스당 비용이 $1.15에서 $1.33으로 올랐다.

개발자 작성 컨텍스트의 경우 LLM 생성 파일보다 모든 에이전트에서 우수했다.

Claude Code를 제외하면 NONE 대비 성능이 개선됐지만, 평균 4% 개선에 불과했고 스텝 수는 평균 3.34 증가, 비용은 최대 19% 증가했다.

흥미로운 건 모든 문서(.md / docs/ 등)를 제거한 실험이다.

이 경우 LLM 자동 생성 컨텍스트 파일이 종합 가이드 역할을 해서, NONE 대비 평균 2.7% 성능 향상을 가져왔다.

심지어 개발자 작성 파일보다 우수했다.

정리하면:

문서가 잘 갖춰진 repo → CLAUDE.md 안 쓰는 게 최선
문서가 부실한 repo → /init으로 자동 생성하는 게 최선

2. Heidelberg Univ. — 효율성 관점

Heidelberg Univ.는 Codex(GPT-5.2)로 AGENTS.md의 효과를 측정했다.

10개 repo, 124개 PR을 대상으로 AGENTS.md 유무를 비교한 결과:

실행 시간: 28.64% 감소
토큰 사용: 16.58% 감소
태스크 완료율: 비슷한 수준 유지

두 논문의 결론이 정면으로 충돌하는 것처럼 보이는데, 측정 대상이 다르다.

Heidelberg는 같은 결과를 내는 데 얼마나 빨리, 적은 토큰으로 도달하는가(효율성)를 봤고, ETH Zurich는 태스크를 실제로 해결하는 비율이 올라가는가(효과성)를 봤다.

그리고 Heidelberg는 개발자가 직접 작성한 AGENTS.md를 사용했다.

ETH Zurich에서도 개발자 작성 파일이 소폭 개선됐다는 점과 일치한다.

즉, 개발자가 직접 잘 작성한 파일은 도움이 된다는 건 두 논문 모두 동의하는 부분이다.

3. 독립 연구 — 계층적 컨텍스트 시스템

독립 연구자 Aristidis Vasilopoulos의 논문도 흥미롭다.

학회 심사를 받지 않아 신뢰도는 낮지만, 대규모 프로젝트에서는 단일 CLAUDE.md가 아니라 계층적 시스템이 필요하다고 주장한다.

Tier 1 (항상 필요) — 모든 세션에 무조건 주입
Tier 2 (태스크별) — 필요할 때만 호출
Tier 3 (가끔 필요) — MCP 서버를 통해 검색

프로젝트 지식을 구조화된 문서 인프라로 만들어야 한다는 주장이다.

4. Anthropic 공식 가이드

Anthropic은 2025년 4월에 CLAUDE.md를 적극 권장했는데, 최신 공식 문서에서는 톤이 달라졌다.

CLAUDE.md는 매 세션 로딩되므로, 광범위하게 적용되는 내용만 적을 것
도메인 지식이나 가끔 필요한 워크플로우는 Skills로 분리할 것
간결하게 유지할 것 — 각 줄에 대해 "이걸 지우면 Claude가 실수하나?"를 질문할 것
큰 CLAUDE.md 파일은 Claude가 실제 지시를 무시하게 만듦
CLAUDE.md는 코드처럼 관리할 것

초기에는 /init 자동 생성을 권장했지만, 최신 문서에서는 간결함과 가지치기를 강조하고 있다.

커뮤니티 반응

Google Software Engineer, Addy Osmani

앵커링 효과(Pink Elephant Problem) — AGENTS.md의 모든 줄은 에이전트에게 실제로 시킨 작업과 경쟁 중
/init은 에이전트가 스스로 발견할 수 있는 것(디렉토리 구조, 기술 스택, 모듈 설명)을 한 번 더 정리해서 진실 소스를 하나 더 만드는 불필요한 작업
CLAUDE.md에 뭔가를 적어야 한다면, 코드베이스 자체가 불명확하다는 신호
- 에이전트가 유틸리티를 잘못된 디렉토리에 넣음 → 디렉토리 구조를 재구성
- deprecated 의존성을 자주 사용 → import 구조부터 수정
- 타입체크 누락 → 빌드 파이프라인에서 자동 수정
코딩 에이전트를 신입 사원처럼 온보딩하려 들지 말자 — 이미 에이전트는 모든 코드베이스를 grep 가능하다

Upsun Developer Center

클라우드 배포 플랫폼 Upsun에서 ETH Zurich 논문을 실무에 적용한 가이드를 발표했다.

빈 CLAUDE.md에서 시작
1주일간 에이전트와 작업하면서 반복되는 실수만 기록
2회 이상 반복된 실수만 CLAUDE.md에 추가
경험적 증거에 기반한 컨텍스트 파일 구축

HumanLayer 블로그

샌프란시스코의 스타트업 HumanLayer에서 CLAUDE.md 작성법에 대한 심층 분석을 발표했다.

300줄 미만이 최적 (자기들은 60줄 미만으로 쓴다고 한다)
Claude Code의 시스템 프롬프트 자체가 이미 약 50개의 개별 지시를 포함

CLAUDE.md 제대로 쓰는 법

위 내용을 종합하면 핵심 원칙이 나온다.

원칙 1: 에이전트가 코드를 읽어서 스스로 발견할 수 있는가?

가장 강력하고 간단한 필터다.

Yes면 삭제, No면 유지.

❌ "src/components에 React 컴포넌트가 있습니다" → 에이전트가 ls로 발견 가능
❌ "이 프로젝트는 모노레포 구조를 사용합니다" → 에이전트가 ls로 발견 가능
❌ "TypeScript를 사용합니다" → tsconfig.json으로 확인 가능
✅ "테스트 시 반드시 --no-cache 플래그, 안 쓰면 fixture 때문에 문제 발생" → 코드에 없는 정보
✅ "legacy/는 deprecated지만 프로덕션 모듈 3개가 import 중, 삭제 금지" → 코드에 없는 정보

원칙 2: 앵커링 효과를 기억하자

논문이 증명한 대로, 장황한 파일은 비용만 올리고 성능을 떨어뜨린다.

넣는 모든 정보가 모든 태스크와 경쟁 중이다.

내용을 제외했을 때 Claude가 실수하는 것만 작성한다.

원칙 3: 진단 도구로 취급하자

에이전트가 반복적으로 틀리는 걸 CLAUDE.md에 넣기보단, 근본 원인을 고치자.

원칙 4: 점진적으로 구축하자

빈 파일에서 시작해서, 에이전트가 반복적으로 틀리는 것만 하나씩 추가한다.

문서화가 없는 repo에서는 /init으로 생성하되, 그대로 쓰지 말고 반드시 검토한다.

체크리스트

CLAUDE.md를 작성하거나 리뷰할 때 아래 체크리스트를 활용하면 된다.

넣어야 할 것

빌드/테스트/린트 명령어 (에이전트가 추측하면 안 되는 것)
프로젝트 특화 도구 사용법 (pnpm, uv, pdm 등)
에이전트가 반복적으로 틀리는 코딩 컨벤션
수정 금지 영역 (레거시 코드, 자동 생성 파일 등)
프로젝트만의 특이한 패턴이나 제약사항
커밋/브랜치 네이밍 규칙 (팀 컨벤션)

넣지 말아야 할 것

디렉토리 구조 설명 (에이전트가 탐색 가능)
프레임워크/라이브러리 일반 사용법 (학습 데이터에 있음)
README나 docs/에 이미 있는 내용 (중복 = 성능 저하)
코드베이스 전체 개요 (논문이 효과 없음을 증명)
"깔끔한 코드를 작성하세요" 같은 모호한 지시
한 번만 쓰이는 태스크별 지시 (그건 프롬프트에)

정기 점검

100줄을 넘으면 가지치기 필요 신호
150줄 이상이면 Skills/Subagent로 분리 검토
에이전트가 CLAUDE.md 지시를 무시하면 파일이 너무 긴 것
에이전트가 CLAUDE.md에 답이 있는 걸 물어보면 표현이 모호한 것
월 1회 팀과 함께 리뷰하고 불필요한 항목 제거
대규모 프로젝트(50K줄+)면 계층적 구조 전환 검토

결론

CLAUDE.md 써야 할까?

논문이 명확하게 보여주듯, 잘 작성된 개발자의 컨텍스트 파일은 더 저렴하고 빠르게 만들어 준다.

다만 장황한 컨텍스트 파일은 성공률을 떨어뜨린다.

에이전트에게 필요한 건 온보딩 같은 지도가 아니라, 피해야 하는 지뢰의 위치다.

Anthropic 공식 가이드에서도 "간결하게, 가지치기하라"를 점점 강조하고 있다.

개발 커뮤니티도 마찬가지다.

60~150줄이 적당하다.

CLAUDE.md에 뭔가를 적어야 한다면, 그건 코드베이스 자체가 불명확하다는 신호일 수 있다.

이를 분석해서 코드베이스 단에서 수정하는 아이디어를 얻는 도구로 활용하는 게 핵심이다.

참고 문헌

Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? — ETH Zurich
On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents — Heidelberg Univ.
Codified Context: Infrastructure for AI Agents in a Complex Codebase — Aristidis Vasilopoulos
Claude Code: Best practices for agentic coding — Anthropic
Best Practices for Claude Code — Anthropic
Do You Really Need an AGENTS.md? — Addy Osmani
AGENTS.md: Less Is More — Upsun Developer Center
Writing a Good CLAUDE.md — HumanLayer