매뉴얼 주도 개발: Claude Code 확신 편차 방지 가이드

매뉴얼 주도 개발(MDD)은 Claude Code에서 자신만만하게 벗어나는 문제를 해결하기 위해 설계된 방법론으로, AI가 시스템에 대한 잘못된 가정을 바탕으로 작업하기 때문에 잘못된 코드를 생성하면서도 컴파일되고 자신의 테스트를 통과시키는 현상을 다룹니다.

문제: 자신만만하게 벗어남

Claude Code가 대규모 생산 코드베이스에서 작업할 때, 몇 개의 파일을 읽고 패턴을 추론한 후 가정을 바탕으로 코딩을 시작합니다. 이로 인해 자신만만하게 벗어나는 현상이 발생합니다. 코드는 올바르게 보이고 실행되며 테스트를 통과하지만, Claude가 실제 시스템 동작이 아닌 자신의 가정에 대해 테스트를 작성했기 때문에 잘못된 것입니다. 이러한 벗어남은 실제 사용자가 Claude가 알지 못했던 경계 사례를 만날 때 생산 환경에서만 드러납니다.

저자는 이것이 단순히 Claude가 당신의 시스템을 모르는 문제가 아니라, 개발자들도 자신의 전체 시스템을 신뢰할 수 있게 설명할 수 없다는 점이라고 지적합니다. 밤 11시에는 운영자가 특정 그룹에만 범위가 지정되어 있다는 점, ROLE_HIERARCHY가 세 개의 다른 파일에 정의되어 있다는 점, 또는 기본 계층 정책이 시스템 전용이며 API를 통해 생성할 수 없다는 점을 언급할 기억이 나지 않을 것입니다.

생산 환경에서의 MDD 결과

MDD를 사용한 생산 환경 감사에서:

일곱 개의 섹션 감사
190개의 발견 사항 식별
876개의 새로운 테스트 작성
7시간 48분의 Claude Code 세션 시간
추정 234~361시간의 인간 개발자 시간 절감 (30-46배 압축 비율)
모든 섹션에서 CLAUDE.md 규칙 위반 제로

코드베이스에는 200개 이상의 경로, 80개 이상의 모델, 그리고 네트워크 정책을 호스트의 실시간 nftables 규칙으로 변환하는 데몬 시행 파이프라인이 있었습니다.

MDD가 다른 도구와 다른 점

MDD는 기존 도구와 다른 문제를 해결합니다:

GSD는 컨텍스트 부패(세션이 채워질수록 품질 저하)를 해결합니다
Mem0와 Claude-Mem은 세션 건망증(세션이 끝날 때 모든 것을 잊어버림)을 해결합니다
MDD는 자신만만하게 벗어남(잘못된 가정에 기반한 잘못된 코드)을 해결합니다

세 가지 모두 충돌 없이 함께 실행될 수 있습니다. 실시간 규칙 시행을 모니터링하는 RuleCatch는 MDD를 사용한 SwarmK 빌드 동안 MDD 없이 진행한 세션에 비해 규칙 위반이 60% 적었다고 보고했습니다. 동일한 모델, 동일한 규칙, 동일한 코드베이스입니다.

이 방법론, 프롬프트, 섹션별 데이터는 소스에 따라 문서화되고 재현 가능합니다.

📖 전체 소스 읽기: r/ClaudeAI