cyrus-tt AI 编码 12 步工作流（vibe coding 不翻车指南）
核心思想一句话：AI 写代码很快，但"写完"不等于"能用"。 这 12 步就是逼 AI 把"能用"的证据拿出来。每一步都来自真实项目的教训，不是理论。
怎么用这 12 步（先读这个）
不是每个任务都要走全 12 步，按项目大小分两档：
- 核心步（人人必做，再小的任务也走）：第 1、2、3、6、7、12 步
- 进阶步（项目变大、要给别人用、要上线时再加）：第 4、5、8、9、10、11 步
AI 执行时：默认只跑核心步；检测到任务满足进阶步各自的触发条件（每步开头标了）才启用。不要在一个本地小脚本上堆全套工程仪式。
第 1 步 · 适用范围与沟通规则【核心】
- 适用：新功能 / 修 bug / 重构 / 发布和热修 / 本地网页·API 验证。只要是让 AI 写代码，统一走这一套，不要每个任务现编流程。
- AI 必须先用大白话解释要做什么，再给命令。必要时用比喻：
main分支 = 主干道，feature分支 = 旁边的施工道，修完才并回主路。 - 只给可直接执行的命令，不给"你可以考虑一下"式的抽象建议。
第 2 步 · 动手前先产"四件套"，写不出就让 AI 访谈你【核心】
任何代码任务，写第一行代码之前必须先有：
- Task Spec：这次做什么、明确不做什么（范围越清楚，AI 跑偏越少）
- 实现计划：不超过 10 步，具体到改哪个文件
- 验收标准：可运行的检查（一条命令、一个测试，不是"应该没问题"）
- 风险 + 回滚方案：搞砸了怎么退回去
说不清需求怎么办（小白最常卡在这）：直接告诉 AI"我说不清楚，你来采访我"。让 AI 一次问一个问题，把模糊的想法问成清晰的 Spec，再开始写。AI 解决一个错误的问题，比写出错误的代码浪费多得多。
小任务四件套可以浓缩成 4 行话，但不能没有。
第 3 步 · 写代码之前，先定义"怎么算过"【核心】
给 AI 一个它自己能运行的检查：一个测试用例、一条验证命令、一个对比截图的基准。
- 没有可运行的检查，你就成了人肉验证环——AI 每改一版你都得亲自点一遍。
- 有检查，AI 改完自己跑、自己确认过没过，你只看最终证据。
- 顺序铁律：检查先于代码存在。先告诉 AI"跑通 X 命令、输出 Y 才算完成"，再让它动手。
第 4 步 · 隔离开发，不直接改 main【进阶 · 触发条件：项目用了 git 且不止一个任务/一个人在动它】
- 所有改动在
feature/前缀的分支里做，main永远保持可用。 - 2 个以上任务并行 → 各开独立 worktree。worktree 是 git 的"分身"功能：同一个仓库在硬盘上开出第二个文件夹，两个任务各改各的互不打架（不懂可跳过，单任务用普通分支就够）。
- 命名：worktree 目录
<仓库名>-wt-<主题>，分支feature/<类型>-<主题>。
第 5 步 · 小步提交，推到远端才算保住【进阶 · 触发条件：项目用了 git】
- 每次改动小到能被 review，不要一个 commit 改 30 个文件。
- commit 信息动词开头：
Add/Fix/Refactor/Docs/Chore。 - 本地 commit ≠ 安全：机器一坏代码全丢。阶段性成果必须 push 到远端（GitHub 等），没推远端不算完成。
第 6 步 · 验证方法论【核心 · 最容易被 AI 糊弄的一步】
- 优先可复现的脚本化检查（就是第 3 步定义的那个），而不是"我看了一眼没问题"。
- 至少留一个确定性证据：测试输出 / 接口返回内容 / smoke 测试结果（smoke 测试 = 上线后最基本的"冒烟检查"：核心功能点一下，确认没冒烟没着火）。
- curl ≠ 浏览器：网页相关的改动，必须用真实浏览器验证完整页面加载（AI 可以用 Playwright——一个让 AI 操作真浏览器的工具——自动做这件事）。命令行请求正常，不代表页面在浏览器里能正常打开。
- 自动验收 + 截图存证：让 AI 用 Playwright 真实打开页面、按验收步骤逐步操作、每步截图，统一存到
test-evidence/<日期-任务名>/并生成 REPORT.md。你不用自己打开浏览器挨个点，只看截图报告确认——验收从"人肉点一遍"变成"看一份带图的报告"。 - 修 bug 先复现，再动手：没在自己机器上看到 bug 发生，就不许改代码——改一个复现不了的 bug，等于闭眼开枪。bug 是修过又复发的：先看 git 历史上次改了什么 → 验证那个改动还在不在生效 → 不生效才从头排查。
- 失败路径必须真测过：脚本/流程里写了"出错就回滚"，就必须真的制造一次失败看它会不会回滚。只打印"开始回滚"不真执行的回滚，是假的安全感（真实事故教训）。
- 四条铁律背下来：
- HTTP 200 ≠ 功能正常（要验响应内容）
- 改了源码 ≠ 已部署（确认构建 + 推送 + 上线）
- 改了一处 ≠ 改全了（用全文搜索把项目里所有同类入口都找出来）
- 部署完成 ≠ 部署对了（验证线上跑的是这次改的版本，不是旧包）
第 7 步 · 上下文管理【核心 · 治"越改越乱"】
AI 编程工具的记忆（上下文）是会塞满、会变笨的。三条规则：
- 一个会话只干一个任务。任务完成就开新会话，不要在一个窗口里从早聊到晚——塞满之后 AI 开始忘记你前面说过的话。
- 纠正 2 次还不对 → 停手，开新会话重来。失败的尝试会污染上下文，AI 会在错误方向上越陷越深（俗称鬼打墙）。新会话 + 更精确的描述，比在原地纠缠快得多。
- 大范围翻代码的活让 AI 派"分身"（subagent）去干，只把结论拿回来——主会话保持干净，留给真正的开发任务。
第 8 步 · VERIFY.md 验收交接【进阶 · 触发条件：改动是用户能感知的（界面/接口/行为变化）】
每次此类改动，在项目根目录的 VERIFY.md（没有就创建）追加一条：
## YYYY-MM-DD · 一句话改了什么 (commit SHA)
**背景**：为什么改 + 用户怎么感知。
- [ ] 具体操作步骤 → 期望结果
原则：面向测试的人写（"点哪里、看到什么"），不写"改了哪个类"。全部打勾 = 可以合并上线。AI 会话关掉之后，"要测什么"的知识就靠这个文件传下去。
第 9 步 · PLAN 治理【进阶 · 触发条件：预计超 30 分钟 / 改超过 1 个文件 / 涉及部署、数据库、外部联调】
满足任一条件，先写 PLAN 文档再动手：
- PLAN 写明 8 件事：目标、为什么做、不做什么、实现结构、涉及资源、验收标准、风险、回滚。
- AI 在这里必须停下来：把 PLAN 摘要讲给用户听，得到用户明确回复"同意/开始"之后才能动手写代码。AI 不得替用户批准、不得跳过这一步自行推进。
- DoD（完成的定义）= 证据，不是 git commit。说"完成"之前必须附证据（接口响应、截图、测试输出）。只有 commit 没有验证 = 最多算"已提交待验证"。
- 同时进行中的任务 ≤ 3 条，开新的之前先关一条。
- 涉及数据库变更：改之前必须先备份，且备份命令要真的执行过（不是写在脚本里没人跑过）。
第 10 步 · 安全基线【进阶 · 触发条件：项目对外提供网络服务/API。纯本地脚本、个人小工具只看前两条】
- 不硬编码任何 secret（密钥/密码/token），用环境变量；仓库里只放
.env.example（只有 key 名没有值）；泄露了先轮换 key 再修代码。——本地小工具也要遵守。 - AI 报的依赖包先确认真实存在再装：AI 会一本正经地编造不存在的包名（依赖幻觉），而攻击者会抢注这些假包名放恶意代码。
- CORS（浏览器的跨域访问开关）不设成
*全放行，白名单指定允许的来源。 - 登录/鉴权逻辑在缺少配置时必须拒绝所有请求，不能默认放行。
- 对外接口加访问频率限制（至少按 IP 限），接 AI 模型的接口尤其要加（被刷一晚上账单爆炸）。
- 输入验证在系统边界做：长度、格式、类型都查，不信任任何外部输入。
第 11 步 · Review 质量门禁【进阶 · 触发条件：代码要合并/上线/给别人用】
合并前过一遍，聚焦五点：
- bug 风险与边界条件
- 安全与 secret 泄露
- 性能热点
- 测试缺口
- 文档和
.env.example有没有跟代码漂移
长期项目建议加独立 Critic——AI 自己审自己的代码永远有盲区。做法：AI 在此处提示用户："建议你另开一个全新的 AI 会话，把这段代码粘进去让它独立挑毛病，再把报告拿回来。" 这一步由用户执行，AI 负责提醒和消化审查报告。
第 12 步 · 交付契约【核心】
每个任务结束，AI 的交付报告必须包含五项，缺一不收货：
- 改了哪些文件
- 跑了什么命令
- 验证结果（带证据）
- 风险
- 回滚路径
附 1 · 新项目起步清单（从零开一个会长期维护的项目时）
在新项目里创建以下文件（不是假设它们已存在）：
scripts/dev.sh— 一键启动；scripts/test.sh— 一键验证；docs/RUNBOOK.md— 出故障怎么处理、怎么回滚- 治理四件套：项目规则文件（Claude Code 用
CLAUDE.md，Cursor 用.cursorrules，Codex 用AGENTS.md）+PROGRESS.md（进度真相源）+plans/（任务计划）+VERIFY.md（验收清单）
附 2 · 高频踩坑清单（来自真实生产项目的教训）
- HTTP 200 ≠ 功能正常 —— 必须验证响应内容
- 改了源码 ≠ 已部署 —— 确认构建 + 推送 + 上线
- 只改一处 ≠ 改全了 —— 全文搜索整个项目确认所有入口
- 部署完成 ≠ 部署对了 —— 验证线上跑的是新版本
- 自动化之前先确认手动流程是对的 —— 不要自动化一个错误的流程
- 动手修之前先问一句：这个东西该不该存在？ 能消除整个流程，就不要去优化它
- 同一项目同一件事只有一种做法 —— 不混用两套写法
- "兼容别名"不留超过一个版本周期 —— 要么迁移完删掉，要么别建