정의

term/claude-md 의 모든 내용을 단일 거대 문서에 담지 않고 모듈별로 분할 한 뒤, AI 가 필요할 때 알아서 찾아서 시스템 프롬프트 컨텍스트에 주입 하게 하는 패턴. Progressive Disclosure (점진적 공개) 라고도 부름. entity/jaesang-ha 강의의 핵심 운영 권장.

핵심 메시지

"CLAUDE.md 의 모든 내용을 다 하나에 담으려고, 단일 문서에 담으려고 하지 말고 — 모듈별로 일단 CLAUDE.md 를 다 구별을 해 놓으면 CLAUDE.md 하나에 담기는 내용이 확연히 줄어듭니다."

구조

프로젝트 루트/
  CLAUDE.md              ← 100~200 줄, 인덱스만
  app/
    CLAUDE.md            ← app 모듈 What/How/Never/Dep/Tacit
  api/
    CLAUDE.md            ← api 모듈
  data/
    CLAUDE.md            ← data 모듈
  design.md              ← 디자인 결정 별도 문서
  antipatterns.md        ← Non-obvious Pattern 별도 문서

효과:

• 루트 CLAUDE.md: 짧고 인덱스 중심 (매 세션 자동 로드)
• 모듈 CLAUDE.md: 해당 모듈 작업 시에만 자동 로드
• 총 컨텍스트 사용량 ↓ + 각 모듈 컨텍스트 깊이 ↑

case/ha-jaesang-meta-pipeline-claude-md 의 적용

• 4,100 파일 코드베이스 → 59 개 모듈별 CLAUDE.md
• 각 25~35 줄 / 총 ≈ 1,000 토큰 (1M 의 0.1%)
• AI 내비게이션: 5% → 100%

강의 활용

03 HRN concept/ai-ready-codebase 운영 패턴:

• 멘트: "답은 큰 위키가 아닙니다 — 작은 CLAUDE.md 여러 개."
• 강의 슬라이드 폴더 트리 다이어그램.

주의사항

• 번역 통일: Lazy Loading 영어 권장. 지연 로딩 한국어 부수.
• 모듈 단위 결정의 비용: 모듈 정의 자체가 팀 토론 비용. 작은 코드베이스에는 과한 패턴.
• 루트 CLAUDE.md 의 길이 한계: 100~200 줄 — 매 세션 자동 로드되므로 길어지면 모든 세션의 비용.
• 순환 참조 주의: 모듈 CLAUDE.md 가 서로 참조하면 컨텍스트가 폭증할 수 있음. 수동 인덱스 권장.