Claude Code를 활용한 설명서 우선 개발(MDD) 워크플로우 업데이트 공유

커뮤니티 반응

작성자가 직접 개발한 도구의 업데이트를 공유한 글로, 체계적인 AI 개발 워크플로우에 대해 긍정적인 관심이 예상된다.

합의점 vs 논쟁점

합의점

AI 생성 코드의 품질은 제공된 컨텍스트의 품질에 비례한다.
테스트는 구현 전에 반드시 실패함을 먼저 확인해야 신뢰할 수 있다.

실용적 조언

AI 코딩 에이전트를 사용할 때 구현 전 테스트 코드를 먼저 작성하여 Red/Green 단계를 거치도록 워크플로우를 설계하라.
대규모 프로젝트는 단순 기능 나열이 아닌 '사용자가 무엇을 할 수 있는지'를 정의하는 데모 상태 기반의 마일스톤으로 관리하라.

섹션별 상세

테스트 주도 개발을 강화하기 위해 Red Gate와 Green Gate 시스템을 도입했다. 구현 전 테스트 실패를 확인하는 Red Gate와 최대 5회의 진단 우선 루프로 제한된 Green Gate를 통해 AI의 무분별한 재시도를 방지하고 코드 품질을 확보한다. 이를 통해 테스트가 구현 전에 우연히 통과하는 오류를 차단하고 논리적 결함을 조기에 발견한다.

대규모 프로젝트 관리를 위해 Initiative, Wave, Feature의 3단계 계층 구조를 도입했다. 전체 목표인 Initiative 아래에 데모 가능한 마일스톤인 Wave를 설정하고, 각 Wave는 실제 동작을 확인하는 '데모 상태' 검증을 거쳐야 완료되도록 설계했다. 단순 테스트 통과가 아닌 실제 작동하는 소프트웨어 중심의 개발 프로세스를 강제하여 프로젝트의 실질적 진척도를 관리한다.

작업 효율을 높이기 위해 독립적인 컨텍스트 수집 및 구현 단계에서 병렬 에이전트 실행 기능을 추가했다. 실행 전 파일 중복 수정 여부를 체크하여 동일 파일에 접근할 경우 자동으로 순차 실행으로 전환함으로써 충돌을 방지한다. 이 방식은 독립적인 기능 구현 시 개발 속도를 비약적으로 향상시키면서도 데이터 무결성을 유지한다.

문서와 코드 간의 동기화를 위해 모든 생성 문서에 명령어 버전을 스탬핑하는 시스템을 구축했다. /mdd status 명령어로 현재 버전과 일치하지 않는 오래된 문서를 식별하고, upgrade 명령어로 이를 일괄 패치할 수 있다. 또한 일회성 작업이나 조사를 위한 Task 문서 타입을 추가하여 영구 보존이 필요 없는 작업의 워크플로우를 분리했다.

용어 해설

설명서 우선 개발(MDD): — Manual-First Development의 약자로, 코드를 작성하기 전에 문서(사양서)를 먼저 작성하고 이를 테스트, 구현, 감사의 단일 진실 공급원(Source of Truth)으로 활용하는 워크플로우이다. AI가 추측에 의존하지 않고 명확한 컨텍스트를 바탕으로 코드를 생성하도록 유도하여 품질을 높이는 것이 핵심이다.
테스트 스켈레톤(Test Skeleton): — 실제 로직을 구현하기 전에 작성하는 테스트의 뼈대 구조이다. 구현 전 테스트가 실패함을 확인하는 Red Gate 단계와 구현 후 통과를 확인하는 Green Gate 단계를 통해 코드의 의도와 실제 동작이 일치하는지 검증하는 데 사용된다.
병렬 에이전트(Parallel Agents): — 독립적인 작업을 수행하기 위해 여러 개의 AI 에이전트를 동시에 실행하는 방식이다. 파일 중복 수정 여부를 사전에 체크하여 충돌이 없을 때만 병렬로 처리하고, 충돌 위험이 있으면 순차 실행으로 전환하여 효율성과 안전성을 동시에 확보한다.
터미널 사용자 인터페이스(TUI): — 텍스트 기반 터미널 환경에서 그래픽 요소나 대화형 메뉴를 제공하는 인터페이스 방식이다. 이 프로젝트에서는 .mdd 파일들을 읽어 전체 프로젝트 상태를 시각적으로 관리하는 대시보드 형태로 구현되어 개발자의 편의성을 높인다.

언급된 도구

Claude Code추천

Anthropic의 CLI 기반 AI 코딩 에이전트

Claude Code Starter Kit추천링크

MDD 워크플로우가 구현된 프로젝트 템플릿 및 도구 모음

언급된 리소스

GitHubClaude Code Mastery Project Starter Kit GitHub