workflow-ship-faster

工作流：更快交付（Next.js 16.1.1）

此工作流的目标是：以最短时间将一个想法或小型原型打磨到可投入生产的状态，同时保持后续的迭代速度。

适用场景

当用户希望使用端到端工作流，例如： -“交付这个 MVP”“让它达到可投入生产的状态”“发布／部署这个项目” -“把这个原型改造成真正的应用” -“搭建基础架构 + UI 系统 + 部署流程”

核心原则（不可妥协）

• 只传递路径，不传递内容：Agent／子 Agent 只传递 ..._path。
• 文件是重要组成部分：每个步骤都必须持久化产物；失败后可以重试；可以重放。
• 确认节点：任何“高风险／高投入／有副作用”的操作都必须先写出计划并等待确认。
• 计划就是检查清单：通过 tasks.md 中的 - [ ] → - [x] 跟踪进度（而不是在聊天中跟踪）。
• 渐进式披露：仅在需要时打开此技能目录中的步骤文件（foundation.md、deploy-vercel.md 等），避免一次性加载所有细节。
• Hooks doctor（必需检查；非阻塞）：如果运行环境是 Claude Code，且你希望启用演进循环，请在会话开始时运行一次 tool-hooks-doctor；如果缺少 hooks，请提出安装项目级 hooks（无论如何都继续）。

输入／输出（仅路径）

输入（仅路径）：

• repo_root：项目根目录（默认值为 "."）
• 可选：run_dir（活动运行目录），如果用户已有

输出（产物，写入 run_dir/ 下）：

• 必需：proposal.md、tasks.md、context.json
• 可选：design.md、evidence/、logs/

规范约定（后端、模板、读取顺序、自动归档）：

• references/artifact-contract.md
• 参考索引：references/README.md

步骤模块（仅在进入相应步骤时打开）

• 基础架构：foundation.md
• 防护措施：guardrails.md
• 跟踪信息清理：cleanup-traces.md
• 文档基线：docs-baseline.md
• Supabase 集成：supabase-integration.md
• Stripe 集成：stripe-integration.md
• 部署（GitHub + Vercel）：deploy-vercel.md
• AI 时代的 SEO（Next.js）：ai-seo-nextjs.md

流程（默认路线）

0）初始化运行（必需）

1. 确定／创建 run_dir/（参见 references/artifact-contract.md 中的确定性后端规则）。
2. 确保核心产物存在（缺少时创建；已存在时合并／追加）：
   • proposal.md、tasks.md、context.json
3. 在 tasks.md 中确保：
   • 顶部附近有 status: active|blocked|done 字段
   • 有一个简短的 下一步操作 部分（1–3 项）
   • 有一个 审批 部分（需要前可以留空）
4. 仅在确实有较大输出需要保存时，才创建 evidence/ 和 logs/。

0.2）范围确认（必需）

解决的问题：运行摘要将核心步骤标记为“已跳过”，但用户从未选择跳过这些步骤，这会造成误导，也难以审计。

在执行构建检查以外的步骤之前，请用户选择范围：

• A）full（默认）：Foundation → Design system → UI/UX → Guardrails → Docs → Feature iteration → Deploy
• B）deploy-only：Foundation（构建 + 基本检查）→ 仅 Deploy（不进行 UI 工作，也不完善 guardrails/docs）
• C）design-only：仅 Design system + UI/UX 计划（不更改代码）
• D）feature-only：一次 Feature iteration（计划 + 实施），跳过 Deploy

规则：

• 将所选范围保存到 context.json（添加或更新 scope 字段）。
• 在 tasks.md 中，除非用户明确要求跳过，否则不要将默认步骤标记为“已跳过”。
  • 建议：在“Scope / Disabled steps”部分中使用 disabled (scope=...)，并附上简短原因
• 任何破坏性操作（例如覆盖现有仓库的强制推送）都是高风险副作用：
  • 先在 tasks.md 中写入一项可执行的审批事项
  • 等待用户明确确认后再执行

0.25）启动澄清（轻量头脑风暴）（建议；目标模糊时必需）

解决的问题：人们直接着手“实现一个功能”，最终做出的 MVP 非常基础，难以演示。

如果符合以下任意一项，请执行此步骤：

• proposal.md 缺少明确的验收标准和非目标
• 用户请求“构建一个类似 X 的东西”或“制作一个原型”，但未说明核心循环
• 用户明确希望制作一个“可直接演示”的原型（动画、令人惊艳的效果、便于分享）

操作方法：

• 使用相同的 repo_root + 此 run_dir 调用 workflow-brainstorm。
• 遵循每次只问一个问题的规则，并明确以下内容：
  • 一个核心循环（一句话）
  • 验收标准（3–5 条）
  • 非目标（1–3 条）
  • 约束（时间线 / 风险偏好）
  • “演示时刻”的设计方向（参见步骤 0.3）
• 将已确认的规格保存到：
  • evidence/YYYY-MM-DD-kickoff-design.md
• 然后更新（合并，不要覆盖）以下输入：
  • proposal.md
  • context.json（确保明确设置 need_database/need_billing/need_deploy/need_seo）

0.3）优先打造演示时刻（建议用于原型）

原则：一个感觉真实的原型，至少需要一个“演示时刻”（恰到好处地吸睛，而非华而不实）。

“演示时刻”的示例（任选 1 个，保持精简）：

• 一个带有实时交互式预览的主视觉区（可以使用模拟数据）+ 流畅且有目的性的动效
• 令人愉悦的微交互：命令面板、可拖动卡片、时间线滑块等
• 一个“前后对比”变换动画（输入 → 输出），让核心循环一目了然

工作流：

1. 编写一个小型功能规格文件（如果文件不存在）：
   • evidence/feature-00-demo-moment.md
   • 包含 mode: plan-only、feature_slug: demo-moment 和 quality_bar: demo-ready
2. 调用 workflow-feature-shipper，仅生成计划（暂不实施）。
3. 将实际 UI 实施推迟到步骤 2 之后（即 design-system.md 已存在之后），这样演示时刻才能遵循所选的设计系统。

0.5）动态分支决策（必需）

根据 context.json 的内容动态调整执行顺序：

• 数据库集成：仅当 context.json 中存在 "need_database": true 时执行
• 支付集成：仅当 context.json 中存在 "need_billing": true 或 "need_stripe": true 时执行
• 身份验证：仅当 context.json 中存在 "need_auth": true 或 "auth": true 时执行
• 部署：仅当 context.json 中存在 "need_deploy": true，或用户明确要求部署时执行
• SEO：仅当 context.json 中存在 "need_seo": true，或项目已上线时执行

开始每个可选步骤前：

• 检查 context.json（以及你选择的 scope），以判断该步骤是否适用
• 如果跳过，在 tasks.md 中写明 1 行原因（这样恢复任务或审计时无需查阅聊天记录）

1）基础：Next.js 基础（默认必需）

打开并遵循：foundation.md。

产物要求（最低要求）：

• evidence/foundation.md（当前状态 + 风险评估 + 选定方案）
• tasks.md：添加一个 Foundation 检查清单部分（任务 + 验证命令）
• 如果升级/迁移需要进行重大变更：在 tasks.md 中添加一个 Approval 项，并等待确认

分支规则（重要）：

• 如果结论是 keep-current-stack（例如 Vite 静态网站），不要强行继续执行“Next.js 专属步骤”。
  • 仅继续执行仍适用于当前技术栈的步骤：样式（2）、护栏（3，按当前技术栈调整）、文档（4）、部署（8，可选）、SEO（9，可选）
  • 如果仍需要数据库/支付集成：先询问用户“想迁移到 Next.js 吗？”，或为该技术栈添加集成步骤（不在此工作流链的默认范围内）

2）样式规范（默认必需）

调用 tool-design-style-selector：扫描项目意图并持久化 design-system.md。

确认节点：用户确认样式后，部署 design-system.md，并进入 2.5 UI/UX 实施（默认必需；如果用户明确跳过，记录原因）。

2.5）UI/UX 实施（默认必需）

目标：确保 design-system.md 真正体现在界面中，而不是“写了规范但 UI 没变”。

推荐做法：将“根据 design-system.md 重做 UI/UX”视为一项独立功能，并交给 workflow-feature-shipper：

• 输入：design-system.md（作为唯一设计约束）+ 当前 UI 页面列表（通过代码扫描获取）
• 输出：evidence/features/<feature_slug>-plan.md（范围/验收标准/非目标/风险/回滚）+ 代码变更

默认增强（已安装时）：

• 如果已安装 tool-ui-ux-pro-max，使用它为 UI/UX 计划补充具体的配色方案/排版/UX 护栏，并将其交付前检查清单用作验收标准。
• 仅当用户明确要求跳过时（例如“不要过度设计 / 保持简单”），才跳过 tool-ui-ux-pro-max 增强，并记录原因。

对于大规模重构：先在 tasks.md 中添加一个 Approval 项，并等待用户确认后再实施。

3）代码规范（轻量必需）

打开并遵循：guardrails.md。

产物：tasks.md（Guardrails 检查清单部分）

3.5）痕迹清理（去品牌化与源代码卫生）（项目为复制而来时必需）

要解决的问题：许多从 Google AI Studio / v0 / Lovable 导入的入门项目都带有供应商品牌、损坏的残留内容（如 importmap）以及误导性的 README 说明。

打开并遵循：cleanup-traces.md。

产物：

• evidence/trace-scan.md
• tasks.md（Trace cleanup 检查清单部分）

4）文档规范（轻量必需）

打开并遵循：docs-baseline.md。

产物：tasks.md（Docs 检查清单部分，以及项目 README 更新）

5) 核心功能开发（迭代循环）

调用 workflow-feature-shipper：

• 每项功能都先生成 evidence/features/<feature_slug>-plan.md（包含验收标准和非目标）
• 默认拆分为可单独提交 PR 的小步骤
• 每批完成后（或合并前），建议调用 review-quality 进行最终审查并给出结论
• review-quality 是唯一入口，会自动分类处理：如果检测到 React/Next.js 性能风险，还会运行 review-react-best-practices（优先处理 CRITICAL 规则）

身份验证说明（可选）：如果功能涉及登录/会话/权限，且已安装 tool-better-auth，请在实施前调用它，以明确会话策略、重定向、Cookie/CSRF 和中间件边界。保存：

• evidence/auth-plan.md
• evidence/auth-summary.md

6) 数据库集成（可选）

执行条件：context.json 中 "need_database": true 或 "database": "supabase"

打开并遵循：supabase-integration.md。

7) 支付集成（可选）

执行条件：context.json 中 "need_billing": true 或 "need_stripe": true 或 "payment": true

打开并遵循：stripe-integration.md。

8) GitHub + Vercel 部署（可选但推荐）

执行条件：context.json 中 "need_deploy": true，或存在非空的 "deploy_target" 字段

打开并遵循：deploy-vercel.md。

9) AI 时代的 SEO（可选但推荐）

执行条件：context.json 中 "need_seo": true 或 "seo": true，或第 8 步已成功完成（已部署）

打开并遵循：ai-seo-nextjs.md。

最终交付

写入：final.md（位于运行根目录），至少包含：

• 当前项目状态（能否在本地运行、能否构建、是否已部署）
• 已完成的步骤和产物路径
• 后续步骤（按价值排序）

并完成收尾工作：

• 将 tasks.md 中的 status 更新为 done，并填写 Delivery summary
• 每批完成后（以及最后）运行自动归档：
  • python3 ~/.claude/skills/workflow-ship-faster/scripts/auto_archive.py --run-dir "<run_dir>"
• 如果希望保持工作区整洁（不使用自动归档）：将 active/<run_id>/ 移至 archive/YYYY-MM-DD-<run_id>/
• 执行一次 skill-evolution Evolution checkpoint（3 个问题）；如果用户选择“想要优化”，则基于此 run_dir 运行 skill-improver，生成最小化补丁建议