Molayo

© 2026 Molayo

Dev.to헤드라인2026. 06. 29. 16:13

CLAUDE.md는 디스크가 아니라 RAM입니다

요약

Claude Code 사용 시 CLAUDE.md 파일을 효율적으로 관리하는 전략을 제안합니다. CLAUDE.md를 상주하는 RAM처럼 작게 유지하고, 상세 문서는 docs/ 폴더에 저장하여 컨텍스트 혼잡과 토큰 비용을 방지해야 합니다.

핵심 포인트

  • CLAUDE.md는 매 세션 컨텍스트에 로드되므로 최소한의 핵심 정보만 유지해야 함
  • 매번 필요한 정보(스택, 명령어, 규칙)만 CLAUDE.md에 포함
  • 상세 아키텍처나 도메인 설명은 docs/ 폴더에 저장하고 포인터로 연결
  • 불필요한 컨텍스트 로드를 줄여 Claude의 성능 저하와 토큰 비용 발생 방지

제가 보는 대부분의 Claude Code 프로젝트들은 300줄이 될 때까지 계속 커지는 하나의 거대한 CLAUDE.md 파일을 가지고 있으며, 200줄 근처에 도달하면 어시스턴트의 성능이 좋아지기는커녕 오히려 나빠지기 시작합니다. 이것은 운이 나쁜 것이 아닙니다. 해당 파일은 세션 시작 시 컨텍스트 (Context)에 로드되어 계속 상주하기 때문에, 당신이 추가하는 모든 줄은 Claude가 이후의 모든 턴마다 앞에 달고 가야 하는 줄이 됩니다. 즉, 실제 작업에 도달하기 전에 읽어야 하는 컨텍스트가 되는 것입니다. 해결책은 파일을 더 길게 만드는 것이 아닙니다. CLAUDE.md를 RAM처럼 취급하고 나머지 문서들을 디스크처럼 취급하는 것입니다.

전체 아이디어를 한 문장으로 요약하면 다음과 같습니다: CLAUDE.md는 지속적으로 로드되고 지속적으로 비용이 발생하는 작업 기억 (Working memory)이므로 작게 유지해야 하며, docs/ 폴더는 무언가가 그것을 가리킬 때만 로드되는 장기 기억 (Long-term memory)입니다. 일단 이 구분이 명확해지면, 특정 정보가 어디에 위치해야 하는지에 대한 다른 모든 결정은 스스로 해결됩니다.

거대한 파일이 해로운 이유

Claude Code는 매 세션 시작 시 CLAUDE.md를 자동으로 읽고 세션 내내 컨텍스트에 유지합니다. 이는 Claude가 모든 작업에서 필요로 하는 몇 가지 사항들, 즉 기술 스택 (Stack), 명령어 (Commands), 항상 지켜져야 하는 규칙들에 대해서는 정확히 당신이 원하는 방식입니다. 하지만 Claude가 일주일에 한 번만 필요로 하는 것들에 대해서는 정확히 당신이 원하지 않는 방식입니다. 긴 도메인 설명이나 전체 아키텍처 기술서가 CLAUDE.md에 들어있다고 해서 Claude가 더 똑똑해지는 것은 아닙니다. 그것은 눈앞의 작업과 무관한 세부 사항들로 컨텍스트를 혼잡하게 만들며, 당신이 사용하든 안 하든 매 턴마다 토큰 (Tokens) 비용을 발생시킵니다.

제가 사용하는 테스트 방법은 간단합니다. Claude가 이것을 매번 필요로 하는가, 아니면 가끔만 필요로 하는가? 매번 필요한 것은 CLAUDE.md에 넣습니다. 가끔 필요한 것은 docs/에 넣고, Claude가 실제로 필요할 때 어디를 찾아봐야 할지 알 수 있도록 CLAUDE.md에 한 줄짜리 포인터 (Pointer)를 남깁니다.

RAM에 속해야 하는 것

CLAUDE.md는 1분 이내에 읽을 수 있을 정도로 충분히 짧아야 합니다. 저의 Laravel 프로젝트용 파일에는 다섯 가지가 들어있습니다:

  • 프로젝트가 무엇인지에 대한 두세 문장 정도의 개요.
  • 버전을 고정한 스택 정보. "Laravel"만으로는 부족합니다. "Laravel 11, PHP 8.3, Pest 3"라고 명시해야 합니다.
  • 정확한 명령어: 테스트(test), 린트(lint), 정적 분석(static analysis), 개발 서버(dev server). Claude가 이를 추측하게 해서는 안 됩니다.
  • 모든 변경 사항에 반드시 준수해야 하는 컨벤션(conventions). 저의 경우, Pest를 우선으로 하는 TDD, KISS, 적절한 곳에서의 Spatie를 통한 이벤트 소싱(event sourcing), 프레임워크 코드로부터 분리된 도메인 로직(domain logic), 그리고 CI에서 .env를 검증하는 envaudit가 이에 해당합니다.
  • 외부 참조(Pointers out). 각각 한 줄씩 작성합니다: 아키텍처는 docs/DESIGN.md에, 현재 작업은 docs/PLAN.md에, 결정 사항은 docs/DECISIONS.md에 있습니다.

마지막 그룹이 핵심입니다. CLAUDE.md는 아키텍처를 포함하지 않습니다. 아키텍처의 주소를 포함합니다. Claude는 작업에 필요할 때만 필요에 따라 세부 사항을 로드하며, 그 외의 시간에는 해당 세부 사항이 컨텍스트(context)를 소모하지 않습니다.

디스크에 저장되어야 할 것들

docs/ 폴더는 긴 자료들이 머무는 곳이며, 필요할 때 로드되기 때문에 필요한 만큼 길어져도 상관없습니다. 대부분의 프로젝트는 세 개의 파일로 충분합니다:

DESIGN.md는 아키텍처와 도메인 모델(domain model)을 다룹니다. 경계 컨텍스트(Bounded contexts), 애그리거트(aggregates), 각 애그리거트가 기록하는 이벤트(events), 그리고 이들이 보호하는 불변성(invariants) 등이 포함됩니다. 이는 여러분의 생각을 한 번 기록해 두는 것으로, Claude가 매 세션마다 이를 재발명하지 않게 하며, Claude가 "이 로직은 어디에 속해야 하나요?"라고 물었을 때 파일로부터 답을 도출할 수 있게 합니다.

PLAN.md는 단계별로 구성된, 계획 우선 방식의 작업 분할입니다. 완료 및 검증이 가능한 작은 단계들로 나누고, 완료될 때마다 체크하며, 하단에 짧은 완료 로그(done log)를 남겨 세션 사이에도 진행 상황이 유지되도록 합니다.

DECISIONS.md는 가벼운 결정 로그(decision log)입니다. 중요한 선택마다 한 번씩 짧게 기록합니다: 맥락(context), 결정(decision), 트레이드오프(trade-off). 이 파일은 여러분과 Claude가 세션이 세 번 지난 후에도 똑같은 질문을 다시 논쟁하는 상황을 방지해 줍니다.

실질적인 필요성이 나타날 때만 추가하세요. 테스트 전략이 진정으로 명확하지 않을 때는 TESTING.md를, 용어 사전(glossary)이 DESIGN.md보다 커지면 별도의 DOMAIN.md를 만드세요. 그 전에는 하지 마세요. 빈 뼈대(scaffolding)는 Claude가 읽어야 할 정보량만 늘릴 뿐입니다.

대부분의 설정이 놓치는 트릭: 중첩된 파일 (nested files)

Claude Code는 루트(root)에 있는 CLAUDE.md만 읽는 것이 아닙니다. 현재 작업 중인 디렉토리에 있는 CLAUDE.md도 읽으며, 이는 루트 파일 위에 레이어(layer) 형태로 겹쳐집니다. 즉, 특정 폴더 내부에서만 유효한 규칙들을 루트 파일을 비대하게 만드는 대신 해당 폴더 안에 둘 수 있다는 의미입니다.

실제 도메인 레이어(domain layer)가 있는 Laravel 프로젝트의 경우, 저는 app/Domains 내부에 다음과 같은 내용을 담은 CLAUDE.md를 두었습니다: 이곳에서는 프레임워크 임포트(import) 금지, 애그리거트(aggregates)는 Spatie의 AggregateRoot를 확장하며 오직 이벤트만 기록할 것, 이벤트는 불변(immutable)이며 과거 시제를 사용할 것, 그리고 모든 변경 사항은 Pest 테스트로 시작할 것. 이 중 그 어떤 것도 루트 파일에 있을 필요가 없습니다. Claude가 컨트롤러(controller)나 Blade 뷰(view)를 편집할 때는 관련이 없기 때문입니다. 이 규칙들은 Claude가 도메인 레이어로 진입할 때 정확히 로드되며, 그 전에는 로드되지 않습니다.

스타터 (The starter)

저는 이 모든 것을 프로젝트에 바로 복사해서 사용할 수 있는 작은 템플릿 리포지토리(template repo)로 만들었습니다: claude-code-laravel-starter. 위에서 설명한 구조를 따르되, 모든 파일은 의미 없는 텍스트(lorem ipsum) 대신 채워 넣을 수 있는 템플릿 형태로 되어 있으며, Laravel 및 이벤트 소싱(event sourcing) 컨벤션(convention)이 이미 내장되어 있고, 패턴을 구체화할 수 있도록 중첩된 도메인 레이어 CLAUDE.md가 포함되어 있습니다.

claude-code-laravel-starter/
├── CLAUDE.md              # 가벼운 앵커(anchor), 매 세션마다 자동 로드됨
├── README.md
...

새로운 Laravel 앱에 이를 복사한 뒤, 실제 스택(stack)과 명령어를 채워 넣고, 예시 도메인을 여러분의 것으로 교체한 다음, 루트 파일은 간결하게 유지하세요.

기억해야 할 세 가지 규칙

Claude가 매번 필요로 하는 것이라면 CLAUDE.md에 넣으세요. 가끔만 필요하다면 docs/에 넣으세요. 세 개의 파일로 시작하고, 실질적인 요구 사항이 생길 때만 더 추가하세요. 그리고 특정 폴더에 자체적인 규칙이 생긴다면, 루트 파일을 늘리지 말고 해당 폴더에 별도의 CLAUDE.md를 부여하세요.

작게 시작하고, 작업 메모리 (working memory)를 타이트하게 유지하며, 나머지는 디스크에 저장하도록 하세요.

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0