Vibe Coding 防翻车工作流
这个 Skill 解决什么
用 AI 做东西，典型翻车路径是一样的：需求没说清就开始写 → 越写越发散 → 改一处坏三处 → AI 来回猜 → 最后推倒重来。
这个 Skill 不教写代码，它在每一步设一道闸：没想清楚不许动手、改哪些文件我说了算、做没做完有客观标准、改乱了有止损线、上线前有清单。
什么时候用
- 要开始一个新项目，准备让 AI 写第一行代码
- 项目推进一段时间后，开始出现改一处坏三处
- 要交付一个切片，需要确定「做完」的标准
- AI 连续改错、来回打转，需要止损
- 换会话 / 换机器 / 换 AI 工具，需要把进度带过去
- 准备上线发布
不用：单文件脚本、一次性计算、临时数据处理；已有成熟规范的项目内部的日常小改。
铁律（先记住这三条）
- 人负责边界和验收，AI 负责体力活。判断标准：这件事做错了会不会没人发现。会，人来做；不会，交给 AI。
- 没有验收标准就不许写第一行代码。
- AI 只能改你允许的，禁止清单比允许清单更重要。
第 0 步 开工三问
任何开发动作开始前，先写下答案，答不上来不许动手：
- 这次要交付的切片是什么，一句话说清
- 这个切片怎么验证做对了（可观察的动作或结果）
- 这次允许改哪些文件、禁止改哪些文件
阶段一 定图纸
| 步骤 | 做什么 | 完成标志 |
|---|---|---|
| 1 倒需求 | 讲清痛点、谁用、什么场景、最想要的几个功能 | AI 能复述需求，你认可 |
| 2 PRD + 验收标准 | 输出功能列表、用户流程、页面清单，每条补验收标准 | 任意一条功能都能回答「怎么验证做对了」 |
| 3 视觉与页面框架 | 定导航、页面、气质；有界面再定组件库、响应式断点、可访问性底线 | UI 方向写进文档，不再反复推倒 |
验收标准四段式，每条功能至少一条：
场景：<谁在什么前提条件下>
操作：<做了什么动作>
预期：<看到什么结果 / 数据变成什么样>
边界：<异常输入时的具体表现>
阶段二 打地基
| 步骤 | 做什么 | 完成标志 |
|---|---|---|
| 4 边界与非功能需求 | 本地自用还是上线；有无用户数据与合规；性能上限；成本上限（含 AI 每天最多烧多少额度） | 安全/性能/可用性/成本/合规五维各有书面结论，不留「看情况」 |
| 5 锁定技术栈 | 选可验证的：文档全、有示例、能测试、能审查 | 依赖全部精确版本，禁止 ^ ~ latest *；运行时版本也锁 |
| 6 架构草案 | 目录分层、模块职责、数据模型、哪些逻辑必须在服务端 | 每个模块职责一句话说得清；外部依赖统一出口；数据变更走可回滚迁移 |
阶段三 立规矩
| 步骤 | 做什么 | 完成标志 |
|---|---|---|
| 7 三份上下文 | 根目录 PRD.md（需求）、ARK.md（架构）、Project.md（进度/已知问题/下一步） | 三份文件与代码实际状态一致；新会话先读它，收工最后更新它 |
| 8 规范 + Reference 样板 | 语言、命名、单文件行数上限（建议 300）；Reference 目录存标准实现 | 新组件有可抄的样本 |
| 9 Git + 质量闸门 | main 永可运行；每切片一个分支；稳定节点打 tag | 一条命令跑完全部检查，全通过才可提交 |
阶段四 交付上线
| 步骤 | 做什么 | 完成标志 |
|---|---|---|
| 10 发布清单 | 闸门记录、密钥走环境变量、迁移可回滚且演练过、回滚方案、性能基线、漏洞与密钥扫描、观测就位 | 逐条打勾，缺一条不发；能灰度先灰度 |
| 11 最小观测 | 错误日志、关键指标（请求量/失败率/响应时间）、业务计数器、健康检查路径 | 上线后 24 小时内有人看一次日志 |
开发中十个关键点
- 小切片：一次一个可验证动作。>3 个文件、>200 行、说不清验收、AI 要三轮以上 = 切太大，必须拆。完成 = 可验证动作 + 闸门通过 + 提交，缺一不算
- 人拆模块：拆分是人的活，AI 不知道你将来怎么改
- 双清单约束：每次派活给「允许改」和「禁止改」两张清单，写进 Project.md，不靠口头提醒
- 派任务标准单：目标 / 允许改 / 禁止改 / 验收 / 上下文，五段缺一 AI 应拒绝执行
- 安全底线：密钥不进前端和仓库；服务端校验参数与授权；错误不泄露内部细节；输入转义；第三方依赖与 skill 先审来源和权限
- 科学应对报错：连续两次修改无新增证据即停 → 最小复现 → 加日志 → 小测试锁行为 → 仍失败就回滚。先验证前提条件（文件在不在、依赖装没装、路径对不对）
- 产出必审 8 条：改动在允许范围内？有没有顺手重构或改样式？依赖锁版本了吗？有没有硬编码密钥/路径/端口？输入校验了吗？错误分支有没有静默失败？有没有重复逻辑？命名符合规范吗
- 上下文交接：交接包 = PRD/ARK/Project + 当前切片状态 + 下一步唯一动作 + 最近一次闸门结果。新会话流程：读三份 → 复述进度 → 对齐 → 动手
- 测试分层：单测 70% / 集成 20% / E2E 10%；修 bug 必补一条复现它的测试；测试不过不许先合并
- 多 agent 并行：先定文件归属表、共享文件唯一 owner、合并顺序（先共享层后业务层，每合一次跑闸门）
红线清单（违反任意一条即停止当前动作）
- 一次让 AI 生成整个模块或整个页面
- 没有验收标准就开始写功能
- 提交前没跑闸门
- 让 AI 自己决定改哪些文件
- 密钥出现在前端代码或仓库里
- 同一问题连续两次无证据的修改还在继续
- 文档与代码状态不一致还在此基础上继续开发
- 三份上下文文件缺失仍开工
- 给用户一堆命令让他自己排顺序执行
- 多 agent 并行时同时改同一个文件
- 直接改生产数据或生产库结构，没有回滚脚本
- 没有回滚方案就发布上线
- 在生产环境直接调试、直接改代码试错
- 测试跑不过却先合并
每个切片收尾自检
- 验收标准逐条对上了吗
- 闸门全通过了吗
- 改动只在允许清单内吗
- 三份上下文文件更新了吗
- 提交信息说清这次做了什么吗
- 新依赖精确锁版本了吗
- 过了一遍审查清单 8 条吗
- 打了稳定 tag 吗，出问题能一键回滚吗
- 改了 bug 有没有补一条复现它的测试
- 要上线的话，发布清单勾完了吗，最小观测四项在不在
交付规范（AI 必须遵守）
- 需要用户执行命令时，只给一段可整段复制的指令，不列多条命令让用户自己排序
- 技术决策要给「推荐项 + 一句话理由 + 风险」，不把选择题甩回给用户
- 术语首次出现给白话解释
- 结论先行，不写铺垫和总结段
本 Skill 包含的文件
安装后包内实际存在这些文件，需要时按路径读取：
| 路径 | 内容 |
|---|---|
SKILL.md |
本文件，流程主体 |
README.md |
给使用者看的说明 |
guardrail_check.py.txt |
可直接运行的体检脚本（见下节） |
template-prd.md |
需求与验收标准 |
template-ark.md |
架构与技术栈，含架构模式速查表 |
template-project.md |
进度、禁止清单、下一步 |
template-task.md |
派活五段式 |
template-gate.md |
单一入口检查命令 |
template-testing.md |
分层比例与回归测试 |
template-release.md |
发布清单、回滚方案、最小观测四项 |
reference-antipatterns.md |
常见翻车姿势与对策 |
reference-cases.md |
三个完整使用案例 |
LICENSE.txt |
MIT |
可直接运行的脚本（不只是文档）
包里带一个能跑的工具 guardrail_check.py.txt，零依赖、只读、不联网、不执行外部命令。
用法一：新项目开工，生成三份骨架
python guardrail_check.py.txt 项目路径 --init
自动生成 PRD.md、ARK.md、Project.md，已存在则不覆盖（要覆盖加 --force）。
骨架里验收标准是四段式空表、架构里技术栈要求写精确版本、进度里预留了允许改/禁止改双清单。
生成完先填验收标准，再谈写代码。
用法二：提交切片前体检
python guardrail_check.py.txt 项目路径
python guardrail_check.py.txt 项目路径 --json # 输出 JSON，可接入 CI
检查六项，逐条给 PASS / WARN / FAIL 和具体文件名：
| 检查项 | 对应红线 |
|---|---|
| 三份上下文文件是否齐全 | 缺 PRD/ARK/Project 仍开工 |
| PRD 是否写了四段式验收标准 | 没有验收标准就写代码 |
| 依赖是否锁死精确版本 | ^ ~ * latest 浮动版本 |
| 是否硬编码密钥、.env 是否被忽略 | 密钥进仓库 |
| 单文件是否超过 300 行 | 代码全堆在一个文件 |
| 是否 Git 仓库、有无统一闸门入口 | 提交前不跑闸门、无法回滚 |
退出码：0 = 无 FAIL，1 = 有 FAIL，2 = 参数错误。有 FAIL 就不许提交。
脚本只用 Python 标准库，零依赖、只读、不联网、不执行外部命令，可直接审阅源码。
Agent 行为指令（触发本 Skill 时按此执行）
不要只把流程讲一遍，要按场景实际动手：
| 用户说 | 你必须先做 |
|---|---|
| 我要做个 XX / 帮我从零开始 | 跑 --init 生成三份骨架 → 走第 0 步三问 → 不写任何代码 |
| AI 改的代码越改越乱 | 跑体检脚本 → 逐条核红线清单指出踩了哪几条 → 给止损动作 |
| 准备上线 / 要发布了 | 跑体检脚本 → 按 template-release.md 逐条核对 → 缺一项就建议不发 |
| 这个怎么算做完 | 输出四段式验收标准（场景/操作/预期/边界） |
| 帮我派个活给 AI | 输出派任务五段式，缺一段就提醒 |
硬约束：脚本报 FAIL 时，必须明确建议先修再提交，不许跳过。
术语白话对照
| 术语 | 白话 |
|---|---|
| 切片 | 一次只做的一个小功能，小到能一次验证完 |
| 闸门 | 一条命令跑完的所有检查（格式化、lint、测试、构建） |
| 验收标准 | 凭什么说这个功能做对了，要能看见、能操作 |
| 双清单 | 允许 AI 改的文件清单 + 禁止改的清单 |
| 回滚 | 出问题一键退回上一个能跑的版本 |
| tag | 给某个能跑的版本打个记号，方便退回去 |
| PRD / ARK / Project | 需求文档 / 架构文档 / 进度文档，放项目根目录 |
| 灰度 | 先给 5%~10% 的用户用，没问题再全量 |
| 迁移脚本 | 改数据库结构的脚本，必须能反向撤销 |
| 幂等 | 同一件事重复做多次，结果一样，不会重复扣费或重复写入 |
| E2E | 端到端测试，模拟真人从头到尾走一遍主流程 |
用法示例
示例一：从零开始
> 用户：我要做一个家庭记账小工具，帮我按流程从零开始
AI 应先执行第 0 步提问（切片是什么 / 怎么验证 / 允许改哪些），再做步骤 1 倒需求，输出 PRD 骨架（照 template-prd.md 的格式），不写任何代码。
示例二：改乱了
> 用户：AI 改的代码越改越乱，帮我按红线清单止损
AI 应先逐条核红线清单指出踩了哪几条，然后给出止损动作：回滚到最近稳定 tag → 缩小到最小切片 → 补验收标准 → 补双清单，再重做。不继续在原代码上打补丁。
示例三：准备上线
> 用户：我要上线了，帮我过一遍发布清单
AI 应先跑一次 python guardrail_check.py.txt 项目路径，再按 template-release.md 逐条核对，缺失项明确标出，并给出回滚方案与最小观测四项的落地建议。缺一项就建议不发布。
更多翻车姿势见 reference-antipatterns.md，完整演示见 reference-cases.md。
