# Ship Workflow Ship

> 发布或导出检查 → Go/No-Go → 归档。当审查通过后需要上线或交付最终产物，或提到"发布""上线""ship""Go/No-Go"

- Skill: `zeroz-lab/ship-workflow-ship` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zeroz-lab/ship-workflow-ship`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zeroz-lab/ship-workflow-ship/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: zeroz-lab (https://skillmd.com/u/zeroz-lab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zeroz-lab/ship-workflow-ship

---


# Ship — 发布与交付


## 入口/出口
- **入口**: 通过 review 的代码
- **出口**: `docs/features/<name>/05-ship.md` + `docs/features/<name>/README.md`（聚合 README + 事后总结）
- **指向**: 完成后进入 `reflect-team-retro`（可选）
- **输出路径**: → ship-workflow-land
- **前置加载**: CANON.md + `verify-workflow-review/SKILL.md`

## 何时不使用
- 纯配置变更（环境变量、DNS）— 可在监控下直接变更
- 功能尚未通过 review — 必须先完成审查
- 依赖尚未就绪（数据库 migration 未审批、第三方服务未配置）

## Iron Law

<HARD-GATE>
没有已验证、可交付、可追溯的发布计划就不上线。`software` 需要 Staging、Go/No-Go、回滚计划；非软件产物需要导出验证、最终文件路径、版本归档和验收记录。
spec / plan / review 已要求同步的项目级文档，必须在 ship 阶段写入 `Documentation Sync` 并明确状态；缺少状态不得收口。
</HARD-GATE>

## 流程

### Phase A：预发检查

先读取 spec 的 `artifact_type`：
- `software`（默认）→ 加载 `ship-infrastructure-deploy`，按其 Pre-Launch 检查表逐项执行代码质量、安全、性能、基础设施和文档验证
- `document` / `article` / `deck` / `visual` → 加载 `ship-artifact-export`，执行导出、预览、归档和交付检查

验证命令（必须运行）：
```bash
npm test && npm run build && npm run lint && npx tsc --noEmit
```

### Phase B：质量门 — Ship Audit Army（发布审计军团）

预发检查通过后，按产物类型并行分派相应 auditor 做发布前专项审计：

```
Pre-launch checks (Phase A passed)
    │
    ├── agents/ship-security-auditor.md      → 安全审计: OWASP、输入边界、认证授权、数据暴露、依赖
    ├── agents/ship-performance-auditor.md   → 性能审计: 关键路径、N+1查询、内存资源、Bundle影响、退化
    ├── agents/ship-accessibility-auditor.md → 无障碍审计: WCAG合规、屏幕阅读器、表单错误、动态内容
    ├── agents/ship-docs-auditor.md          → 文档审计: CHANGELOG、README、迁移指南、API文档、错误信息
    └── agents/ship-artifact-export-auditor.md → 非 software 导出 QA: source/final 对齐、格式、归档、交付包验证
            │
            ▼
    收集审计结果 → 分级合并 → 修正 → 进入 Staging（Phase B.5）
```

每个 auditor 输出 Blocking / Important / Suggestion 三级反馈。

阶段技能只分派已被最少触发条件选中的 auditor；未被选中的 auditor 不产出占位反馈。

**反馈处理规则：**
- **Blocking** — 必须解决，不上线直到修复
- **Important** — 强烈必须修复，不修复需在 ship 报告中记录风险接受理由
- **Suggestion** — 自主判断，采纳后标注来源

**最少触发条件：**
- 小型变更（单文件、无安全/UI 敏感）→ 可跳过 Audit Army
- `software` 标准变更 → 至少 security + docs 双审计
- 非 software 标准变更 → 至少 artifact-export + docs 双审计
- 有 UI 变更 → 加 accessibility
- 有性能敏感变更（数据处理、查询、前端 bundle）→ 加 performance
- 用户指定 `--full` → 当前产物类型相关角色全开

**保留向后兼容：** 高风险变更也可加载专项审查技能：
- `verify-quality-security/SKILL.md` — 深度安全专项
- `verify-quality-performance/SKILL.md` — 深度性能专项
- `verify-frontend-accessibility/SKILL.md` — 深度无障碍专项

### Phase B.5：Staging 验证（仅 `software` 强制）

`software` 上线前必须经过 staging 环境验证：

**验证步骤：**
1. 部署到 staging 环境
2. 运行完整测试套件在 staging 数据上：`npm test`
3. 手动冒烟测试关键路径（用户注册、登录、核心流程）
4. 验证与下游依赖的集成（API mock 关闭，真实调用）
5. 确认数据 migration 向前兼容
6. 确认回滚脚本可用

**staging 不完全 == 不上线。** 所有 `software` 验证必须全部绿色才能进入 Go/No-Go。

非 software 产物在这一阶段改为执行最终交付包验证：
1. 打开 final 文件或预览
2. 检查 source / final / review / ship 记录是否能互相追踪
3. 核对文件名、格式、路径、版本说明
4. 标记 human partner / CI 的最终打开验证结果

### Phase C：Go/No-Go 决策

文档化：

```
## Go/No-Go
- [ ] 阻塞项：无未解决的 Critical 问题
- [ ] 已知风险：[列出]
- [ ] 回滚计划：已准备（强制！）
```

**回滚计划模板：**

```markdown
## 回滚计划

### 触发条件
- 错误率 > 2x 基准
- P95 延迟 > [X]ms

### 回滚步骤
1. 禁用 feature flag（如适用）
   或
1. 部署上一版本：`git revert <commit> && git push`
2. 验证回滚：健康检查、错误监控
3. 沟通：通知团队

### 数据库执行
- Migration [X] 有 rollback
- 新功能插入的数据：[保留 / 清理]

### 回滚时间
- Feature flag: < 1 分钟
- 重部署前一版本: < 5 分钟
- DB rollback: < 15 分钟
```

### Phase D：文档聚合

自动生成 `docs/features/<name>/README.md`，包含：
- `Feature Summary`：owner、日期、状态、artifact_type、最终结果、来源目标
- `Document Index`：`00-brainstorm.md` 到 `07-deploy-report.md` 的阶段证据状态
- `Timeline`：关键阶段日期、证据路径和备注
- `Key Decisions`：ADR / design / ship 决策索引、理由和当前状态
- `Delivery Outcome`：已交付、未交付、最终产物、用户可见变化、项目文档和变更统计
- `Verification Evidence`：review / ship / canary / deploy 门禁证据、结果和 owner
- `Residual Risks`：剩余风险、影响、owner 和 tracking
- `Follow-up Actions`：后续动作、owner、due date 和 tracking
- `Retro Notes`：做得好、应改变、可复用经验

同时检查并记录 `Documentation Sync`：
- `Updated project docs`
- `Deferred project docs`
- `CHANGELOG.md updated`
- `README verified`
- 其他 review / plan 标记为必须同步的项目级文档状态

### Phase E：发布后闭环（推荐）

发布完成后，必须执行发布后闭环：
- `ship-workflow-canary` — 金丝雀监控，curl 关键端点比对基线
- `ship-workflow-land` — 合并 PR、等 CI、验证生产环境
- `ship-workflow-doc-sync` — 交叉引用变更，同步更新过时文档

分阶段上线策略、Feature Flag 生命周期和推进/回滚阈值详见 `ship-infrastructure-deploy`。

## 好/坏示例

### 好示例：结构化 Go/No-Go + 回滚计划

```
## Go/No-Go — 任务管理 v2.3
- [x] 阻塞项：无未解决 Critical
- [x] 已知风险：旧版 API 兼容窗口 48h，已准备 fallback 路由
- [x] 回滚计划：feature flag 关闭 < 1min；git revert + redeploy < 5min
- [x] Staging 全绿，冒烟测试通过
- 决策：GO
```

优点：每项可验证、回滚时间量化、风险显式记录。

### 坏示例："发了吧"

```
代码能跑了，周五之前上线吧。出问题再修。
```

问题：无回滚计划、无 staging 验证、无监控确认、无 Go/No-Go 决策记录。上线后故障无法快速回退。

## 输出模板

模板起点：
- `templates/feature/05-ship.md`
- `templates/feature/README.md`（聚合 README）

```markdown
# Ship Report — <feature-name>

## 基本信息
- artifact_type: software / document / article / deck / visual
- 版本: <version>
- 发布时间: YYYY-MM-DD HH:MM

## Delivery Scope
- Deliverables:
- Commit / version / artifact path:
- Target users / audience:
- Explicitly out of scope:

## Review Carryover
- Review verdict:
- Blocking remaining:
- Important / deferred risks:
- Review conditions:

## Pre-ship Evidence
| Check | Command / Evidence | Result | Owner |
|-------|--------------------|--------|-------|

## Ship Audit Results
| Audit | Required | Auditor | Result | Blocking findings | Accepted risks |
|-------|----------|---------|--------|-------------------|----------------|

## Final Verification
- software staging:
- smoke / integration verification:
- migration / data compatibility:
- feature flag / kill switch:
- artifact export verification:
- final file / delivery package path:

## Go / No-Go Decision
| Criterion | Required | Status | Evidence |
|-----------|----------|--------|----------|
- Decision: GO / NO-GO
- Decision owner:
- Decision time:

## Rollback / Recovery Plan
- Trigger conditions:
- Recovery steps:
- Data handling:
- Expected recovery time:
- Owner:
- Non-software replacement / re-export plan:

## Documentation Sync
- Updated project docs: [paths or none]
- Deferred project docs: [paths + reasons or none]
- CHANGELOG.md updated: yes / no / n/a
- README verified: yes / no / n/a

## Post-ship Monitoring
- Observation window:
- Health checks / metrics:
- Alert thresholds:
- Monitoring owner:
- First check time:

## Handoff / Archive
- Final artifact / release path:
- Release notes / changelog path:
- Archived evidence path:
- Next command: canary / land / doc-sync / export
- Owner:
```

聚合 README 必须使用 `templates/feature/README.md`，并至少保留：
- `Feature Summary`
- `Document Index`
- `Timeline`
- `Key Decisions`
- `Delivery Outcome`
- `Verification Evidence`
- `Residual Risks`
- `Follow-up Actions`
- `Retro Notes`

## 监控与可观测性

### 应用级指标
```
├── 错误率（总数 + 按端点）
├── 响应时间（p50 / p95 / p99）
├── 请求量
├── 活跃用户
└── 关键业务指标（转化率、参与度）
```

### 上线后验证


上线后 1 小时内：
1. 健康检查 200
2. 错误监控仪表盘（无新错误类型）
3. 延迟仪表盘（无回归）
4. 手动测试关键用户流程
5. 确认日志正常流动
6. 确认回滚机制就绪

## 验证失败处理

| 失败场景 | 处理方式 |
|---------|---------|
| Staging 测试失败 | 阻塞。修复后重新部署 staging，不可跳过直接上线 |
| Go/No-Go 被否决 | 回到对应阶段修复（review / build），重新走预发检查 |
| 上线后错误率飙升 | 立即回滚（禁用 feature flag 或 revert），不"观察一下" |
| Feature flag 未就绪 | 阻塞。不上线。在 staging 验证 flag 开关功能正常 |
| DB migration 向前不兼容 | 阻塞。修复 migration 使其向前兼容，或拆分为两阶段部署 |
| 回滚计划不完整 | 阻塞。必须补全触发条件和步骤后才可上线 |

## 验证证据

输出或记录必须包含：
- **输入/来源**: 读取的 spec、plan、代码、反馈或发布上下文。
- **执行动作**: 实际完成的检查、生成、修复、导出或发布步骤。
- **验证结果**: 命令、审查结论、产物路径、截图或人工确认。
- **阻塞/回退**: 未通过项、回退路径或需要 human partner 决策的问题。

## 常见说辞

| 说辞 | 现实 | 后果 |
|------|------|------|
| "周五下午了，发了吧" | 周五不发版。 | 周五上线后周末无人监控，故障持续到周一才被发现，用户受影响时间 48-72 小时。 |
| "不需要 feature flag" | 每个功能都需要 kill switch。 | 没有 kill switch 的功能出问题时只能重部署回滚，回滚时间从 < 1 分钟（关 flag）膨胀到 15-30 分钟（revert + 重新部署）。 |
| "监控是额外的成本" | 没有监控意味着从用户投诉而不是仪表盘发现故障。 | 从用户投诉到定位问题平均 2-4 小时；有监控从仪表盘发现到定位平均 5 分钟。MTTR 差距 24-48x。 |
| "回滚就是承认失败" | 回滚是负责任的工程。发布有问题的功能才是失败。 | 拒绝回滚 = 让所有用户持续受损。每多 1 分钟犹豫，多 1 分钟用户流失。故障持续时间与用户信任损失正相关。 |

**违反字面规则就是违反精神。** 没有灰色地带。

## 红旗

<HARD-GATE>
以下任何一个出现，立即停止发布：

- 没有回滚计划就部署
- 没有监控或错误报告就上线
- 大爆炸式发布（一次性全量，没有 staging）
- Feature flag 没有 owner 或过期时间
- 上线后第一小时无人监控
- 生产环境配置靠记忆而不是代码
- "周五下午了，发了吧"
</HARD-GATE>

## 验证清单

上线前：
- [ ] 预发检查清单完成（全部绿色）
- [ ] Delivery Scope 已写清交付物、目标环境和不做范围
- [ ] Review Carryover 已带入 `04-review.md` verdict、条件和残余风险
- [ ] Pre-ship Evidence 已记录命令、路径、结果和 owner
- [ ] Go/No-Go Decision 已记录 criterion、evidence、owner 和时间
- [ ] Feature flag 已配置（如适用）
- [ ] Rollback / Recovery Plan 已文档化，包含触发条件、步骤、数据处理和 owner
- [ ] Documentation Sync 已完成；必须同步的 project docs 状态明确
- [ ] Post-ship Monitoring 已写清观察窗口、指标、阈值和 owner
- [ ] Handoff / Archive 已写清最终路径和下一命令
- [ ] 聚合 README 已覆盖 `00-brainstorm.md` 到 `07-deploy-report.md` 的证据状态
- [ ] 聚合 README 已写清剩余风险、后续动作、owner 和 tracking
- [ ] 团队已通知上线

上线后：
- [ ] 健康检查 200
- [ ] 错误率正常
- [ ] 延迟正常
- [ ] 关键用户流程工作
- [ ] 日志正常流动