단원 14 — CLAUDE.md = AI 시대의 압축형 설계 문서
별칭: CLAUDE.md 설계 언어 단원 · 4원칙 OOP 재번역 · 65줄 단원
요약
학생이 흔히 term/claude-md 를 단순한 설정 파일 정도로 오해하는데, 본 단원은 그 오해를 정면으로 깬다. CLAUDE.md 는 사실상 AI 에이전트의 UML Class Diagram 에 해당하는 압축형 설계 문서 로, 역할 (Role) + 제약 (Constraints) + 목표 (Goal) + 컨텍스트 (Context) 네 요소를 한 파일에 박아 두는 형태다. 다시 말해 객체지향 설계의 Usecase + Class + Sequence Diagram 세 가지를 하나의 마크다운으로 통합한 형태 다. 이 모델의 정점 사례가 바로 case/karpathy-claudemd-65lines — Karpathy 가 GitHub 에 공개한 65 줄짜리 CLAUDE.md 가 10 만 스타를 받은 사건이다. 본 단원의 결론은 — Karpathy 의 CLAUDE.md 4 원칙이 단순한 글쓰기 가이드가 아니라 OOP 핵심 원칙의 AI 시대 재번역 이라는 점이다.
상세
CLAUDE.md 가 정의하는 4 요소
| 요소 | 의미 | UML 상응 |
|---|---|---|
| Role | AI 가 누구 인가 ("시니어 페어 프로그래머") | Class (역할) |
| Constraints | AI 가 하지 말아야 할 것 (추측·오버엔지니어링·무단 수정 금지) | 제약 조건 |
| Goal | 성공 기준 ("테스트를 통과시켜라") | Usecase (목적) |
| Context | 시스템 아키텍처·기술 스택·팀 컨벤션 | Class Diagram (구조) |
→ Usecase + Class + Sequence 가 한 파일에 압축.
term/karpathy-4-principles = OOP 의 AI 시대 재번역
| 카파시 4원칙 | 설계 관점 해석 | UML 상응 |
|---|---|---|
| Think Before Coding | 요구사항 명확화 없이 착수 금지 | Usecase 확정 전 Class 작성 금지 |
| Simplicity First | 최소 책임 원칙 (SRP) | 클래스 단일 책임 |
| Surgical Interventions | 변경 격리 (OCP/ISP) | 인터페이스 분리 원칙 |
| Goal-Driven Execution | 수용 기준(AC) 기반 TDD | 선조건·후조건 명세 |
"카파시는 새로운 설계 원칙 을 만든 것이 아니다. OOP 의 핵심 원칙을 AI 에이전트 시대에 재번역 한 것이다."
case/karpathy-claudemd-65lines — 65줄짜리 CLAUDE.md 가 GitHub 10만 스타
→ 짧은 설계 문서 의 압도적 영향력 — Boris 의 2,500 토큰 원칙 (lesson/hrn-verification-loop) 과 일치.
★ "왜 65 줄이고 왜 100 줄은 독인가" — 정량 근거
학생 질문 응대 — "길게 쓰면 좋은 거 아닌가요?" 답변은 세 수치 에 박힌다:
| 항목 | 수치 | 이유 |
|---|---|---|
| 권장 토큰 | ≤ 2,500 (lesson/hrn-verification-loop Boris) | Claude 1M context 의 0.25% — 매 세션 캐시 prefix 의 일부 |
| 모듈 단위 길이 | 25~35 줄 / 모듈 | 컨텍스트 윈도우 1 회 전체 로드 가능 (vs. 100 줄 = 부분 로드 → 망각) |
| 루트 길이 | ≤ 200 줄 | 맵 으로 쓰고 매뉴얼 은 모듈로 분산 (lazy loading) |
황금 비율: CLAUDE.md 의 75% 는 하지 마라 (Don't / 금지·안티패턴), 25% 만 해라 (Do) — AI 가 실패할 때마다 한 줄 추가 가 가장 레버리지 높은 항목 (term/non-obvious-pattern 카드 참조).
왜 길면 독인가:
- 세션 중 CLAUDE.md 수정 → 캐시 prefix 무효화 → 토큰 전액 재청구 (캐시 hit 의 ~20 배)
- 지나치게 긴 CLAUDE.md → AI 가 매 작업마다 읽는 시간 > 실행 시간
- 분석 마비 (Analysis Paralysis) — 학생이 강의 후 300 줄 CLAUDE.md 를 작성하면, 그 자체가 새로운 부채
"CLAUDE.md 가 너무 길면 자기 자신이 된다 — 코드 읽기 전에 CLAUDE.md 부터 읽어야 하는 상황. 그러면 무엇을 위한 설계인가?"
→ 본 강조점이 "설계 = 무거운 문서가 아니라 결정의 압축 " 의 정량적 뒷받침.
다른 도구의 등가물: term/agents-md (GitHub Copilot) / term/cursorrules (Cursor). 모두 term/persistent-instructions 의 도구별 구현.
방법론
강의 진행 시퀀스 (8분 30초):
- ★ 표어 회귀 멘트 (15초): "앞 단원에서 설계 없이는 코딩 없다 를 봤습니다. 이 단원이 그 설계의 형태 입니다."
- CLAUDE.md = UML Class Diagram (1분): 충격 명제로 시작.
- 4 요소 분해 (2분): Role/Constraints/Goal/Context.
- 65줄 사례 (1분): GitHub 10만 스타.
- ★ 정량 근거 — 왜 65 줄이고 왜 100 줄은 독인가 (90초): 세 수치 (2,500 토큰 / 25~35 줄 / ≤200 줄) + 75:25 비율 + 분석 마비 경고.
- 카파시 4원칙 ↔ OOP 5 핵심 (2분): 재번역 메시지.
- 3 도구 영구 지시어 비교 (45초): CLAUDE.md / AGENTS.md / .cursorrules.
주의사항
- 충격 명제의 무게: CLAUDE.md = Class Diagram 은 과감한 비유. 청중에게 비유적 등가 임을 부연.
- 65줄의 의미: 짧음 이 핵심. 청중이 길게 적자 로 오해하지 않게.
- OOP 재번역의 한계: 완벽한 1:1 은 아니다. 주요 원칙 의 매핑 정도로 표기.
- 다음 섹션 연결: "이제 직접 보여드립니다" → 05 DEM 으로 자연 전환.