mandu-mcp-deploy

Files (1)

• SKILL.md

SKILL.md (first lines)

# Mandu MCP Deploy

프로덕션 배포 직전의 **fail-fast 파이프라인**. 개별 검증 도구를 손으로 나열하는
대신, `mandu.deploy.check` 와 `mandu.deploy.preview` 집계 도구를 쓴다.

## Trigger

- "배포", "release", "deploy"
- release tag 직전, `git push origin main` 직전
- 프로덕션 환경 업로드 전
- CI/CD 에서 deploy job 이전
- `mandu-deploy` task-shaped skill 이 활성화될 때

## Recipe (순서 고정, 게이트 엄격)

```
mandu_build                     ← 프로덕션 빌드 시작
  └─> mandu_build_status        ← green 대기 (polling)
       └─> mandu.deploy.check   ← Tier-0 aggregate: guard+contract+manifest 병렬
            │                      ─ fail → 즉시 중단, deploy_preview 금지
            └─> mandu_write_seo_file  ← sitemap/robots/meta 확정
                 └─> mandu.deploy.preview ← 프로덕션 리허설 (Tier-0)
                      └─> 사용자에게 배포 승인 요청
                           └─> (사용자 승인) 외부 배포 실행
```

## Step Detail

### Step 1 — `mandu_build`

```
mandu_build({ profile: "production" })
```

alias of `mandu.build`. 프로덕션 번들 생성. 반환에 jobId / status 포함.
이 호출은 비동기일 수 있다 — 즉시 반환 후 Step 2 로 poll.

### Step 2 — `mandu_build_status` (poll until green)

```
mandu_build_status({ jobId })
```

alias of `mandu.build.status`. status ∈ {pending, running, success, failed}.

- `success` → Step 3
- `failed` → 중단, 빌드 에러 분석 후 `mandu-mcp-verify` 로 이동
- `running` → 짧은 간격으로 재호출

CRITICAL: 빌드 `failed` 이면 **`mandu.deploy.check` 절대 호출하지 않는다**.
빌드가 깨진 상태에서 deploy check 를 돌리면 잘못된 positive/negative 가 나온다.

### Step 3 — `mandu.deploy.check` (Fail-Fast Gate)

```
mandu.deploy.check({ target: "bun" })
```

반환:
- `ok: true` → Step 4 로 진행
- `ok: false, blockers: [...]` → **즉시 중단**

blockers 예시:
- guard 위반 (레이어, 금지 import)
- contract validation 실패
- manifest 깨짐 (route 누락 / 중복)

각 blocker 는 가리키는 도구가 있다:
- guard → `mandu_guard_explain`, `mandu_guard_heal` (단, safe-change 감싸기)
- contract → `mandu_validate_contracts`, `mandu_create_contract`
- manifest → `mandu_validate_manifest`

blocker 를 고치면 Step 1 부터 재실행. `deploy_preview` 로 건너뛰지 않는다.

### Step 4 — `mandu_write_seo_file`

```
mandu_write_seo_file({ target: "sitemap" })
mandu_write_seo_file({ target: "robots" })
mandu_write_seo_file({ target: "meta" })
```

alias of `mandu.seo.write`. 프리뷰 도구 (`mandu_preview_seo`) 가 아니라
**실제 파일 기록**. 배포 전에 `public/sitemap.xml`, `public/robots.txt` 가 고정돼야 함.

선택 사항: 먼저 `mandu_preview_seo` 로 결과 확인 후 `mandu_write_seo_file`.
CI 에서는 바로 write.

### Step 5 — `mandu.deploy.preview`

```
mandu.deploy.preview({ port: 4173 })
```

프로덕션 빌드를 로컬에서 serve. 스모크 테스트 용도:
- 초기 페이지 로드
- 주요 라우트 200
- critical island 하이드레이션
- SEO 파일 서빙

preview 가 깨지면 배포 금지.

### Step 6 — 외부 배포 (프레임워크 밖)

Docker / Fly / Vercel / Cloudflare 등. 이 단계는 mandu MCP 범위 밖이므로
`mandu-deploy` (task-shaped skill) 의 Dockerfile / CI 예시 참조.

## 절대 규칙

| # | 규칙 | 이유 |
|---|------|------|
| D-1 | `deploy.check` 실패 → **즉시 중단**, preview 금지 | fail-fast. 깨진 빌드를 preview 해도 의미 없음 |
| D-2 | 빌드 `failed` → `deploy.check` **호출 금지** | 빌드 산출물이 없는데 check 돌리면 false negative |
| D-3 | `mandu_write_seo_file` 은 **check green 이후** | check 실패 상태로 SEO 쓰면 잘못된 meta 확정 |
| D-4 | preview 깨지면 **배포 중단** | 로컬에서 안 뜨는 빌드가 프로덕션에서 뜰 리 없다 |
| D-5 | 개별 검증 (`guard_check`, `validate_contracts`, `validate_manifest`) 를 **손으로 나열하지 않는다** | `deploy.check` 가 이들을 병렬 집계. 수동 나열 = AP-7 (index 참조) |
| D-6 | deploy.check blocker 를 `guard_heal` / refactor 로 고칠 땐 **safe-change 래핑** | 프로덕션 직전 파일 수정은 위험 변경 |

## Anti-patterns

From konamgil/mandu, MPL-2.0.

More from konamgil/mandu