mandu-mcp-safe-change

Mandu MCP Safe Change

돌이키기 힘든 변경 을 실행할 때의 표준 래퍼. history.snapshot 으로 롤백 포인트를 찍고, tx.begin 으로 트랜잭션을 열고, 안에서 편집 + verify, 결과에 따라 tx.commit 또는 tx.rollback.

Trigger

• 마이그레이션: 경로 컨벤션 변경, 생성 barrel 재작성, contract 추출 등
• 대규모 리팩터: 레이어 재배치, 모듈 이동, 대량 import 경로 수정
• mandu.refactor.* / mandu.refactor.migrateRouteConventions / mandu.refactor.rewriteGeneratedBarrel / mandu.refactor.extractContract 호출 직전
• 사용자: "돌이킬 수 없는 변경", "한 번에 바꿔줘", "전체 프로젝트에 적용"
• 생성 파일 대량 재작성 (mandu_generate 를 전체 재실행)

Recipe (순서 고정)

mandu.history.snapshot              ← 롤백 포인트 (Tier-1)
  └─> mandu_begin                   ← 트랜잭션 시작 (alias of mandu.tx.begin)
       └─> <편집 / refactor tool 호출>
            └─> mandu-mcp-verify fast path
                 ├─ all green → mandu_commit  (alias of mandu.tx.commit)
                 │                └─> mandu_prune_history (선택, 오래된 스냅샷 정리)
                 └─ 실패       → mandu_rollback (alias of mandu.tx.rollback)
                                   └─> 스냅샷은 유지. 원인 분석 후 재시도

Step Detail

Step 1 — mandu.history.snapshot

mandu.history.snapshot({
  repoRoot: ".",
  label: "pre-route-migration-2026-04-20"
})

스냅샷은 .mandu/generated/** 같이 git 추적 밖 산출물까지 포함해서 저장한다. label 은 항상 붙인다 — mandu_list_history 로 볼 때 뭐였는지 알아야 함.

Step 2 — mandu_begin

mandu_begin({ label: "route-convention-migration" })

트랜잭션 ID 를 기억한다. Step 4 에서 쓴다. mandu.tx.status 로 상태 조회 가능.

Step 3 — 실제 변경

이제야 파괴적 도구를 호출한다. dry-run 이 있으면 먼저 dry-run:

mandu.refactor.migrateRouteConventions({ dryRun: true, ... })
  → 변경 목록 검토
mandu.refactor.migrateRouteConventions({ dryRun: false, ... })

복합 변경이면 여러 도구를 순차 호출 — tx 안이므로 중간 실패도 안전.

Step 4 — mandu-mcp-verify fast path

변경 후 검증. mandu-mcp-verify 의 병렬 4 콜 (ate.auto_pipeline, guard_check, lint, doctor). 특히 대규모 refactor 는 lint 에러를 쉽게 새로 만들기 때문에 lint 축을 반드시 포함한다 — 하나라도 빨간 상태로 tx_commit 하지 않는다.

Step 5a — 모두 green 이면 Commit

mandu_commit({ txId })