AI 문서 주도 개발 MCP 구현 아이디어

share, idea · 2026-3-2

← 리스트로

DESIGN_MCP.md

1. 문서 목적

이 문서는 다음 목표를 위해 작성한다.

  • doc-driven-implementer-v1, doc-driven-designer-v1 같은 규칙 기반 개발 워크플로우를 장기적으로 운영 가능한 형태로 정리
  • MCP(Model Context Protocol)를 활용하되, 단순 도구 연결을 넘어 **진행 게이트(Validation Gate)**를 강제하는 아키텍처 제안
  • 공통 설계 문서 + 피처 단위 설계 문서를 함께 운용하는 확장 가능한 문서 체계 제안
  • 하네스(특정 에이전트/클라이언트) 종속성을 낮춘 운영 모델 수립

2. 배경 및 문제 정의

현재 워크플로우의 강점:

  • 문서 중심(Requirements/Design/Implement)으로 개발 의도가 명확함
  • phase 단위 진행, 완료 보고, handoff/ctx 저장이 체계적임
  • 재시작/인수인계가 비교적 쉬움

현재 한계:

  • 규칙이 프롬프트에만 있을 경우 우회 가능
  • 문서 체크/증거 수집/완료 판정이 수동일 때 품질 편차 발생
  • 중간에 문서가 바뀌면 어떤 phase에 영향이 있는지 추적이 어려움
  • 하네스별(도구별) 동작 차이로 재현성이 낮아질 수 있음

핵심 결론:

  • MCP는 **최소조건(연결 표준)**이고, 실제 강제는 별도 Workflow Engine이 담당해야 함
  • 문서/규칙은 선언(Policy), 엔진은 집행(Enforcement), 기록은 증거(Evidence)로 분리해야 함

3. 핵심 설계 원칙

  1. 정책과 실행 분리
    규칙(문서/스킬)과 강제(엔진)를 분리하여 운영한다.

  2. 게이트 기반 진행
    조건 미충족 시 다음 phase로 절대 진행하지 않는다.

  3. 문서 변경 허용 + 재검증 강제
    개발 중 문서 수정은 허용하되, 영향 분석 및 재계획을 반드시 거치게 한다.

  4. 하네스 비종속
    Codex/Claude/기타 도구는 동일 MCP API를 호출하게 하여 동작을 통일한다.

  5. 증거 중심 완료 판정
    “완료 선언”이 아니라 테스트 결과/문서 반영/컨텍스트 저장을 데이터로 확인한다.

4. 제안 아키텍처 (요약)

┌──────────────────────────┐
│ Agent Harness (Codex 등) │
└───────────┬──────────────┘
            │ MCP
┌───────────▼─────────────────────────────┐
│ workflow-mcp-server                     │
│  - Tool API (start/complete/sync/...)   │
│  - Validation Gate                        │
│  - Policy Loader (rule/skill spec)       │
└───────────┬─────────────────────────────┘
            │
┌───────────▼─────────────────────────────┐
│ Workflow Engine (State Machine)         │
│  - phase 상태/전이 관리                  │
│  - entry/exit 조건 검증                  │
│  - 문서 revision lock 관리               │
└───────┬───────────────┬─────────────────┘
        │               │
┌───────▼──────┐  ┌─────▼────────────────┐
│ Evidence DB   │  │ Docs/Context Sync    │
│ (tests, diff, │  │ IMPLEMENT/Handoff/   │
│ commit, logs) │  │ ctxbin 저장 자동화   │
└───────────────┘  └──────────────────────┘

5. 구성 요소 상세

5.1 MCP 서버 (최소조건 + 확장 포인트)

역할:

  • 에이전트가 호출할 표준 도구 제공
  • 하네스별 차이를 흡수
  • 단순 래퍼가 아닌 validation 실행 지점 제공

5.2 Workflow Engine (강제 레이어)

역할:

  • phase 상태 관리(pending, in_progress, blocked, done)
  • entry 조건/exit 조건 강제
  • “phase 완료 후 사용자 승인 대기” 같은 절차성 규칙 강제

5.3 Evidence/Docs Sync (검증/기록 레이어)

역할:

  • 실행 근거 수집(테스트 명령, 결과, 변경 파일, 커밋)
  • 문서 자동 동기화(체크박스, handoff status)
  • 컨텍스트 저장(ctxbin ctx save) 자동화

6. 문서 모델 (공통 + 피처)

장기 운영을 위한 권장 구조:

docs/
  global/
    REQUIREMENTS.md
    DESIGN.md
    IMPLEMENT.md
  features/
    feature-a/
      REQUIREMENTS.md
      DESIGN.md
      IMPLEMENT.md
    feature-b/
      REQUIREMENTS.md
      DESIGN.md
      IMPLEMENT.md

권장 규칙:

  • 공통 문서: 시스템 전역 정책/아키텍처/기본 제약
  • 피처 문서: 특정 기능의 요구사항/설계/phase 실행 계획
  • 충돌 시 우선순위:
    • 사용자 최신 지시 > 피처 문서 > 공통 문서
    • 단, 공통 보안/컴플라이언스 규칙은 override 불가로 별도 정책화 가능

7. “문서 수정 가능” 요구사항 반영 설계

중간 문서 수정은 허용하되, 아래 절차를 강제한다.

  1. propose_doc_change 호출
  • 변경 대상 문서
  • 변경 이유
  • 영향 범위(예상)
  1. approve_doc_change (또는 사용자 승인)
  • 승인 전에는 관련 phase를 blocked 처리 가능
  1. replan_phase
  • 수정된 문서 기준으로 phase 계획 재작성
  • 필요한 경우 이미 완료된 phase를 stale로 재표시
  1. revision lock 업데이트
  • phase 시작 시 문서 revision 해시를 잠금
  • 완료 시점에 불일치하면 complete_phase 거부

8. Validation Gate 설계

complete_phase 시 필수 검증 예시:

  1. 테스트 증거 존재/성공
  • 예: pnpm test 결과 pass
  1. 문서 동기화 완료
  • IMPLEMENT 체크박스 갱신
  • handoff 섹션 갱신(Done/Next/Blockers/Latest commit)
  1. 컨텍스트 저장 완료
  • ctxbin ctx save 성공 여부
  1. 리비전 무결성
  • 시작 시점 revision lock과 현재 문서 revision 비교
  1. 스코프 무결성(선택)
  • 현재 phase 범위를 벗어난 과도한 변경 차단(경고 또는 실패)

검증 실패 시:

  • complete_phase는 실패 응답 반환
  • 상태는 in_progress 또는 blocked 유지
  • 실패 원인을 구조화된 에러로 전달

9. MCP Tool 제안 (MVP)

최소 툴 세트:

  1. start_phase
  • 입력: workflow_id, phase_id
  • 출력: entry 조건, 잠금된 문서 revision, 필수 체크리스트
  1. record_evidence
  • 입력: 테스트 명령/결과, 변경 파일, 커밋 SHA, 메모
  • 출력: evidence id
  1. sync_docs
  • 입력: 문서 업데이트 의도(체크박스/Handoff/노트)
  • 출력: 적용 결과, diff 요약
  1. complete_phase
  • 입력: phase_id
  • 동작: validation gate 실행
  • 출력: pass/fail + 실패 사유

문서 변경 대응 툴(권장):

  1. propose_doc_change
  2. approve_doc_change
  3. replan_phase

10. 정책 명세(Policy-as-Code) 예시

예시 YAML 스키마:

workflow: doc-driven-implementer-v1
version: 1.0.0

phase_rules:
  single_active_phase: true
  require_user_ack_before_next_phase: true

entry_checks:
  - type: dependency_phase_done
  - type: required_docs_exist

exit_checks:
  - type: test_passed
    command: pnpm test
  - type: docs_synced
    files:
      - IMPLEMENT_PHASE2.md
  - type: handoff_updated
  - type: context_saved

doc_revision:
  lock_on_phase_start: true
  fail_on_mismatch_at_complete: true

11. ctxbin 연동 전략

단기:

  • 기존 ctxbin을 저장소 백엔드로 계속 사용
  • complete_phase 성공 후 ctxbin ctx save 자동 수행

중기:

  • Context Store 인터페이스 분리
  • ctxbin/Redis/DB 교체 가능하게 추상화

장기:

  • phase/evidence/context를 통합 조회하는 UI 또는 CLI 제공

12. 단계별 도입 로드맵

Phase A (MVP)

  • MCP 서버 기본 툴 4개(start_phase, record_evidence, sync_docs, complete_phase)
  • doc-driven-implementer-v1 정책 반영
  • 완료 게이트 필수 3종: 테스트/문서/handoff+ctx

Phase B (문서 변경 워크플로우)

  • propose_doc_change, approve_doc_change, replan_phase
  • revision lock + mismatch 차단
  • stale phase 자동 마킹

Phase C (멀티 피처 확장)

  • 공통/피처 문서 계층화
  • feature별 독립 워크플로우 인스턴스
  • 교차 영향 분석 고도화

Phase D (하네스 독립 운영 안정화)

  • 다양한 에이전트 하네스 연결 테스트
  • 정책 버전 관리/마이그레이션
  • 운영 대시보드(phase/evidence/history)

13. 기대 효과

  • 규칙 준수율 상승(“말로만 phase gate” 문제 해소)
  • 문서와 코드의 동기화 자동화
  • 중간 설계 변경을 허용하면서도 추적 가능성 유지
  • 하네스가 바뀌어도 동일한 운영 품질 확보

14. 리스크 및 대응

  1. 초기 구현 복잡도 증가
    대응: MVP는 4개 툴 + 3개 게이트부터 시작

  2. 과도한 차단으로 개발 속도 저하
    대응: 실패 시 “warn 모드”와 “strict 모드” 분리

  3. 문서 품질이 낮으면 자동화 품질도 낮음
    대응: 문서 템플릿/린트 규칙 도입

  4. 기존 레거시 타입/테스트 이슈로 게이트 오탐
    대응: phase별 필수 게이트를 점진적으로 강화

15. 결론

  • MCP 통합은 필요하지만 충분조건은 아니다.
  • 실질적 성공 조건은:
    • Workflow Engine으로 phase 전이를 강제하고
    • Evidence/Docs Sync로 완료 근거를 자동 기록/검증하며
    • 문서 변경을 허용하되 revision 기반 재검증을 의무화하는 것

이 방향이면, 현재의 문서 주도 개발 문화를 유지하면서도 장기적으로 하네스 비종속/재현 가능한 운영 체계를 구축할 수 있다.