요약

entity/jaesang-ha 가 정리한 — AI 가 코드베이스 안에서 길을 잃지 않도록 어디가 어떤 모듈이고, 어디서부터 봐야 되고, 어디는 건드리면 안 되는지를 미리 표시해 둔 코드 베이스. 작은 토이 프로젝트 에서는 차이 없지만 회사 코드베이스(수천 파일·수백 모듈·5~10 년 누적 컨벤션) 에서 폭발적 격차. 신입 엔지니어 비유 — 신입에게는 온보딩 문서·위키·시니어 코칭을 주면서 AI 한테는 안 줌.

상세

왜 회사 코드베이스에서 폭발적 차이가 나는가

AI 가 모를 수밖에 없는 암묵적 정보

• 산정치 (예: 이 함수는 절대 프로덕션에서 호출 금지)
• 3 년 전 PR 코멘트
• 시니어가 신입에게 옆에서 가르치는 무언어 규칙

"신입한테는 온보딩 문서를 줍니다. 위키도 알려주고 시니어 엔지니어가 옆에 앉아서 가르치기도 해요. 근데 AI 한테는 그걸 안 하잖아요. 그냥 코드 던지고 잘 짜라 고 하고 결과물이 평범하다고 실망."

핵심 비유 — 백과사전이 아니라 나침반

"AI 한테 모든 걸 다 알려주려고 하면 안 되고 — 방향만 어디로 가야 할지 방향만 알려 줘야."

모듈별 term/claude-md — 5 질문

→ term/non-obvious-pattern 이 가장 결정적. AI 가 잘못 갈 수 있는 길을 아예 차단.

모듈별 CLAUDE.md 의 규모 권장

• 각 파일: 25~35 줄
• 토큰 예산: 1M 컨텍스트의 0.1~1%
• 루트 CLAUDE.md: 100~200 줄 이하 + 인덱스 형식

효과 (메타 데이터 파이프라인 사례 — case/ha-jaesang-meta-pipeline-claude-md)

• 4,100 파일 코드베이스에 59 개 작은 CLAUDE.md
• AI 가 볼 수 있는 코드베이스: 5% → 100%
• 도구 호출 횟수: −40%
• 작업 시간: 단축 / 품질: 향상

3 가지 운영 원칙

1. AI 가 실패할 때마다 term/non-obvious-pattern 한 줄 추가 — 표지판 세우기
2. 루트 CLAUDE.md = 짧은 지도(인덱스) — 이 정보는 X 문서 참조 형식
3. 자동 갱신 루프 — 썩어 가는 컨텍스트는 없는 것보다 나쁘다. 훅으로 강제 자동화

concept/claudemd-as-design-language 와의 관계

• Claudemd as Design Language = CLAUDE.md = Class Diagram 의 의미론적 등가
• AI Ready Codebase = 그 설계 언어가 대규모 코드베이스에 모듈별로 분산 배치된 운영 모델

방법론

강의 활용 — 단원 11 lesson/hrn-experience-as-validator 와 12 lesson/hrn-sdd-evidence 의 실리콘 밸리 현업 측면 보강:

1. 사이드 vs 회사 비유 (1분): 토이 OK → 회사 ❌
2. 신입 비유 (2분): 신입에게 주는 온보딩 = AI 에게 줘야 할 것
3. 메타 4,100 파일 사례 (3분): case/ha-jaesang-meta-pipeline-claude-md 의 5% → 100%
4. 5 질문 + Non-obvious 강조 (2분): 모듈별 CLAUDE.md 5 질문
5. 3 원칙 (2분): 실패 시 한 줄, 루트는 인덱스, 자동 갱신
6. AI Ready 100점 루브릭 (1분): 7 영역, A 그레이드 90~100 = Agentic Ready

주의사항

• 사이드 ↔ 회사 격차의 함정: 학생 청중에게 지금은 작은 코드베이스 임을 인정. 졸업 후 회사 코드베이스에서 진가.
• 모듈 분할 vs 단일 거대 위키: 거대 위키는 컨텍스트 윈도우 터트림. 무조건 모듈별 분할.
• Tacit Knowledge 채굴 비용: 안묵지 추출 자체가 시니어 시간 소모. 한 번에 다 하지 말고 AI 실패 시마다 한 줄씩 누적 권장.
• 자동 갱신 = Active 가 아닌 Passive: 사람이 손으로 유지하면 반드시 썩는다. 훅 + 크론으로 강제.
• 상위 카드: 본 카드는 concept/claudemd-as-design-language 의 대규모 코드베이스 운영 측면. 두 카드 함께 인용.