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

AP-7 — Manual Build Pipeline (index AP-7 재인용)

• 증상: 배포 전에 mandu_build + mandu_guard_check + mandu_validate_contracts + mandu_validate_manifest + mandu_preview_seo 를 손으로.
• 왜 안 되나: mandu.deploy.check 가 이 시퀀스를 병렬 집계로 이미 처리. 수동 나열은 왕복 5배 + 순서 오류 가능.
• 대응: mandu.deploy.check 한 방.

AP — preview 스킵

• 증상: deploy.check 통과했다고 바로 외부 배포.
• 왜 안 되나: check 는 정적 검증. 실제 serve 에서만 드러나는 런타임 에러 (island 하이드레이션, SSR 에러, asset 경로) 가 누락.
• 대응: Step 5 필수.

AP — write 전에 preview

• 증상: mandu_preview_seo → mandu.deploy.preview → mandu_write_seo_file.
• 왜 안 되나: preview 가 아직 안 쓰인 SEO 파일로 돌면 실제 배포와 차이. write 를 preview 전에.
• 대응: Step 4 → Step 5 순서 지킨다.

AP — 빌드 실패 후 check 강행

• 증상: mandu_build_status 가 failed 인데 "뭐라도 확인해보자" 로 deploy.check.
• 왜 안 되나: 빌드 산출물 없이 돌린 check 는 신뢰 불가. 왕복 낭비.
• 대응: D-2, 빌드 고친 뒤 Step 1 부터.

AP — blocker 를 배포 전에 급하게 heal

• 증상: deploy.check 위반을 guard_heal 로 바로 수정 후 다시 check.
• 왜 안 되나: 배포 직전 수정은 위험 변경. 스냅샷 없이 자동수정 = 롤백 어려움.
• 대응: D-6, mandu-mcp-safe-change 래퍼 안에서 heal.

Quick Reference

release 준비
  mandu_build                  (1 call)
  mandu_build_status           (poll, 1~n calls)
  mandu.deploy.check           (1 call, fail-fast gate)
    └ blocker 있으면 safe-change 로 escalate
  mandu_write_seo_file         (1~3 calls)
  mandu.deploy.preview         (1 call)
  ────────────────────────────
  green → 외부 배포
  실패   → 해당 단계에서 중단, 원인 수정 후 처음부터

표준 호출 수: 5~8 (polling 제외). 수동 파이프라인 (AP-7) 은 12+.

See Also

• mandu-mcp-index — AP-7 (manual build pipeline), Tier-0 aggregate 규칙
• mandu-mcp-verify — blocker 진단 / drill-down
• mandu-mcp-safe-change — 배포 직전 수정은 safe-change 필수
• mandu-deploy — Dockerfile / nginx / CI 설정 (외부 배포 단계)