规格驱动 AI 开发流水线
把「需求靠聊天传、质量靠肉眼验、回归靠手点」变成「需求进文件、质量进流水线」。核心三句话：
- 写下来的才是流程，能复跑的才是资产。 聊天记录里没有工程，只有巧合。
- AI 产出的上限，是你给它的规格的下限。 花十分钟确认模糊点，胜过返工一周。
- 门禁不是不信任 AI，是让所有人——包括三个月后的自己——都敢放心地快。
何时使用
- 用户要开发新功能，且存在一份 PRD / 需求文档（Word、Markdown 或贴入的文本）。
- 用户抱怨「AI 写的东西和需求对不上」「AI 自测说绿了我不敢信」「改新功能怕弄坏老功能」。
- 用户要搭建 AI 驱动的开发流程：项目指令文件、自定义命令、测试体系、CI 门禁。
- 用户要求「先出规格/契约再写代码」「把验收标准变成测试」「让接口文档不过期」。
快速上手（安装与触发）
安装（一次即可，任何装了 skillhub CLI 的机器）：
skillhub install spec-driven-ai-pipeline
# 或完整坐标：skillhub install @user_ea92b53e/spec-driven-ai-pipeline
触发（两种方式）：
- 自然触发：对话需求符合「何时使用」的场景时，自动按本 skill 的方法执行。
- 显式调用：直接说「用 spec-driven-ai-pipeline 的方法，帮我开发 XX 功能，PRD 在 docs/xxx.md」。
典型对话示例：
> 用户：帮我按 spec-driven-ai-pipeline 走一遍：新功能是自动跟进客户，PRD 在 docs/auto-followup-prd.md
AI 会先产出规格三件套 + 模糊点清单，等确认后才写代码；之后按「执行流程」六步推进，本地 e2e 全绿 + 契约检查通过才算交付。
用户在各阶段做什么：
| 阶段 | AI 做什么 | 用户做什么 |
|---|---|---|
| ① 宪法 | 检查/补齐项目指令文件（CLAUDE.md） | 审一遍行为边界是否合意 |
| ② /spec | 读 PRD → 三件套 + 模糊点清单 | ⭐ 逐条确认模糊点（最关键） |
| ③ 实现 | 按规格写码，决策记入 DECISIONS.md | 模块做完集中审决策日志 |
| ④ /test | 生成场景链 e2e，跑到全绿 | 等结果 |
| ⑤ 防漂移 | openapi:check 对齐代码与契约 | 看报告 |
| ⑥ CI 门禁 | 配置部署前 verify | 之后由机器把关 |
六步流水线总览
| 步骤 | 动作 | 核心产物 | 质量关卡 |
|---|---|---|---|
| 1 | 立项目宪法 | 项目级指令文件（CLAUDE.md / AGENTS.md） | 三层行为边界：自动做 / 记决策 / 必须问 |
| 2 | /spec 命令 |
spec.md + 人读契约 + OpenAPI + 模糊点清单 | 模糊点在动工前全部摊开确认 |
| 3 | 按规格实现 | 业务代码 + DECISIONS.md 决策日志 | 人审「AI 替你做了哪些选择」而非逐行审码 |
| 4 | /test 命令 |
场景链 e2e 测试 | 本地跑到全绿才算完成 |
| 5 | 契约防漂移 | openapi:dump / openapi:check | 文档与代码由机器对齐，杜绝悄悄过期 |
| 6 | CI verify 门禁 | 部署前 单测 + e2e + 契约检查 | 红一次，点击到不了部署 |
每步的详细模板与可直接复制的文件见下方「资源索引」。所有模板均可按本结构照抄进任何项目。
执行流程
第 1 步：给项目立宪法
项目级指令文件（Claude Code 的 CLAUDE.md、Codex 的 AGENTS.md，机制等价）的真正价值不是「描述项目」，而是给 AI 立规矩。含四块：项目概览（含禁止引入项）、关键命令表（每条标注副作用）、硬约束清单、行为边界。
行为边界三层模型（本方法最值钱的部分）：
- 🟢 自动做，别问：读代码、写业务代码、写测试、跑构建/测试/lint、起本地服务排查。
- 🟡 做完记录，集中审：等价方案取舍、PRD 未覆盖的边界场景、命名分层——按最合理方式做，记入
DECISIONS.md，模块做完集中给人过。 - 🔴 必须当场问：改 DB 表结构、动跨模块公共接口、权限/安全、真实对外副作用（发短信/邮件/调付费 AI/推送）、git 写操作。
完整宪法模板见 references/01-constitution.md。效果：AI 的打断从每天几十次降到每模块个位数。
第 2 步：/spec 命令——PRD 翻译成三件套
把一条自定义命令（Claude Code 放 .claude/commands/spec.md，Codex 放等价自定义提示词目录）注册为 /spec，让 AI 把 PRD 翻译成：
docs/specs/<功能>/spec.md—— 工程规格（固定五段：背景与目标 / 数据模型 / 接口定义 / 状态机与流程 / 验收标准 GWT）。docs/api/api-contract-<功能>-v1.md—— 人读接口契约，前端据此并行开发。docs/api/openapi/<功能>-v1.yaml—— 机读契约，前端据此生成类型/客户端/Mock。- 附《模糊点清单》——列出 PRD 未回答的所有问题，每条附「我准备的默认处理」，等人确认后才动工。
模糊点清单是整条流水线最值钱的东西：它把以前藏在 AI 自由发挥里的歧义，全部摊开在人确认之前。这一步消灭的是返工，不是打字量。
完整提示词骨架、编写三要点见 references/02-spec-command.md；可直接落地的命令文件见 assets/claude-commands/spec.md。
第 3 步：按规格实现 + 决策日志
AI 按 spec.md 写码。过程中的小决策（方案取舍、新依赖、边界处理）按固定格式记入 DECISIONS.md（格式见 references/03-decisions-log.md）。带来三样东西：人审「决策」而非逐行审码；半年后知道「当年为什么这么改」；新成员读它等于读半本架构演进史。
第 4 步：/test 命令——验收标准变成场景链 e2e
把 spec ⑤ 的 Given/When/Then 变成一条模拟真实用户完整旅程的场景链（创建 → 合法流转 → 非法流转断言业务错误码 → 按唯一条件查询 → 清理现场），而非「一个接口一个用例」的散点测试。本地跑到全绿才算完成。
命令里必须写死：测试红了，先判断是测试错还是代码错；测试错改测试，代码错报告给人，严禁为了变绿而弱化断言。
完整提示词骨架见 references/04-test-command.md；可直接落地的命令文件见 assets/claude-commands/test.md。
第 5 步：契约防漂移
让机器比对「代码里实际注册的路由」与「设计契约 yaml」：契约有代码没有 → fail；代码有契约没有 → fail。两条命令、几十行脚本，换来接口文档从此不可能悄悄过期。实现思路与各框架等价物见 references/05-contract-drift.md；参考实现（NestJS）见 assets/scripts/dump-openapi.ts 与 assets/scripts/check-openapi-drift.ts。
注意：参考脚本默认检查路由和方法，不等于完整的 schema 兼容性检查。生产项目还应接入 OpenAPI diff、GraphQL schema diff 或对应 IDL 检查，并把破坏性变更设为 CI 失败。
第 6 步：CI verify 门禁
在部署阶段前加 verify：build → 单测 → e2e 全量 → 契约检查 →（全绿才继续）→ deploy。价值是让所有人敢快：AI 大胆改，人大胆合，改坏了门禁会拦。e2e 环境变量必须由 CI Secret 注入，测试库优先按运行隔离；OpenAPI 导出必须关闭定时任务、消息消费和真实外部副作用。配置片段见 references/06-ci-gate.md。
按规模选择落地模式
- Lite：
spec.md + 模糊点确认 + 一条核心场景链 + build/test/lint verify，适合小项目或内部工具。 - Standard：完整六步，适合有数据库和公共 API 的业务服务。
- Strict：Standard + schema/IDL breaking-change 检查 + migration 门禁 + 独立测试环境 + 失败证据归档，适合生产核心链路。
e2e 五条军规（每条背后都是真实翻车）
- 测试数据唯一化：测试数据带本次运行时间戳后缀（
测试客户_${RUN}），否则二次运行必撞唯一约束。 - 断言只锁契约承诺的字段：不锁实现细节，接口正常演进时测试才不会成片死掉。
- e2e 里绝不触发真实副作用：短信/邮件/付费 AI 一律 mock 或 skip。
- 测试进程里禁止定时任务：残留 cron 会真实扫库发邮件，与线上并发造成事故；测试环境强制不注册。
- 禁止全仓自动格式化：一次改动上百文件，diff 全是噪音；格式化单独开分支，AI 自动修复只对本次改动文件跑。
首次落地顺序（不需要一步到位）
- 30 分钟：写宪法——先写「关键命令表（标清副作用）+ 三层行为边界」两节，收益最快。
- 1 小时：把手头最近的 PRD 喂给 AI，产出 spec + 模糊点清单。先不写代码，只回答模糊点。
- 半天：挑一条最核心的业务流程，让 AI 写一条场景链 e2e，按五条军规打磨到「第二天再跑还是绿」。
资源索引
references/（需要时加载的详细模板）
01-constitution.md—— 项目宪法完整骨架 + 三层行为边界示例02-spec-command.md—— /spec 命令编写指南（提示词骨架 + 三要点）03-decisions-log.md—— DECISIONS.md 格式与写法04-test-command.md—— /test 命令编写指南（场景链 + 断言三件套）05-contract-drift.md—— 契约防漂移实现思路与框架等价物06-ci-gate.md—— CI verify 门禁配置片段07-faq.md—— 常见问题、故障排查、非 OpenAPI 项目和 Lite 模式
assets/（可直接复制/参考的文件）
claude-commands/spec.md—— 可直接放进.claude/commands/的 /spec 命令claude-commands/test.md—— 可直接放进.claude/commands/的 /test 命令scripts/dump-openapi.ts—— 契约防漂移「导出代码路由」参考实现（NestJS）scripts/check-openapi-drift.ts—— 契约防漂移「比对契约」参考实现（NestJS）
使用注意
- 不绑定技术栈：Claude Code / Codex / GLM CLI 等机制等价；Spring / FastAPI / NestJS 等框架都有 OpenAPI 导出等价物。
- 对 GraphQL、RPC、CLI、异步任务等非 REST 场景，使用对应 schema/IDL/消息契约替代 OpenAPI，不要为了套模板强行引入 REST。
- 不要替产品拍板业务规则：拿不准的列入模糊点清单或当场问，不猜。
- 命令文件是团队资产、要进 git：每踩一个坑就往对应命令里加一条规则，越用越准。
