Claude가 느려지더라

Claude Code 응답이 점점 느려지고, 가끔 내가 하는 작업이랑 전혀 상관없는 얘기를 하더라고요. 프로젝트의 엉뚱한 부분을 참조하기도 하고요.

프로젝트 문서 파일들 확인해봤습니다:

  • CLAUDE.md: 500줄 이상
  • CLAUDE_StoryPack.md: 450줄 이상
  • 100_Days_Plan.md: 400줄 이상

Claude Code 대화 시작할 때마다 이게 전부 컨텍스트로 로딩되고 있었어요. 실제 대화 시작도 전에 약 7,500 토큰의 문서부터 먹고 들어가는 거였습니다.

컨텍스트가 너무 많았다

문제는 제가 CLAUDE.md에 모든 걸 쑤셔넣으면서 “문서 많을수록 Claude가 프로젝트 더 잘 이해하겠지”라고 생각했던 거예요.

정반대 결과가 나왔습니다. 관련 없는 정보가 너무 많으니까 Claude 응답이 오히려 산만해졌어요.

한국어 번역할 때 스토리팩 생성기 아키텍처 세부사항이 필요 없습니다. CSS 버그 고칠 때 100일 프로젝트 계획 전문이 필요 없고요.

현재 작업이랑 무관한 컨텍스트에 토큰 다 날리고 있었던 겁니다.

문서 재구성

문서를 작고 집중된 파일들로 쪼갰어요:

CLAUDE.md (항상 로드) - 요약본만:

  • What If Classics가 뭔지
  • 현재 프로젝트 상태
  • 다른 문서 파일 링크
  • 빠른 명령어 참조

특화 파일들 (필요할 때만):

  • CLAUDE_Architecture.md - Astro, 빌드, 배포 기술 상세
  • CLAUDE_i18n.md - 한국어 번역 워크플로우
  • CLAUDE_ContentFactory.md - 스토리팩 생성기 상세
  • CLAUDE_StoryPack.md - 아카이브 (기본 로드 안 함)

그리고 .claudeignore 파일 만들었습니다(.gitignore랑 비슷한데 Claude Code용):

# 항상 제외
100_Days_of_Building_in_Public.md
CLAUDE_StoryPack.md

# 필요할 때만 로드
CLAUDE_Architecture.md
CLAUDE_i18n.md
CLAUDE_ContentFactory.md

이제 Claude는 기본으로 400 토큰만 로드해요(요약본). 번역 작업할 땐 ignore 파일에서 CLAUDE_i18n.md 주석 풀면 총 1,200 토큰 로드.

일반 코딩 세션에서 95% 토큰 절약입니다.

응답 품질이 확 올라갔다

재구성 후 Claude 응답이 눈에 띄게 좋아졌어요:

  • 응답 속도 빨라짐
  • 실제 작업에 더 집중
  • 엉뚱한 프로젝트 부분 참조 안 함
  • 토큰 한계 안 걸리고 대화 더 길게 가능

핵심은 문서를 코드처럼 다루는 거였어요. 전부 로드하지 말고 필요한 것만 로드.

Claude Code 쓰는 분들께

Claude Code로 프로젝트 만들고 있는데 CLAUDE.md 파일이 계속 커지고 있다면 쪼개보세요:

  1. CLAUDE.md 짧게 유지 (200줄 이하)
  2. 상세 문서는 별도 파일로
  3. .claudeignore로 로딩 제어
  4. 특화 문서는 해당 기능 작업할 때만 로드

저는 7,500 토큰에서 400 토큰으로 줄였어요. 상황마다 다르겠지만 50%만 줄여도 엄청난 차이입니다.

다음 편에서 계속…