CLAUDE.md 삭제, 측정으로 확인: ablation 표, 체크리스트, 출처

TL;DR

177줄짜리 CLAUDE.md, skill 3개, hook 1개를 가진 실제 리포지토리에서 전부 지웠을 때 깨진 규칙은 딱 하나, 상황도 딱 하나였습니다. 완전히 새로 만든 파일에서의 i18n 규칙입니다. 나머지 컨벤션은 주변 코드가 이미 가르쳐 주고 있어서 그대로 지켜졌습니다.
결과물이 똑같았던 작업에서 이 파일의 비용은 읽은 토큰의 4~14%, 10달러 중 약 1달러였습니다. 눈에 띄는 32% 절감은 파일 때문에 모델이 일을 더 하게 된 단 하나의 작업이 좌우합니다.
skill과 hook은 측정 가능한 비용이 없었습니다. skill은 호출될 때만 로드되는데 호출된 것이 없고, hook이 주입하는 것은 한 문장입니다.
82줄짜리 아키텍처 개요는 아키텍처 질문에서 아무것도 사 주지 못했습니다. 파일이 있든 없든 여섯 번의 답변이 모두 정확했습니다.
Anthropic 자신의 표현에서 "delete"는 지우는 것이 아니라 ablate한 뒤 progressive disclosure로 옮기는 것을 뜻합니다. 코드가 가르칠 수 없는 규칙은 남기고, 나머지는 rules 파일과 skill로 옮기고, 절대 어기면 안 되는 것은 hook으로 만드세요.
설정당 2회 실행은 하한선일 뿐 결론이 아닙니다. 작업별 차이가 15% 미만이면 실행 간 노이즈 범위 안입니다.

What the measurements say

모두가 반응하는 그 강연은 두 가지를 말하는데, 두 번째는 자주 빠집니다. Boris Cherny는 무대에서 Claude Code가 시스템 프롬프트의 80%를 삭제했다고 확인하고, 방법도 설명합니다. 시스템 프롬프트 전체를 지운 다음, 한 줄씩 되살리면서 각 줄의 영향을 측정한다는 것입니다 s2. "every 6 months" 대목은 00:06:58부터 00:07:05 사이에 있고, 표현은 "strongly recommend"가 아니라 "really do recommend"입니다 s1. 그의 말로 널리 알려진 두 문장은 강연에 없습니다. "context, goals and a definition of done"(15:22에서 가장 가까운 실제 표현은 "describe the task, the guardrails, the exit criteria")과 "64 agents"입니다. 그는 "eleven days"라고 말했고, 에이전트 수를 묻자 "I'm not sure"라고 답했습니다 s2. 64라는 숫자는 Bun 재작성 글에서 나온 것입니다. "64 Claudes running for 11 days", API 가격으로 약 165,000달러, 캐시되지 않은 입력 토큰 90억, 출력 토큰 6억 9천만, 캐시된 입력 토큰 읽기 720억입니다 s14.

이 모든 것을 측정 가능하게 만드는 메커니즘은 로딩입니다. CLAUDE.md와 rules 파일은 매 턴 주입되고, skill은 호출될 때만 로드됩니다. memory 문서에는 다들 풀어서 인용하는 크기 가이드도 있습니다. "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence." s4. Anthropic이 글로 쓴 조언은 리포지토리 중앙의 CLAUDE.md를 신화로 규정하고, progressive disclosure와 auto-memory를 제시합니다 s3.

우리 이전의 유일한 통제 연구는 AGENTS.md에 관한 ETH 논문입니다. 12개 리포지토리의 이슈 138건에서 "providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average". 개발자가 커밋한 파일은 LLM이 생성한 파일보다 평균 7% 낫고, 특정 도구를 명시하는 지침은 실제로 도움이 됩니다 s5.

파일에 무엇이 들어 있고 어떻게 읽히는지에 대한 데이터 두 가지입니다. 28,721개 리포지토리, 165,063개 파일에서 중앙값 지침 파일은 50개의 내용 항목을 담고 있고 그중 실제 지시문은 12개입니다. 저자의 표현으로는 파일의 27%만이 여러분이 생각하는 일을 하고 있습니다 s8. 실제로 충돌하는 두 지침을 쓴 통제 실험에서, 규칙 하나를 파일 맨 위에서 맨 아래로 옮기자 모델이 따르는 빈도가 약 90포인트 달라졌고, 거의 안 따르던 것이 거의 항상 따르는 쪽으로 바뀌었습니다 s9. 같은 발행처가 우리 실험이 따르는 선을 긋습니다. ablation은 삭제가 아니며, hook은 강제 수단이라 모델 업그레이드로 만료되지 않습니다 s7.

우리 결과와 맞아떨어진 비공식 사전 정보가 둘 있습니다. 같은 GitHub 이슈와 같은 모델로 1,000줄짜리 CLAUDE.md를 약 20줄로 줄인 버전과 비교했더니, 아키텍처는 유지되고 하우스 룰은 깨졌습니다 s6. 모든 것을 progressive disclosure로 옮긴 한 댓글 작성자는 자동으로 로드되는 컨텍스트가 세션당 약 35k 토큰에서 약 4.5k로 줄었고, 지운 지식은 하나도 없다고 보고합니다 s11. skill ablation을 채점하는 도구도 있습니다. caliper의 --ablate는 skill과 MCP 서버를 다루고, compare는 성공률, 토큰, 실행 시간을 보고합니다. CLAUDE.md 교체는 여전히 수동입니다 s16.

Measurements

프로토콜: 비공개 Expo / React Native 리포지토리 1개(추적 파일 1,021개), CLAUDE.md 177줄, 7,243자, 약 1,800 토큰, skill 3개, 슬래시 커맨드 4개, PreToolUse hook 1개. 모든 실행에서 모델은 claude-opus-5로 고정, Claude Code 2.1.278, 헤드리스 claude -p, --max-turns 40, 사용자 설정 디렉터리는 비움, MCP 없음, 매 실행 전 새 clone으로 초기화. 일상적인 다섯 가지 작업(새 컴포넌트, 컴포넌트 수정, 공용 헬퍼 리팩터, store 필드 영속화, 데이터 경로 설명)에서 한 번에 한 조각씩 ablation했습니다. 44회 실행, API 가격으로 38.97달러, 에이전트 실행 시간 92분. 채점: 추가된 줄에 대한 리포지토리 자체의 하우스 룰, tsc --noEmit, eslint, 답변은 수동 채점입니다.

품질, 무엇이 깨졌나:

설정	수정 실행 수	하우스 룰 위반
A 전체	8	0
B CLAUDE.md 없음	8	1 (새 제목이 하드코딩됨, `.content.ts` 없음)
C skill 없음	4	0
D hook 없음	4	0
E 아무것도 없음	8	2 (제목이 두 번 하드코딩됨, `.content.ts` 없음)

실행당 비용, 설정별 실행의 평균(토큰 = 캐시 읽기, 매 턴 다시 읽는 컨텍스트):

설정	실행 수	$ / 회	턴 / 회	읽은 토큰 / 회
A 전체	10	0.95	25.6	829k
B CLAUDE.md 없음	10	0.74	21.9	568k
C skill 없음	5	0.96	28.2	819k
D hook 없음	5	0.96	27.8	851k
E 아무것도 없음	10	0.85	25.7	655k

작업별, A 대 B(각 2회 실행의 평균):

작업	A $	B $	비용	읽은 토큰
T1 새 컴포넌트	1.72	0.96	-44%	-61%
T2 컴포넌트 수정	1.49	1.26	-15%	-15%
T3 리팩터	0.64	0.63	-1%	-5%
T4 store	0.57	0.53	-6%	-4%
T5 질문	0.34	0.31	-9%	-14%
전체 10회	9.51	7.40	-22%	-32%

표 읽는 법. CLAUDE.md가 없으면 새 컴포넌트 4회 중 3회가 제목을 평범한 문자열로 작성했습니다. 있으면 4회 모두 EN과 FR이 들어간 .content.ts를 만들었습니다. 수정 작업에서는 E를 포함한 모든 설정이 새 문자열을 .content.ts에 넣었습니다. 이웃 파일들이 컨벤션을 보여 주고 있었기 때문입니다. 나머지는 44회 실행 모두에서 지켜졌습니다. 상대 import 0건, types 파일을 고친 여섯 번 모두 interface가 아닌 type, 모든 diff에 디자인 토큰, 16진 색상 0건, barrel 파일 없음. 아무도 따를 수 없었던 지침이 하나 있습니다. 파일은 @design-tokens에서 theme를 import하라고 하지만, 이 별칭은 tsconfig.json에 없습니다. 어떤 설정의 어떤 실행도 이를 쓰지 않았고, 매 세션 1,800 토큰이 헛되이 읽혔습니다. T1의 절감은 더 싼 실행이 일을 덜 했기 때문입니다. 실행 간 분산이 대부분의 설정 효과보다 큽니다. 전체 설정의 T1은 2.11달러, 그다음 1.33달러가 들었습니다. 333 MB 코드 그래프를 둔 대조 실행은 전체 설정의 수치와 같은 범위에 들어왔습니다(T1에서 1.59 대 1.72달러, T5에서 0.38 대 0.34달러). 그래프 블록과 hook은 측정 가능한 변화를 만들지 않았습니다.

Do this Monday

CLAUDE.md를 세어 보세요. 줄 수, 문자 수, 그리고 실제 지시문(Always, Never, Use, Prefer)인 줄 수. 나머지는 모델이 매 턴 다시 읽는 컨텍스트입니다.
섹션마다 컨벤션 하나를 골라 이웃 파일이 이미 그것을 보여 주는지 확인하세요. 폴더의 세 파일이 그 규칙을 따른다면 그 줄은 삭제 후보입니다.
완전히 새로 만든 파일에서 코드가 가르칠 수 없는 규칙을 하나 찾으세요(i18n, 텔레메트리, 라이선스 헤더, 필수 등록 단계 등). 그것을 남기고, 한 줄로 쓰고, 맨 위 가까이에 두세요.
파일이 언급하는 모든 import 경로와 커맨드를 직접 실행해 보세요. 죽은 별칭이나 이름이 바뀐 스크립트는 아무도 따를 수 없는 지침입니다.
긴 아키텍처 개요와 셋업 안내를 필요할 때 로드되는 rules 파일이나 skill로 옮기고, 자동 로드되는 컨텍스트를 전후로 비교하세요.
절대 어기면 안 되는 두세 가지를 hook이나 lint 규칙으로 바꾸세요. 강제는 모델이 문단을 읽는지에 달려 있지 않습니다.
가장 흔한 두 작업을 고정 모델로 파일 있이 두 번, 없이 두 번 실행하고 토큰과 diff를 읽어 보세요. 두 번의 실행은 어디를 봐야 하는지 알려 줄 뿐, 무엇을 결론 내릴지는 알려 주지 않습니다.

Go further

명언이 아니라 방법을 보려면 강연 자체를. 지우고, 한 줄씩 되살립니다 s2.
논문의 전체 결과. 개발자가 커밋한 파일이 생성된 파일보다 7% 낫다는 것과 도구 이름을 명시하면 도움이 된다는 발견을 포함합니다 s5.
변수로서의 규칙 위치. 약 90포인트의 차이와, 모델이 충돌하는 지침을 조용히 해결하는 방식 s9.
30k 리포지토리로 본 지침 파일의 해부. 50개 항목, 12개의 지시문, 나머지 38개는 무엇인가 s8.
좋은 CLAUDE.md 작성법에 대한 HumanLayer 가이드와 그에 반박하는 스레드 s10.
"MUST use agent, ignored 80% of the time" 스레드. 줄글이 통하지 않는 곳에서 hook이 필요한 사례 s12.
"Claude Code now ignores everything" 스레드. 모델 드리프트와 지침 충돌을 가려내는 데 유용합니다 s13.
caliper. 성공률, 토큰, 실행 시간으로 skill과 MCP ablation을 채점하는 용도 s16.

Sources

Boris Cherny: We Cut 80% of Claude Code's Prompt, Y Combinator. 읽는 이유: 1차 인용문, 클립이 잘라낸 단서와 함께.
Transcript of the talk, Y Combinator. 읽는 이유: 무슨 말을 했고 하지 않았는지 확인할 수 있는 검색 가능한 텍스트.
The new rules of context engineering for Claude 5 generation models, Anthropic. 읽는 이유: 조언의 글 버전, 중앙 파일보다 progressive disclosure.
Memory docs: CLAUDE.md and rules files, Claude Code docs. 읽는 이유: 매 턴 로드되는 것, 필요할 때 로드되는 것, 그리고 200줄 가이드.
Evaluating AGENTS.md, arXiv. 읽는 이유: 이번 조사 이전에 컨텍스트 파일을 통제해서 측정한 유일한 연구.
Should you delete your CLAUDE.md every 6 months?, Modern Creator. 읽는 이유: 1,000줄 대 20줄을 비교한 비공식 실험, 깨지는 양상이 우리와 일치합니다.
Opus 5: delete your CLAUDE.md?, reporails. 읽는 이유: ablation과 삭제의 차이, 그리고 hook이 모델 업그레이드 뒤에도 살아남는 이유.
The State of AI Instruction Quality: 30k-repo analysis, reporails. 읽는 이유: 중앙값 지침 파일에 실제로 무엇이 들어 있는지.
Opus 5: the cost of instruction conflicts, reporails. 읽는 이유: 규칙 위치에 대한 통제 실험.
Writing a good CLAUDE.md, HN thread, Hacker News. 읽는 이유: 파일에 무엇이 들어가야 하는지를 두고 실무자들이 벌이는 논쟁.
Anthropic says keep CLAUDE.md under 200 lines, r/ClaudeCode. 읽는 이유: 약 35k에서 약 4.5k로 줄었다는 전후 댓글.
CLAUDE.md says MUST use agent, Claude ignores it, r/ClaudeCode. 읽는 이유: 줄글 지침이 실패하는 구체적인 사례.
Claude Code now ignores everything, r/ClaudeCode. 읽는 이유: "뭔가 바뀌었다"는 느낌 뒤에 있는 증상 보고들.
Rewriting Bun in Rust, Simon Willison. 읽는 이유: 64 에이전트와 165,000달러라는 수치의 출처.
caliper, GitHub. 읽는 이유: skill과 MCP ablation을 위한 채점 하네스.

FAQ

CLAUDE.md를 삭제해야 하나요?

무턱대고는 아닙니다. 우리 리포지토리에서 잃은 것은 새 파일에서의 규칙 하나뿐이었고, 코드가 이미 보여 주던 것은 파일 없이도 그대로 지켜졌습니다. 섹션을 하나씩 ablate하고, 결과물을 바꾸는 것만 남기세요.

파일의 비용이 4~14%뿐인데 왜 토큰이 32% 절감됐나요?

합계가 새 컴포넌트 작업에 좌우되기 때문입니다. 그 작업에서는 파일 때문에 모델이 두 언어로 된 두 번째 파일을 작성했습니다. 더 싼 실행은 일을 덜 한 것입니다. 결과물이 같았던 작업에서의 절감은 4~14%였습니다.

skill과 hook은 매 턴 토큰을 쓰나요?

skill은 호출될 때만 로드되므로 호출되지 않은 skill은 비용이 없고, hook이 주입하는 것은 한 문장입니다. 둘 다 지워도 우리 실행의 어떤 수치도 바뀌지 않았습니다. 매 턴 다시 읽히는 것은 rules 파일과 CLAUDE.md입니다.

설정당 2회 실행이면 충분한가요?

아닙니다. 두 번의 실행은 효과가 어디 있는지 가리킬 뿐, 크기를 재지는 못합니다. 우리 전체 설정은 같은 작업에서 2.11달러, 그다음 1.33달러가 들었으므로, 작업별 차이가 15% 미만이면 노이즈 범위 안입니다.