결론 먼저
CLAUDE.md를 두되, 자동 생성과 장황함을 버리고 짧고 검증 가능한 규칙을 손으로 점진 축적하라. 쟁점은 쓸지 말지가 아니라 무엇을 어떻게 쓰느냐다. AI가 자동으로 만들어 낸 장황한 규칙 파일은 해롭고, 사람이 직접 고른 짧은 규칙은 도움이 된다 6 8.
이 페이지는 이 위키의 모순①을 실무 의사결정 가이드로 바꾼 것이다. CLAUDE.md에 기록된 "CLAUDE.md를 지워라" vs "CLAUDE.md로 품질 2~3배"의 충돌이다.
두 입장 중 어느 쪽도 버리지 않는다. 둘은 충돌이 아니라 "어떤 CLAUDE.md를, 어떻게 쓰느냐"의 문제로 수렴하기 때문이다.
비교표
| 구분 | "지워라 / 조심하라" (#6 CLAUDE.md를 지워라) | "품질 2~3배" (#8 CLAUDE.md 품질 3배 · #19 65줄 CLAUDE.md) |
|---|---|---|
| 핵심 주장 | 잘못 쓴 컨텍스트 파일은 안 주느니만 못하다 | 잘 쓴 CLAUDE.md는 최고 레버리지 포인트다 |
| 근거 1 | LLM이 자동 생성한 컨텍스트 파일은 작업 성공률을 떨어뜨림 (Agent Bench 평균 약 2%↓, SW-Bench Lite 약 0.5%↓) 6 | Claude가 결과를 스스로 검증하게 해 주면 최종 품질 2~3배 향상 (보리스 체르니 증언) 8 17 |
| 근거 2 | 추론 비용 20%+ 증가 — GPT 5.2는 리즈닝 토큰 +22%, 5.1 mini는 +14% 6 | 안드레이 카파시의 65줄짜리 CLAUDE.md가 깃허브 스타 10만+ 획득 19 |
| 근거 3 | 첫 인터랙션까지 스텝·툴 사용이 늘어 코드를 불필요하게 넓게 탐색, 에너지 낭비 6 | CLAUDE.md는 한 번 잘 써두면 지렛대처럼 효과가 몇 배로 커지는 지점 8 |
| 결정적 단서 | 같은 논문에서 사람이 직접 작성한 컨텍스트 파일은 성공률 평균 약 19%↑ 6 | 권장은 짧고(150~200줄) 구체적·검증 가능한 최소 규칙 8 17 |
화해 명제
두 입장은 같은 곳을 가리킨다.
- 비판 대상은 "CLAUDE.md 그 자체"가 아니다. 자동 생성됐고, 장황하고, 지금 작업과 무관한 컨텍스트를 때리는 것이다. #6 CLAUDE.md를 지워라 영상도 "아예 없애라는 뜻은 전혀 아니고, 잘못 작성했을 때의 악영향에 가까운 논문"이라고 명시한다 6.
- 권장 대상은 "사람이 손으로 쓴 최소·검증 가능한 규칙"이다. 짧고(150~200줄), 도메인 용어가 정의돼 있고, Claude가 스스로 검증할 수 있는 형태다 8 17.
- 그래서 결론이 겹친다. "사람이 작성한 최소·검증 가능한 규칙"은 양쪽 모두에서 효과적이다. 지워라 쪽 논문에서도 사람 작성 시 +19%였다 6 8.
실천 가이드
언제 두는가
- 반복되는 실수가 보일 때 둔다. 빈 파일에서 시작해 Claude가 실수할 때마다 한 줄씩 추가한다(보리스 체르니 팀 방식). 처음부터 완벽하게 채우려 하지 않는다 8.
- 도메인 용어가 헷갈릴 때 둔다. "주문" vs "주문 항목"처럼 비즈니스 용어를 정의해 두면 결과가 크게 달라진다 8.
- 검증 규칙이 필요할 때 둔다. Claude가 구현→빌드→에러 시 자가 수정 루프를 스스로 돌게 하는 규칙이 최고 레버리지다 8.
- 팀 공유가 필요할 때 둔다. git에 커밋해 PR 리뷰로 규칙을 머지하면 팀 전원이 같은 실수를 반복하지 않는다 8.
무엇을 넣고 무엇을 빼는가
| 넣어라 (✅) | 빼라 (❌) |
|---|---|
| 검증 규칙 ("빌드/테스트 통과까지 자가 수정") 8 | LLM이 자동 생성한 장황한 컨텍스트 6 |
| 구체적·검증 가능한 지시 ("함수 30줄 이하", "새 파일 만들기 전 확인") 8 | "깔끔한 코드를 작성하라" 같은 모호한 지시 8 |
| 도메인 용어 정의 8 | 지금 작업과 무관한 API 스펙·DB 스키마 전부 7 |
| 팀 공유 규칙 8 | 300줄 넘는 분량 — 중요한 규칙이 노이즈에 묻힌다 8 |
길이 규칙 — 200줄 룰
- 공식 권장은 200줄 이하다. 대략 150~200단어/줄 안에서 끝내고, 300줄을 넘으면 과감히 삭제하라는 것이다 8 17. CLAUDE.md는 부탁이지 강제가 아니라 실무상 약 80%만 지켜진다. 짧을수록 준수율이 올라간다 17.
- 오토 메모리(
/memory)도 200줄 룰을 따른다. 처음 200줄까지만 로드된다. 넘으면 Claude가 상세 내용을 별도 파일로 분리해 필요할 때만 읽는다. 개인 메모리는 오토 메모리에, 팀 공유 지식은 CLAUDE.md에 둔다 8 7.
대규모 프로젝트면 — 조건부 분할
루트 CLAUDE.md가 비대해지면 Claude가 느려지고 규칙을 안 따르기 시작한다. 한 모노레포 사례에서는 47,000단어까지 갔다. 단순히 쪼개는 게 아니라 "필요한 규칙만 필요한 시점에" 불러오도록 설계한다 10:
@참조 + 레이지 로딩: CLAUDE.md에는 규칙과 참조만, 상세는 별도 파일로 분리 7..claude/rules+ 프론트매터 조건부 로딩 — 주제별 파일 상단에 glob 패턴(예:src/api/**/*.ts)을 지정한다. 해당 파일을 작업할 때만 자동 로드된다. 실제로 trigger.dev와 CockroachDB가 쓴다 10.- 폴더별 CLAUDE.md:
apps/api/CLAUDE.md등으로 두면 해당 폴더 작업 시 그 파일만 읽힌다 10 7.
정 길어지면 — 스킬로 분리
CLAUDE.md에 많은 내용을 쓰기 싫으면 문서와 체크 항목을 스킬로 옮긴다. 스킬은 CLAUDE.md와 달리 실제 필요할 때만 로드된다. 그래서 특정 작업에 필요한 컨텍스트만 주입할 수 있다 6 17. 다만 스킬은 명시적으로 호출해야 Claude가 실제로 쓴다 17.
한 줄 결론
CLAUDE.md를 두되, 자동 생성과 장황함은 버려라. 짧고(200줄 이하) 검증 가능한 규칙을 손으로 점진 축적한다. 더 커지면 .claude/rules 조건부 분할과 스킬 분리로 "필요할 때만 로딩"을 설계한다.