요약

메타 (Meta) 의 데이터 파이프라인은 4 개의 저장소·3 개의 언어·4,100 개의 파일 로 이루어진 대규모 프로덕션 코드베이스다. entity/jaesang-ha 와 그의 팀 동료 1~2 명은 이 거대한 코드베이스에 AI 에이전트를 도입하면서 모듈별로 작은 CLAUDE.md 를 59 개 기록하는 방식을 시도했다. 도입 전 메타의 엔지니어링 블로그는 그 상태를 "AI had no map (AI 가 지도 없이 헤매고 있었다)" 라고 표현했는데, 4,100 파일 안에서 AI 가 어디로 갈지 몰라 성능이 5 % 수준에 그쳤다는 의미다. 모듈별 CLAUDE.md 59 개를 박은 후 결과는 — AI 내비게이션 (코드베이스 안에서 길을 찾는 능력) 이 5 % 에서 100 % 로 상승 했고, 동시에 도구 호출 횟수가 40 % 감소 했다. 즉 AI 가 길을 알게 되니 시행착오가 줄어든 것 이다.

상세

규모 / 문제

구체적 실패 사례 2 종

(1) 같은 값인데 이름이 다른 경우

• 한 리포: price 필드 → 또 다른 리포: 똑같은 값을 amount 라는 이름으로 받음
• 인간 엔지니어는 암묵적으로 알고 있지만 AI 는 코드만 보면 매핑 잘못
• 컴파일 통과 + 테스트 통과 → 프로덕션 배포 → 가격 0 으로 나가거나 단위 잘못 → 서비스 장애

(2) 한 리포에서 deprecated, 다른 리포가 의존

• 마이크로서비스 5 개 (결제 / 주문 / 사용자 / 알림 / 분석)
• 결제 리포: // Legacy 주석이 붙은 API 키
• AI: "deprecated 구나" → PR → 머지 → 알림 서비스 CI 깨짐 → 서비스 장애

해결 — 거대 위키 ❌, 모듈별 작은 CLAUDE.md

모듈별 CLAUDE.md 5 질문 (concept/ai-ready-codebase 본문):

1. What — 이 모듈이 무엇을 하는가
2. How — 일반적 수정 방법
3. Never (Non-obvious Pattern) ★ 절대 하면 안 되는 것
4. Dependency — 다른 모듈과의 의존성
5. Tacit Knowledge — 안묵적 지식

규모와 비용

드라마틱한 결과

강의 활용

03 HRN lesson/hrn-experience-as-validator / lesson/hrn-sdd-evidence 결정적 사례:

• 시퀀스 (3분):
  1. "메타 엔지니어링 블로그가 직접 AI had no map 이라고 적었습니다."
  2. 4,100 파일 + 5% → 100% 전환 슬라이드
  3. 59 개 작은 CLAUDE.md (1M 의 0.1%) 가 한 일
  4. "답은 백과사전이 아니라 나침반 입니다."
• 본 강의의 case/altenbach-7-agents (비개발자 1 = 시니어 7) 와 묶어 경험 + 하네스 = 곱셈 사례.

주의사항

• 메타 블로그 1차 출처 확인: 강의 슬라이드에 Meta Engineering Blog 2026-05 명시.
• Non-obvious Pattern 의 결정성: 5 질문 중 3 번 이 가장 강한 효과. 다른 4 개를 빼더라도 3 번은 절대.
• 전사 일반화 금지: 메타 데이터 파이프라인 한 사례. 다른 도메인 / 다른 회사에서 동일 효과 보장 불가. 대표적 패턴 으로 표기.
• 모듈 정의의 어려움: 모듈 단위 결정 자체가 비용. 작은 코드베이스에서는 루트 CLAUDE.md 하나면 충분.