Shipcheck（交付体检）

Shipcheck 是一套给 Vibe Coding / AI 辅助开发项目使用的交付流程 Skill。

它不是代码生成器，也不是项目管理软件的替代品。它更像一个“项目进度账本 + 阶段闸门检查器”：当你用 Trae、Codex 或其他 AI 工具做真实项目时，它负责把每一步做过什么、改过什么、交付了什么、还有什么没做完记录下来，并在进入下一阶段前提醒你哪些动作还没有完成。

它解决什么问题

很多 AI 项目失败，不是因为第一版做不出来，而是因为第一版之后没有流程：

• 需求没有确认清楚，就开始写页面。
• 页面看起来能跑，但后端、数据库、权限没有检查。
• 联调通过了，却没有单独测试。
• 客户说“差不多”，但没有验收记录。
• 项目上线了，却没有版本、提交、部署和复盘记录。

Shipcheck 的作用是把这些容易被忽略的过程显性化。它会把一个项目拆成固定阶段，每个阶段都有输入、过程、返工、产出、风险、下一步和 GO / NO-GO 判断。

它在项目中起到的作用

在一个真实项目里，Shipcheck 主要承担 4 个角色：

1. 需求翻译器：把客户的一句话需求，拆成目标用户、业务目标、页面结构、功能范围、数据对象和验收标准。
2. 项目进度账本：每次完成页面、接口、数据库、测试、部署、客户反馈等动作后，都留下记录，避免项目只存在聊天记录里。
3. 阶段闸门检查器：每次准备进入下一阶段时，检查上一阶段是否真的完成。没完成就提醒用户，不允许默认往下推进。
4. 交付复盘素材库：项目结束后，project-delivery/ 里会沉淀一套可交接、可复盘、可复用的 Markdown 文档。

适合谁使用

• 想用 AI 做项目的非程序员、产品经理、运营、设计师。
• 用 Trae / Codex 做客户项目、内部工具、H5、小程序、网站、后台系统的人。
• 想把 Vibe Coding 从“试试看”变成“能交付”的人。
• 需要把 AI 项目过程记录下来，方便交接、验收、复盘、二次开发的人。

核心工作方式

Shipcheck 会在项目根目录创建一个 project-delivery/ 文件夹。

这个文件夹就是项目交付记录的唯一来源。不要只依赖聊天上下文，也不要只依赖 AI 的记忆。

project-delivery/
├── 00_项目总览.md
├── 00_项目启动问答.md
├── 00_技术方案推荐.md
├── 01_需求分析.md
├── 02_项目拆解.md
├── 03_前端检查.md
├── 04_后端检查.md
├── 05_数据库检查.md
├── 06_联调.md
├── 07_测试记录.md
├── 08_客户验收.md
├── 09_上线准备.md
├── 10_复盘沉淀.md
├── change-log.md
├── progress-log.md
└── turn-checkpoints.md

标准阶段

阶段	文件	作用
00	00_项目启动问答.md / 00_技术方案推荐.md	确认项目画像、技术路线、风险假设
01	01_需求分析.md	明确用户、场景、功能、边界、验收标准
02	02_项目拆解.md	拆页面、模块、接口、数据表、任务顺序
03	03_前端检查.md	检查页面、交互、响应式、空状态、错误状态
04	04_后端检查.md	检查接口、权限、业务逻辑、异常处理
05	05_数据库检查.md	检查表结构、字段、数据关系、备份和迁移
06	06_联调.md	确认前端、后端、数据库真实跑通
07	07_测试记录.md	单独记录功能、边界、权限、移动端、异常、回归测试
08	08_客户验收.md	记录客户反馈、修改清单、验收结论
09	09_上线准备.md	记录环境变量、域名、备案、部署、回滚方案
10	10_复盘沉淀.md	总结踩坑、流程、模板、可复用经验

最重要的两条规则

1. 做完任何事情，都要记录

每次完成一个动作，都应该留下记录。动作可以很小，比如：

• 改了一个页面布局。
• 补了一个表单校验。
• 新增一个接口。
• 调整数据库字段。
• 修复一个移动端问题。
• 跑完一轮测试。
• 客户提出一条修改意见。
• 提交一个 Git commit。
• 准备一个上线版本。

普通进展记录到 progress-log.md。

代码、文件、版本、部署、Git 提交记录到 change-log.md。

10/20 轮这种长对话检查记录到 turn-checkpoints.md。

2. 每次进入新阶段前，都要提醒用户没完成的动作

Shipcheck 默认使用严格闸门：

• 需求不清，不进入项目拆解。
• 项目拆解不清，不进入前后端实现。
• 前端、后端、数据库未检查，不进入联调。
• 联调未通过，不进入测试。
• 测试未通过，不进入客户验收。
• 客户验收未通过，不进入上线。
• 上线没有记录，不进入复盘。
• 复盘没有沉淀，不算交付完成。

当用户说“下一步”“继续”“可以进入下一阶段”时，Agent 应该先运行阶段检查。如果检查结果是 NO-GO，就要明确提醒：

当前还不能进入下一阶段，因为：
1. xxx 还没有记录
2. xxx 还没有验证
3. xxx 还没有 GO 判断

建议先完成这 3 个动作：
1. ...
2. ...
3. ...

安装到 Codex

克隆仓库后执行：

bash install.sh

安装后在 Codex 里使用：

使用 $shipcheck 帮我初始化一个项目交付流程：婚庆案例小程序

在 Trae 使用

Trae 不一定直接读取 Codex Skill 格式。推荐做法：

1. 打开 agents/trae.md
2. 复制里面的规则到 Trae 项目规则、自定义指令或项目说明里
3. 让 Trae 在项目根目录维护 project-delivery/

你可以对 Trae 说：

按照 Shipcheck 交付体检流程，帮我启动这个项目。先不要写代码，先做项目启动问答和技术方案推荐。

初始化项目

python3 scripts/init_delivery_project.py --name "婚庆案例小程序" --output /path/to/project

这会创建：

/path/to/project/project-delivery/

如果目标目录已经存在，脚本会拒绝覆盖，避免把已有交付记录删掉。

检查当前阶段

python3 scripts/check_delivery_stage.py --path /path/to/project/project-delivery

输出会告诉你：

• 当前处于哪个阶段
• 当前阶段完成度
• 是否 GO / NO-GO
• 还缺哪些记录
• 下一步 3 个动作
• 应该追加到 progress-log.md 的日志块

记录普通进展

python3 scripts/record_delivery_event.py \
  --path /path/to/project/project-delivery \
  --type progress \
  --phase "03_前端检查" \
  --summary "完成首页首屏和案例列表的移动端适配" \
  --files "src/pages/Home.tsx" \
  --risk "底部咨询按钮在小屏手机上还需要复查" \
  --go NO-GO \
  --next "补齐小屏手机截图并复测"

记录代码或文件改动

python3 scripts/record_delivery_event.py \
  --path /path/to/project/project-delivery \
  --type change \
  --phase "04_后端检查" \
  --summary "新增咨询表单提交接口" \
  --files "src/api/leads.ts" \
  --decision "需要增加手机号格式校验" \
  --go NO-GO \
  --next "补充接口异常态测试"

记录版本或 Git 提交

python3 scripts/record_delivery_event.py \
  --path /path/to/project/project-delivery \
  --type version \
  --phase "09_上线准备" \
  --summary "提交候选版本" \
  --branch "main" \
  --commit "abc1234" \
  --version "v0.1.0" \
  --go GO \
  --next "客户验收后打正式 tag"

推荐使用节奏

项目开始时

1. 用 Shipcheck 初始化 project-delivery/
2. 完成 00_项目启动问答.md
3. 完成 00_技术方案推荐.md
4. 运行阶段检查
5. GO 后再进入需求分析

每次完成一个动作后

1. 判断这次动作属于 progress、change、decision、version 还是 checkpoint
2. 调用 record_delivery_event.py 记录
3. 更新对应阶段文档
4. 如果用户想进入下一阶段，先运行 check_delivery_stage.py

每次阶段切换前

1. 运行阶段检查
2. 如果 NO-GO，先列出未完成动作
3. 补齐记录、测试或验收证据
4. 重新检查
5. GO 后再进入下一阶段

常见使用场景

场景 1：非程序员做第一个 AI 项目

用户只有一句话需求：

我朋友是做婚庆的，想做一个案例展示 H5。

Shipcheck 会先引导用户补齐：

• 给谁看
• 看完要做什么
• 要展示哪些内容
• 是否需要后台
• 是否需要数据库
• 是否需要收集咨询线索
• 最小可交付版本是什么

场景 2：AI 已经做出第一版，但不知道还能不能交付

运行阶段检查：

python3 scripts/check_delivery_stage.py --path ./project-delivery

如果前端完成但后端、数据库、测试没记录，Shipcheck 会给出 NO-GO，并提示不能直接进入客户验收。

场景 3：客户一直改需求

每次客户反馈都记录到 progress-log.md 或 change-log.md，最后复盘时可以看清楚：

• 哪些是原始需求
• 哪些是新增需求
• 哪些是返工
• 哪些是范围变化
• 哪些影响了上线时间

对外介绍一句话

Shipcheck 是一套给 Vibe Coding 项目用的“交付体检”流程。它帮助你把 AI 做出来的第一版，继续推进到能检查、能验收、能上线、能复盘的真实交付状态。