CLAUDE.md는 몇 행까지 효과가 있을까? — 사이즈별로 정확도·비용·속도를 실측하다

저희 프로젝트의 CLAUDE.md가 1,200행을 넘어섰습니다. 아키텍처 방침, 커밋 규약, 디렉토리 구성, 테스트 방침, 자주 사용하는 명령어, 최근의 ADR(Architecture Decision Records), 과거의 인시던트, 절대 해서는 안 되는 일 등을 매일같이 추가하다 보니 어느샌가 이 정도 사이즈가 되었습니다.

여기서 궁금한 점은 "결국 CLAUDE.md는 몇 행까지 효과가 있는가"라는 소박한 의문입니다. Claude Code의 공식 문서에는 "간결하게 유지하라"라고만 적혀 있습니다. 500행까지는 효과가 있는지, 1,000행을 넘으면 저하되는지, 누군가가 정량적으로 측정하고 있는 것을 본 적이 없습니다.

그렇다면 직접 측정해보자는 생각으로, 100/300/500/1000/2000행의 5가지 사이즈로 정확도·토큰 소비·응답 시간의 3개 축을 실측해 보았습니다. 결론부터 말씀드리면 "500행을 넘어서는 시점부터 비용 대비 효과가 무너지기 시작한다"는 것이 이번 실험의 체감 결과입니다.

공정한 비교를 위해 다음과 같은 조건을 고정했습니다.

모델: Claude Opus 4.7 (Anthropic Console, Claude Code CLI 경유) -
프로젝트: 자사 TypeScript + Next.js 앱 (약 4만 행) -
태스크: 동일한 20개 태스크 세트 (API 추가 5건, 버그 수정 5건, 리팩토링 5건, 테스트 추가 5건) -
CLAUDE.md: 동일한 문장을 100/300/500/1000/2000행으로 늘리거나 줄여서 준비 -
평가: 태스크 완료율 (수동 리뷰), 입력 토큰, 응답 시간 (첫 출력까지)

CLAUDE.md의 내용은 원래의 1,000행 버전을 기준으로 하였으며, 줄일 때는 상세 내용을 삭제하고, 늘릴 때는 과거 ADR을 전사하여 분량을 늘렸습니다. 의미 있는 정보 밀도는 유지하면서 사이즈만 바꾸는 것이 목표입니다.

태스크의 내역도 조금 더 적어두겠습니다. API 추가는 "기존 패턴에 맞춘 신규 엔드포인트", 버그 수정은 "Issue로 알려진 것 4건 + 인위적으로 심어놓은 것 1건", 리팩토링은 "장황한 switch/case 문 정리", 테스트 추가는 "이미 동작하고 있는 함수에 유닛 테스트 추가"입니다. 모두 난이도를 중간 정도로 맞추었으며, 결과가 "프로젝트 고유의 규약을 따랐는지 여부"에 따라 크게 갈리도록 설계했습니다.

2026년 5월 시점, Claude Code 1M context는 Opus 4.7 / Sonnet 4.6에서 GA(General Availability) 상태입니다. CLAUDE.md가 2000행(약 60K tokens 상당)이라도 컨텍스트(context)에는 여유롭게 들어간다는 전제하에, 이번 계측은 컨텍스트 초과가 아니라 정확도 저하를 목표로 한 것입니다.

실측한 3개 축의 수치를 먼저 나열합니다.

CLAUDE.md 행수	입력 토큰 (평균/태스크)	응답 시간 (초/태스크)	태스크 완료율
100행	약 3.1K	6.2	65% (13/20)
300행	약 8.4K	7.5	85% (17/20)
500행	약 13.5K	8.4	90% (18/20)
1000행	약 26.0K	11.2	90% (18/20)
2000행	약 51.0K	16.8	80% (16/20)

몇 가지 경향이 보입니다.

100행은 부족하여, 고유 규약을 알지 못하고 일반적인 코드를 작성해 버리는 패턴이 눈에 띔 -
300~500행에서 완료율이 상승하며, 500행에서 최대치(90%)가 됨 -
1000행은 500행과 동일한 완료율이지만, 토큰은 약 2배, 응답 시간은 1.3배 -
2000행은 완료율이 오히려 떨어지고, 응답 시간은 2배 이상

300→500→1000 구간에서는 토큰 소비와 응답 시간이 정직하게 선형적으로 증가하지만, 완료율은 500행에서 정체됩니다. 게다가 2000행에서는 완료율이 오히려 떨어지는 결과가 나왔습니다.

100행 버전에서 실패한 태스크의 전형적인 사례를 하나 들자면, 신규 API 추가 시 고유의 응답 타입(ApiResponse<T> 제네릭)을 사용하지 않고 일반 object를 반환해 버리는 케이스였습니다. 1,000행 버전의 CLAUDE.md에는 "

API의 응답 타입은 반드시"라고 명시되어 있지만, 100행 버전으로 줄이는 과정에서 이 규약이 빠지게 되었고, Claude는 일반적인 TypeScript 방식으로 반환해 버린 것이 구도입니다. 적혀 있으면 지키고, 적혀 있지 않으면 자연스럽게 추측한다, 단지 그뿐인 것처럼 보입니다.

ApiResponse<T>

ApiResponse<T>로 감싸는 것이죠. "컨텍스트 윈도우 (context window)가 1M나 되니까, 넣기만 하면 효과가 있지 않을까?"라고 직관적으로 생각하기 쉽습니다. 저도 그렇게 생각했습니다.

실제로 2000행 버전에서 실패한 태스크의 내용을 관찰해 보니, 원인은 대체로 다음 두 가지였습니다.

첫째, CLAUDE.md가 길어질수록 과거에 추가한 내용들끼리 서로 모순되기 시작합니다. 제가 작성한 2000행 버전의 경우, 어떤 장에서는 "테스트는 Vitest를 사용한다"라고 적어놓고, 다른 장에서는 "pytest로 작성한다"라고 적어둔 부분이 있었습니다 (프로젝트 일부에 Python 서비스가 있어 혼재되어 있었습니다).

Claude는 이런 모순을 발견하면, 양쪽을 모두 만족시키기 위해 절충안을 제시할 때가 있습니다. "Vitest와 Pytest 둘 다 실행할 수 있도록 테스트 러너 (test runner)를 추상화한다"라는 것은 요구사항 수준에서는 존재하지 않는 설계였습니다. 스스로 쌓아온 CLAUDE.md 내부의 모순이 정작 자신의 눈에는 의외로 보이지 않는다는 것을 뼈저리게 느낀 순간입니다.

둘째, Anthropic 공식이 "lost in the middle"이라고 부르는 현상입니다. 긴 문서에서는 도입부와 결말부는 강하게 읽히지만, 중앙 섹션은 놓치기 쉽습니다. 2000행 규모의 CLAUDE.md에서는 800~1500행 부근의 규약이 무시될 확률이 체감상 20% 정도 높아졌습니다.

이는 장문 문서 (document)를 위한 프롬프팅 (prompting)에서 나타나는 고전적인 현상이며, Anthropic 스스로도 Opus 4.7 release notes에서 "Claude prefers concise context. Verbose context can degrade adherence. (Claude는 간결한 컨텍스트를 선호합니다. 장황한 컨텍스트는 준수 능력을 저하시킬 수 있습니다.)"라고 명시하고 있습니다.

2000행 버전에서 실제로 놓쳤던 사례로, 파일의 1100행 부근에 적혀 있던 "Server Actions를 사용할 때는 'use server'를 파일 최상단이 아니라 함수 내부에 작성한다"라는 규약이 있습니다. 이는 500행/1000행 버전에서는 제대로 지켜졌으나, 2000행 버전에서는 완전히 누락되어 파일 최상단에

'use server'

가 섞여 있는 답변이 돌아왔습니다. 같은 정보라도 CLAUDE.md의 어느 위치에 적혀 있는가가 결과에 영향을 미친다는 점은 꽤 무서운 현상입니다.

완료율뿐만 아니라, 태스크 1건당 비용 측면에서 보면 500행의 우위는 더욱 두드러집니다. Opus 4.7의 입력 단가를 $15/1M tokens로 가정하고, CLAUDE.md로 인해 발생하는 입력 비용만을 계산했습니다.

행수	1태스크당 입력 비용	완료율	완료 1건당 비용
100행	약 $0.047	65%	$0.072
...

완료 1건당 비용으로 보면 500행이 가장 효율적이며, 2000행은 500행의 약 4배에 달하는 비용이 듭니다. 저희 팀의 Claude Code 사용량으로 계산하면, CLAUDE.md를 2000행에서 500행으로 줄이는 것만으로도 월 수만 엔의 차이가 발생합니다.

여기서 한 가지 보정이 필요합니다. Claude Code에는 compaction(자동 요약) 기능이 있어, 대화가 길어지면 과거 메시지를 압축합니다. 하지만 CLAUDE.md는 매번 프롬프트의 선두에 로드되며, compaction 대상에서 제외됩니다. 이는 공식 help center에 명시된 동작입니다.

즉, "CLAUDE.md를 컴팩트하게 유지하는 것"은 compaction에 맡길 수 없는 영역이라는 뜻입니다. 토큰 압축을 기대하며 CLAUDE.md를 부풀려 놓아도, 매번 전체 사이즈로 읽히게 됩니다. 비용은 계속 불어날 뿐입니다.

세션 내에서 /compact를 수동으로 실행하더라도 CLAUDE.md의 내용은 요약되지 않습니다. 이는 "매 세션 반드시 읽게 하고 싶은 규칙"을 보장하기 위한 설계이므로 장점이기도 합니다. 대신 "CLAUDE.md에 적지 않는 것이 좋은 정보"를 가려내는 능력이 필요해집니다.

500행을 상한선으로 정했을 때, 무엇을 남기고 무엇을 버릴지가 최대의 쟁점이 됩니다. 현재 진행 중인 프로젝트에서는 다음과 같은 방침으로 정리했습니다.

아키텍처의 대방침 (모노레포 구성, 레이어 책임 분리)

명명 및 커밋 규약 (짧고 요점만)

절대로 해서는 안 되는 일 (운영 DB 직접 연결, 시크릿 유출 등)

빈출 명령어 (pnpm test:watch, pnpm db:migrate 등)

긴 ADR (docs/adr/

에 분리, CLAUDE.md에서는 링크만 제공) -
과거 인시던트 상세(docs/postmortem/에 집약) -
API 상세 사양(OpenAPI 파일에서 참조) -
테스트 개별 패턴(tests/README.md로 이동)

CLAUDE.md는 "Claude에게 매번 읽히기" 위한 파일이므로, 매번 필요한 정보로만 압축합니다. 가끔만 사용하는 정보는 Claude가 필요할 때 Read tool로 가져올 수 있는 곳에 두면 됩니다.

CLAUDE.md는 내버려 두면 자연스럽게 비대해집니다. 제가 운영하며 효과를 보고 있는 방법은 두 가지입니다.

저희 팀에서는 월초에 15분 동안 CLAUDE.md를 검토하는 시간을 확보하고 있습니다. 실제로 하는 일은 딱 세 가지뿐입니다.

• 지난 1개월 동안 추가된 행을 다시 읽기
• "더 이상 참조하지 않음", "다른 파일로 옮겨도 됨"이라고 판단한 것을 삭제/이동
• wc -l로 500행을 초과하면, 줄일 때까지 commit 하지 않기

각 장(Chapter)에 행 수 상한을 정해두면 안일한 추가를 억제할 수 있습니다.

## 아키텍처 (max 80행)
## 명명·커밋 규약 (max 60행)
## 개발 플로우 (max 100행)
...

상한을 넘을 것 같은 장이 있다면, 추가하기 전에 먼저 삭제합니다. 이것만으로도 지속적으로 슬림한 CLAUDE.md를 유지할 수 있습니다.

세 번째는 "AI에게 재고 조사를 도와달라고 하는" 방식입니다. claude -p "이 CLAUDE.md 중에서, 지난 3개월간의 git log에 한 번도 등장하지 않은 용어를 포함하는 행을 추출해줘"와 같은 원샷 프롬프트(one-shot prompt)를 통해, AI 스스로가 "실제로 프로젝트에서 사용되지 않는 규칙"을 찾아내도록 합니다. 저희 팀에서 시도해 보니 200행 분량의 후보가 나왔고, 확인 결과 절반은 정말로 삭제해도 문제가 없는 것들이었습니다. CLAUDE.md를 읽는 AI에게 CLAUDE.md를 슬림화하게 만드는 것은 조금 흥미로운 구도이기도 합니다.

5가지 사이즈 실측을 통해 발견한 세 가지 규칙입니다.

• CLAUDE.md는 500행까지가 효율 최대 (완료율 90%, 비용 최소)
• 1000행을 넘으면 가성비가 악화되며, 2000행에서 정확도가 오히려 저하됨
• 압축(compaction) 대상이 아니므로, 사이즈 자제가 필수적임

"일단 전부 써두면 좋다"는 컨텍스트 엔지니어링(Context Engineering) 관점에서는 오류였습니다. Claude에게 무엇을 전달하고 무엇을 별도 파일로 대피시킬 것인가에 대한 설계가, 결국 토큰 경제성(Token Economics)과 태스크 완료율 모두에 영향을 미칩니다. 저의 CLAUDE.md는 현재 490행으로 운영하고 있습니다. 10행 정도는 의식적으로 비워두는 것이 딱 적당한 여백이라고 생각합니다.

당신의 CLAUDE.md는 몇 행인가요? 500행을 넘고 있다면, 줄인 후의 체감 차이를 꼭 댓글로 알려주세요.