Mandu MCP Verify

편집 직후 / 생성 직후 / pre-commit 에서 도는 표준 검증 루프. 핵심은 "하나의 ate 파이프라인 + guard + 구조 진단" 을 병렬 fast path 로 먼저 돌리고, 실패했을 때만 세분 도구로 drill-down 하는 것.

Trigger

• 파일 편집 직후 (특히 app/, spec/, src/shared/contracts/)
• mandu_generate 완료 직후 (create-flow 가 자동 전이)
• "check 해줘", "제대로 된 거야?", "괜찮아?"
• stop-hook / pre-commit 자동 실행
• 사용자가 명시적으로 "verify", "validate", "검증"

Fast Path (병렬, 기본값)

네 도구는 서로 독립. 병렬 호출.

┌─────────────────────────────┐
│ mandu.ate.auto_pipeline     │  ← Tier-0: extract/generate/run/heal 전부
├─────────────────────────────┤
│ mandu_guard_check           │  ← Tier-1: 아키텍처 규칙 위반 스캔
├─────────────────────────────┤
│ mandu.lint                  │  ← 가드레일-lint: 코드 품질 스캔 (oxlint)
├─────────────────────────────┤
│ mandu_doctor                │  ← Tier-0: 구조/import/location 진단
└─────────────────────────────┘
       네 개를 parallel 호출

인자 예:

mandu.ate.auto_pipeline({
  repoRoot: ".",
  oracleLevel: "standard",
  useImpactAnalysis: true,    // 변경된 라우트만 대상
  autoHeal: false              // heal 은 별도 단계
})

mandu_guard_check({ repoRoot: "." })

mandu.lint({ typeAware: false })   // oxlint 미설치 시 조용히 skip

mandu_doctor({ repoRoot: "." })

네 응답을 수집하고 pass/fail 매트릭스를 만든다:

도구	pass	fail 의 의미
ate.auto_pipeline	테스트 통과 + 계약 일치	테스트 실패 또는 impact 드리프트
guard_check	레이어/금지 import 위반 없음	아키텍처 규칙 위반
lint	oxlint error 0	error 1+ (warning 은 informational)
doctor	파일 위치 / import 정상	구조 결함

네 개 모두 green → verify 종료. 사용자에게 압축 요약 제시.

Drill-Down (실패 시에만)

fast path 가 빨간 항목을 돌려주면 그 카테고리별로만 drill-down. 세 종류가 다 실패했다고 모든 drill-down 을 돌리지 말고, 응답에 들어온 카테고리만.

Guard 실패

mandu_guard_explain({ violationId })    ← 먼저: 왜 위반인지 설명
  → (자동 수정 가능하면) mandu_guard_heal({ autofix: true, violationIds: [...] })
  → (수동 수정이면) 사용자에게 수정 지시 후 fast path 재실행

ATE 실패 (테스트 실패 / 힐 후보 있음)

mandu.ate.feedback({ runId })           ← 힐 후보의 카테고리/우선순위
  → mandu.ate.apply_heal({ runId, healIndex, createBackup: true })
  → fast path 의 ate.auto_pipeline 재실행

중요: mandu.ate.heal + mandu.ate.apply_heal 을 수동으로 엮지 않는다. ate.auto_pipeline 이 이미 heal 후보를 계산했고, 우리는 적용 여부만 결정.

Lint 실패 (oxlint error 1+)

mandu.lint({ typeAware: false })    ← 이미 fast path 에서 뜬 상태
  → 반환 payload 의 error 목록에서 rule id 확인
  → site-level 수정 (절대 전역 off 로 회피 금지 — `mandu-lint` §AP-1)
  → fast path 재실행

oxlint 가 설치되어 있지 않으면 fast path 의 lint 응답은 installed: false 로 돌아온다. 그 경우 mandu.lint.setup({}) 로 설치하도록 사용자에게 안내 — 기존 프로젝트는 opt-in 이 필요함. 신규 프로젝트는 mandu init 이 이미 배선했으므로 이 경로는 드물다.

Doctor 실패 (구조 / import)

mandu_check_import({ filePath })        ← 잘못된 import 경로 상세
  → mandu_check_location({ filePath })  ← 파일 위치 규칙 위반 상세
  → 사용자에게 수정안 제시 (또는 safe-change 로 전이)

Kitchen (런타임 에러 동반)

dev 서버 돌고 있고 fast path 중 런타임 성격의 실패가 보이면:

mandu_kitchen_errors({ limit: 20 })

절대 규칙

#	규칙	이유
V-1	ATE 는 반드시 mandu.ate.auto_pipeline 하나로 시작	개별 ate_* 도구 수동 조합 = AP-1 (index 참조)
V-2	fast path 는 병렬 호출	세 도구 독립. 순차 호출은 왕복 3배 낭비
V-3	mandu_guard_heal 은 drill-down 단계에서만	fast path 에서 autofix 를 켜면 스냅샷 없이 자동 수정됨
V-4	drill-down 은 실패한 카테고리에만	통과한 쪽까지 drill 해서 왕복 부풀리지 않는다
V-5	heal 후에는 fast path 를 다시 돌린다	수정이 새 위반을 만들 수 있음. 1회 재확인
V-6	대규모 수정이 필요한 drill-down 은 mandu-mcp-safe-change 로 escalate	snapshot + tx 없이 큰 수정 금지

Anti-patterns

AP-1 — ATE 수동 분해 (index AP-1 재인용)

• 증상: mandu.ate.extract → mandu.ate.generate → mandu.ate.run → mandu.ate.heal → mandu.ate.apply_heal 를 손으로.
• 왜 안 되나: 왕복 5배 + 중간 실패 처리 로직을 재구현하게 됨.
• 대응: mandu.ate.auto_pipeline 단 하나.

AP — fast path 순차 호출

• 증상: auto_pipeline 결과 보고 → guard_check → doctor 를 하나씩.
• 왜 안 되나: 독립 작업을 직렬화. 응답 집계가 늦어지고 사용자 대기 시간이 3배.
• 대응: V-2, 병렬 호출.

AP — heal 없이 재생성

• 증상: ate 또는 guard 실패 → mandu_generate 재호출로 "리셋" 시도.
• 왜 안 되나: 같은 입력이면 같은 결과. 원인은 입력 쪽 (contract / slot / island) 에 있음.
• 대응: 해당 카테고리 drill-down → guard_heal / apply_heal / 수동 수정.

AP — verify 생략

• 증상: 편집 후 바로 git add . && git commit.
• 왜 안 되나: 위반을 커밋에 박음. CI 에서 reject.
• 대응: stop-hook 또는 명시적 mandu-mcp-verify 호출.

Quick Reference

편집 완료
  ┌─ mandu.ate.auto_pipeline ─┐
  ├─ mandu_guard_check        │  (parallel)
  └─ mandu_doctor             ─┘
  ────────────────────────────
  all green? → 종료
  실패? → 해당 카테고리만 drill-down:
           guard_explain / guard_heal
           ate.feedback / ate.apply_heal
           check_import / check_location
         → 재실행 (fast path)

목표 호출 수:

• all-green 경로: 3 calls (parallel)
• 1 카테고리 drill + 재실행: 3 + 12 + 3 = 78 calls
• 모든 카테고리 실패: escalate to mandu-mcp-safe-change

See Also

• mandu-mcp-index — Tier/aggregate 우선순위 + AP-1 (ATE 수동 분해)
• mandu-mcp-create-flow — 생성 직후 이 skill 로 자동 전이
• mandu-mcp-safe-change — drill-down 이 대규모 수정으로 번질 때
• mandu-debug — 에러 카테고리별 도메인 지식
• mandu-guard-guide — guard 위반 유형별 수정 방법
• mandu-lint — 가드레일-lint 축 상세 (setup / type-aware / 자동수정 안전 절차)