workflow-ship-faster

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Workflow: Ship Faster (Next.js 16.1.1)

工作流：快速交付（基于Next.js 16.1.1）

The goal of this chain is: Ship an idea or small prototype to production-ready state in the shortest time, while maintaining iteration speed afterward.

本工作流的目标是：在最短时间内将想法或小型原型转化为可投入生产的状态，同时保障后续的迭代速度。

When to use

适用场景

Use this workflow when the user wants an end-to-end chain like:

“ship this MVP”, “make it production-ready”, “launch/deploy this project”
“take this prototype and turn it into a real app”
“set up the foundation + UI system + deployment”

当用户需要以下端到端工作流时使用：

“交付这个MVP”、“让它具备生产环境就绪状态”、“上线/部署这个项目”
“将这个原型转化为真实可用的应用”
“搭建基础架构 + UI系统 + 部署流程”

Core principles (non-negotiable)

核心原则（不可妥协）

Pass paths only, not content: agents/sub-agents only pass
```
..._path
```
.
Files are first-class citizens: Every step must persist artifacts; failures can be retried; replayable.
Confirmation points: Any "high-risk/high-effort/side-effect" action must write a plan first and wait for confirmation.
Plans are checklists: progress is tracked in
```
tasks.md
```
via
```
- [ ]
```
→
```
- [x]
```
(not in chat).
Progressive disclosure: Only open step files in this skill directory (
```
foundation.md
```
,
```
deploy-vercel.md
```
, etc.) when needed—avoid loading all details at once.
Hooks doctor (required check; non-blocking): If running under Claude Code and you want the evolution loop active, run
```
tool-hooks-doctor
```
once at the start of the session; if hooks are missing, offer to install project-level hooks (continue either way).

仅传递路径，而非内容：Agent/子Agent仅传递
```
..._path
```
类型的路径参数。
文件为一等公民：每个步骤必须持久化产物；失败可重试；流程可回放。
确认节点：任何“高风险/高工作量/有副作用”的操作必须先编写计划，等待用户确认后再执行。
计划即清单：进度在
```
tasks.md
```
中通过
```
- [ ]
```
→
```
- [x]
```
跟踪（而非在对话中）。
渐进式披露：仅在需要时才打开本技能目录下的步骤文件（如
```
foundation.md
```
、
```
deploy-vercel.md
```
等）——避免一次性加载所有细节。
钩子检查器（必填检查；非阻塞）：如果在Claude Code环境下运行且希望启用进化循环，请在会话开始时运行一次
```
tool-hooks-doctor
```
；若钩子缺失，可提供安装项目级钩子的选项（无论是否安装，流程均可继续）。

Inputs / outputs (paths only)

输入/输出（仅路径）

Inputs (paths only):

```
repo_root
```
: project root (default
```
"."
```
)
Optional:
```
run_dir
```
(active run directory) if the user already has one

Outputs (artifacts, written under

run_dir/

Required:
```
proposal.md
```
,
```
tasks.md
```
,
```
context.json
```
Optional:
```
design.md
```
,
```
evidence/
```
,
```
logs/
```

Canonical contract (backends, templates, read order, auto-archive):

references/artifact-contract.md
Reference index: references/README.md

输入（仅路径）：

```
repo_root
```
：项目根目录（默认值为
```
"."
```
）
可选：
```
run_dir
```
（当前运行目录），如果用户已存在该目录

输出（产物，存储在

run_dir/

下）：

必填：
```
proposal.md
```
、
```
tasks.md
```
、
```
context.json
```
可选：
```
design.md
```
、
```
evidence/
```
、
```
logs/
```

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

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

Step modules (open only when you hit that step)

步骤模块（仅在执行对应步骤时打开）

Foundation: foundation.md
Guardrails: guardrails.md
Trace cleanup: cleanup-traces.md
Docs baseline: docs-baseline.md
Supabase integration: supabase-integration.md
Stripe integration: stripe-integration.md
Deploy (GitHub + Vercel): deploy-vercel.md
AI-era SEO (Next.js): ai-seo-nextjs.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

Process (Default Route)

流程（默认路线）

0) Initialize Run (Required)

0) 初始化运行（必填）

Resolve/create
```
run_dir/
```
(see the deterministic backend rules in references/artifact-contract.md).
Ensure core artifacts exist (create if missing; merge/append if already present):
- ```
proposal.md
```
  ,
```
tasks.md
```
  ,
```
context.json
```
In
```
tasks.md
```
, ensure:
- a
```
status: active|blocked|done
```
  field near the top
- a short Next action section (1–3 items)
- an Approvals section (empty is fine until needed)
Only create
```
evidence/
```
and
```
logs/
```
when you actually have large outputs to store.

解析/创建
```
run_dir/
```
（遵循references/artifact-contract.md中的确定性后端规则）。
确保核心产物存在（若缺失则创建；若已存在则合并/追加内容）：
- ```
proposal.md
```
  、
```
tasks.md
```
  、
```
context.json
```
在
```
tasks.md
```
中确保：
- 顶部附近有
```
status: active|blocked|done
```
  字段
- 简短的下一步行动部分（1–3项）
- 审批项部分（为空即可，直到需要时再添加）
仅当有大量输出需要存储时，才创建
```
evidence/
```
和
```
logs/
```
目录。

0.2) Scope Confirmation (Required)

0.2) 范围确认（必填）

Problem this solves: a run summary that marks core steps as “skipped” without the user ever choosing to skip them is misleading and hard to audit.

Ask the user to select a scope before executing steps beyond build checks:

A) full (default): Foundation → Design system → UI/UX → Guardrails → Docs → Feature iteration → Deploy
B) deploy-only: Foundation (build + sanity) → Deploy only (no UI work, no guardrails/docs polish)
C) design-only: Design system + UI/UX plan only (no code changes)
D) feature-only: One feature iteration (plan + implementation), skip deploy

Rules:

Persist the chosen scope to
```
context.json
```
(add/update a
```
scope
```
field).
In
```
tasks.md
```
, do not mark a default step as “skipped” unless the user explicitly requested skipping it.
- Prefer:
```
disabled (scope=...)
```
  with a short reason under a “Scope / Disabled steps” section
Any destructive action (e.g., force push overwriting an existing repo) is a high-risk side effect:
- Write an executable approval item under
```
tasks.md
```
  first
- Wait for explicit user confirmation before executing

解决的问题：若运行摘要在用户未明确选择跳过的情况下标记核心步骤为“已跳过”，会产生误导且难以审计。

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

A) 完整流程（默认）：基础架构 → 设计系统 → UI/UX → 规范约束 → 文档 → 功能迭代 → 部署
B) 仅部署：基础架构（构建 + 健康检查）→ 仅部署（无UI工作，无规范约束/文档优化）
C) 仅设计：仅设计系统 + UI/UX方案（无代码变更）
D) 仅功能：单次功能迭代（方案 + 实现），跳过部署

规则：

将所选范围持久化到
```
context.json
```
中（添加/更新
```
scope
```
字段）。
在
```
tasks.md
```
中，除非用户明确要求跳过，否则不要将默认步骤标记为“已跳过”。
- 推荐写法：在“范围 / 禁用步骤”部分下标注
```
disabled (scope=...)
```
  并附上简短原因
任何破坏性操作（如强制推送覆盖现有仓库）属于高风险副作用：
- 先在
```
tasks.md
```
  中编写可执行的审批项
- 等待用户明确确认后再执行

0.25) Kickoff Clarification (Brainstorm-lite) (Recommended; required if goal is vague)

0.25) 启动前澄清（轻量头脑风暴）（推荐；若目标模糊则必填）

Problem this solves: people jump straight into “implement a feature” and end up with a very basic MVP that’s hard to demo.

Run this step if any of these are true:

```
proposal.md
```
is missing clear acceptance criteria and non-goals
The user request is “build something like X” / “make a prototype” without specifying the core loop
The user explicitly wants a “demo-ready” prototype (animation, wow factor, shareable)

How:

Call
```
workflow-brainstorm
```
using the same
repo_root
+ this
run_dir
.
Follow the one-question-at-a-time rule and converge on:
- the one core loop (1 sentence)
- acceptance criteria (3–5 bullets)
- non-goals (1–3 bullets)
- constraints (timeline / risk preference)
- a “demo moment” direction (see step 0.3)
Persist the confirmed spec to:
- ```
evidence/YYYY-MM-DD-kickoff-design.md
```
Then update (merge, don’t overwrite) these inputs:
- ```
proposal.md
```
- ```
context.json
```
  (ensure
```
need_database/need_billing/need_deploy/need_seo
```
  are explicitly set)

解决的问题：人们常直接进入“实现功能”环节，最终得到的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) Demo Moment First (Recommended for prototypes)

0.3) 优先确定演示亮点（原型推荐）

Principle: a prototype that feels real needs at least one “demo moment” (tastefully showy, not gimmicky).

Examples of “demo moment” (pick 1, keep it small):

A hero section with a live interactive preview (fake data is fine) + smooth, purposeful motion
A delightful micro-interaction: command palette, draggable cards, timeline scrubber, etc.
A “before/after” transformation animation (input → output) that makes the core loop obvious

Workflow:

Write a small feature spec file (if it doesn’t exist):

```
evidence/feature-00-demo-moment.md
```

Include

mode: plan-only

feature_slug: demo-moment

, and

quality_bar: demo-ready

Call
```
workflow-feature-shipper
```
to generate the plan only (no implementation yet).
Defer actual UI implementation until after Step 2 (design-system.md exists), so the demo moment follows the chosen design system.

原则：一个“看起来真实”的原型至少需要一个“演示亮点”（适度吸睛，而非华而不实）。

“演示亮点”示例（选1个，保持轻量化）：

包含实时交互预览（假数据即可）+ 流畅有意义动效的首页区域
令人愉悦的微交互：命令面板、可拖拽卡片、时间轴 scrubber 等
清晰展示核心流程的“前后对比”转换动画（输入 → 输出）

工作流：

编写小型功能规格文件（若不存在）：

```
evidence/feature-00-demo-moment.md
```

包含

mode: plan-only

、

feature_slug: demo-moment

和

quality_bar: demo-ready

调用
```
workflow-feature-shipper
```
仅生成方案（暂不实现）。
推迟实际UI实现至步骤2（design-system.md已生成）之后，确保演示亮点符合选定的设计系统。

0.5) Dynamic Branch Decision (Required)

0.5) 动态分支决策（必填）

Dynamically adjust execution order based on

context.json

content:

Database integration: Only execute when
```
context.json
```
has
```
"need_database": true
```

Payment integration: Only execute when

context.json

has

"need_billing": true

"need_stripe": true

Auth: Only execute when

context.json

has

"need_auth": true

"auth": true

Deployment: Only execute when
```
context.json
```
has
```
"need_deploy": true
```
or user explicitly requests deployment
SEO: Only execute when
```
context.json
```
has
```
"need_seo": true
```
or project is already live

Before starting each optional step:

Check
```
context.json
```
(and your chosen
```
scope
```
) to decide whether the step applies
If skipped, write a 1-line reason into
```
tasks.md
```
(so resume/audit doesn’t require chat history)

根据

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) Foundation: Next.js Foundation (Default Required)

1) 基础架构：Next.js基础（默认必填）

Open and follow: foundation.md.

Artifact requirements (minimum):

```
evidence/foundation.md
```
(current state + risk assessment + chosen route)
```
tasks.md
```
: add a Foundation checklist section (tasks + verification commands)
If upgrade/migration needed with significant changes: add an Approval item to
```
tasks.md
```
and wait for confirmation

Branch rules (important):

If conclusion is keep-current-stack (e.g., Vite static site), don't force continuing "Next.js-specific steps".
- Only continue steps that still apply to current stack: style (2), guardrails (3, adapted for current stack), docs (4), deploy (8 optional), SEO (9 optional)
- If DB/payment integration still needed: First ask user "want to migrate to Next.js?", or add integration step for that stack (not in this chain's default scope)

打开并遵循：foundation.md。

产物要求（最低标准）：

```
evidence/foundation.md
```
（当前状态 + 风险评估 + 选定路线）
```
tasks.md
```
：添加基础架构清单部分（任务 + 验证命令）
若需要进行有重大变更的升级/迁移：在
```
tasks.md
```
中添加审批项并等待用户确认

分支规则（重要）：

若结论为保留当前技术栈（如Vite静态站点），请勿强制继续"Next.js专属步骤"。
- 仅继续适用于当前技术栈的步骤：样式（2）、规范约束（3，适配当前技术栈）、文档（4）、部署（8可选）、SEO（9可选）
- 若仍需数据库/支付集成：先询问用户"是否要迁移到Next.js？"，或为当前技术栈添加集成步骤（不在本工作流的默认范围内）

2) Style Specification (Default Required)

2) 样式规范（默认必填）

Call

tool-design-style-selector

: Scan project intent and persist

design-system.md

Confirmation point: After user confirms style, deploy

design-system.md

, and enter 2.5 UI/UX Implementation (default required; if user explicitly skips, log reason).

调用

tool-design-style-selector

：扫描项目意图并持久化

design-system.md

。

确认节点：用户确认样式后，部署

design-system.md

，然后进入2.5 UI/UX实现（默认必填；若用户明确跳过，请记录原因）。

2.5) UI/UX Implementation (Default Required)

2.5) UI/UX实现（默认必填）

Goal: Make

design-system.md

actually reflected in the interface, not "wrote spec but UI unchanged".

Recommended approach: Treat "redo UI/UX per design-system.md" as an independent feature and hand to

workflow-feature-shipper

Input:
```
design-system.md
```
(as sole design constraint) + current UI page list (from code scan)
Output:
```
evidence/features/<feature_slug>-plan.md
```
(scope/acceptance criteria/non-goals/risks/rollback) + code changes

Default enrichment (when installed):

If
```
tool-ui-ux-pro-max
```
is installed, use it to enrich the UI/UX plan with concrete palette/typography/UX guardrails, and use its pre-delivery checklist as acceptance criteria.
Only skip
```
tool-ui-ux-pro-max
```
enrichment if the user explicitly asks to skip it (e.g., “don’t over-design / keep it simple”), and log the reason.

For large-scale refactoring: add an Approval item to

tasks.md

first and wait for user confirmation before implementing.

目标：确保

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

中添加审批项，等待用户确认后再实现。

3) Code Standards (Lightweight Required)

3) 代码规范（轻量必填）

Open and follow: guardrails.md.

Artifact:

tasks.md

(Guardrails checklist section)

打开并遵循：guardrails.md。

产物：

tasks.md

（规范约束清单部分）

3.5) Trace Cleanup (De-branding & Source Hygiene) (Required if project was copied)

3.5) 痕迹清理（去品牌化 & 源码卫生）（若项目为复制而来则必填）

Problem this solves: many starter projects imported from Google AI Studio / v0 / Lovable ship with vendor branding, broken remnants (like

importmap

), and misleading README instructions.

Open and follow: cleanup-traces.md.

Artifacts:

```
evidence/trace-scan.md
```
```
tasks.md
```
(Trace cleanup checklist section)

解决的问题：许多从Google AI Studio / v0 / Lovable导入的启动项目带有厂商品牌、残留代码（如

importmap

）和误导性的README说明。

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

产物：

```
evidence/trace-scan.md
```
```
tasks.md
```
（痕迹清理清单部分）

4) Documentation Standards (Lightweight Required)

4) 文档规范（轻量必填）

Open and follow: docs-baseline.md.

Artifact:

tasks.md

(Docs checklist section, plus project README update)

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

产物：

tasks.md

（文档清单部分，以及项目README更新）

5) Core Feature Development (Iterative Loop)

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

Call

workflow-feature-shipper

Each feature first produces
```
evidence/features/<feature_slug>-plan.md
```
(with acceptance criteria/non-goals)
Default split into PR-able small steps
After each batch (or before merge), recommend calling
```
review-quality
```
for a conclusive review + verdict
```
review-quality
```
is the single entry point and will auto-triage: if React/Next.js performance risk is detected, it will also run
```
review-react-best-practices
```
(CRITICAL rules first)

Auth note (optional): if a feature includes login/session/permissions and

tool-better-auth

is installed, call it before implementation to lock down session strategy, redirects, cookies/CSRF, and middleware boundaries. Persist:

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

调用

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) Database Integration (Optional)

6) 数据库集成（可选）

Execution condition:

context.json

has

"need_database": true

"database": "supabase"

Open and follow: supabase-integration.md.

执行条件：

context.json

包含

"need_database": true

或

"database": "supabase"

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

7) Payment Integration (Optional)

7) 支付集成（可选）

Execution condition:

context.json

has

"need_billing": true

"need_stripe": true

"payment": true

Open and follow: stripe-integration.md.

执行条件：

context.json

包含

"need_billing": true

或

"need_stripe": true

或

"payment": true

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

8) GitHub + Vercel Deployment (Optional but Recommended)

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

Execution condition:

context.json

has

"need_deploy": true

"deploy_target"

field exists and non-empty

Open and follow: deploy-vercel.md.

执行条件：

context.json

包含

"need_deploy": true

或存在非空的

"deploy_target"

字段

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

9) AI-Era SEO (Optional but Recommended)

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

Execution condition:

context.json

has

"need_seo": true

"seo": true

, or step 8 completed successfully (already deployed)

Open and follow: ai-seo-nextjs.md.

执行条件：

context.json

包含

"need_seo": true

或

"seo": true

，或步骤8已成功完成（已部署）

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

Final Delivery

最终交付

Write to:

final.md

(in the run root), at minimum include:

Current project status (can run locally, can build, is deployed)
Completed steps and artifact paths
Next steps (prioritized by value)

And wrap up:

Update
```
tasks.md
```
```
status
```
to
```
done
```
, and fill the Delivery summary

Run auto-archive after each batch (and at the end):

python3 ~/.claude/skills/workflow-ship-faster/scripts/auto_archive.py --run-dir "<run_dir>"

If you want a clean workspace (without auto-archive): move
```
active/<run_id>/
```
→
```
archive/YYYY-MM-DD-<run_id>/
```
Do a
```
skill-evolution
```
Evolution checkpoint (3 questions); if user chooses "want to optimize", run
```
skill-improver
```
based on this
```
run_dir
```
to produce minimal patch suggestions

写入至：

final.md

（运行根目录下），至少包含：

当前项目状态（可本地运行、可构建、已部署）
已完成步骤和产物路径
下一步计划（按价值优先级排序）

收尾工作：

将
```
tasks.md
```
中的
```
status
```
更新为
```
done
```
，并填写交付摘要

每完成一批任务后（以及最终）运行自动归档：

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
```
进化检查点（3个问题）；若用户选择“需要优化”，基于当前
```
run_dir
```
运行
```
skill-improver
```
以生成最小化补丁建议",