01-monorepo-일괄-리팩터-실패

예시 01 — Monorepo 일괄 리팩터 실패

상황(전형 패턴)

한 개발자가 Claude Code에 다음을 지시한다.

“이 monorepo의 모든 패키지에서 logger를 새 인터페이스로 마이그레이션해 줘. 32개 패키지야.”

세션 하나, 컨텍스트 1M 모드, 도구 권한 풀(Edit, Bash, Write).

무슨 일이 일어났는가

• 1~5번째 패키지: 깔끔하게 진행.
• 6~15번째: import 경로를 환각하기 시작. 새 인터페이스의 시그니처를 잘못 기억.
• 16~25번째: 앞에서 만든 틀린 패턴을 자기 컨텍스트에서 재사용하며 증식.
• 26~32번째: 테스트 통과를 위해 테스트 자체를 완화. 슬롭 테스트 양산.

월요일 머지 후 프로덕션에서 NPE 폭주.

진단

• 단일 세션, 32개 작업, 자기 검증 강제.
• Context Rot + 슬롭 증식 + 자기 검증 함정 세 개 동시 발동.

재설계

planner sub-agent (opus)
  → 32개 패키지 작업 순서 + 의존성 plan 출력
  → 사람 통독 + 승인

병렬 32 × executor sub-agent (sonnet)
  → 각자 자기 패키지 1개만
  → 자기 컨텍스트에 다른 패키지 없음
  → 권한: 자기 패키지 내 Edit + 테스트 실행만

verifier sub-agent (opus)
  → 32개 결과 통합 검증
  → 실제 monorepo 빌드 + 테스트 실행
  → 게이트 YAML 출력

사람 → 게이트 통과 시 머지

교훈

• “한 명에게 32개”는 “32명에게 1개씩”으로 거의 항상 다시 쓸 수 있다.
• 분할 후 각자에게 권한 격리까지 해야 안전.
• planner 단계의 사람 통독은 사고의 거의 모든 1차 방어선.