mandu-mcp-safe-change

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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 })
```

그리고 선택적으로 오래된 스냅샷 정리:

```
mandu_prune_history({ olderThan: "7d", keep: 10 })
```

### Step 5b — 실패면 Rollback

```
mandu_rollback({ txId })
```

그리고 스냅샷은 **삭제하지 않는다**. 원인 분석 / 로그 공유 후 재시도에 필요.

```
mandu.history.snapshot 은 그대로
  → 로그 수집
  → 원인 수정
  → Step 2 부터 다시
```

## 절대 규칙

| # | 규칙 | 이유 |
|---|------|------|
| SC-1 | `refactor_*` 또는 대규모 마이그레이션은 **반드시** 이 레시피 안에서 | snapshot 없는 변경은 롤백 불가 |
| SC-2 | `history.snapshot` 은 **`tx.begin` 전에** | tx 내부에서 찍으면 rollback 시 스냅샷도 사라질 수 있음 |
| SC-3 | `refactor_*` 도구는 **dry-run 먼저** (도구가 지원하면) | 변경 범위 가시화 없이 실행 금지 |
| SC-4 | verify 는 fast path 의 **세 개 모두** | 한두 개만 확인하고 커밋하는 건 안전망 의미 없음 |
| SC-5 | rollback 시 **스냅샷 유지** | 재시도 / 재현 / 로그 공유에 필요 |
| SC-6 | 하나의 tx 에 **하나의 의미 단위** | 여러 독립 변경을 한 tx 로 묶으면 부분 rollback 불가 |

## Anti-patterns

### AP — Snapshot Skip (index AP-3)
- 증상: `mandu.refactor.*` 를 `history.snapshot` 없이 바로 호출.
- 왜 안 되나: git 은 `.mandu/generated/**`, `node_modules/**`, 런타임 아티팩트를 추적하지 않는다. 실패 시 수동 복구 불가.
- 대응: Step 1 항상 실행. 예외 없음.

### AP — tx 없이 복합 변경
- 증상: `mandu_add_route` × 5 + `mandu_create_contract` × 3 + `mandu_generate` 를 독립 호출.
- 왜 안 되나: 중간에 실패하면 부분 생성물이 남아 guard violation 유발.
- 대응: `mandu_begin` ~ `mandu_commit` 또는 집계 도구 (`mandu.feature.create`) 로 묶는다.

### AP — Commit 전 verify 생략
- 증상: refactor → 바로 `mandu_commit`.
- 왜 안 되나: tx 커밋 = 되돌리기 포기. 검증 없이 커밋하면 깨진 상태가 확정.
- 대응: SC-4, fast path 3 개 모두 green 확인.

From konamgil/mandu, MPL-2.0.

More from konamgil/mandu