cyrus-12

name	Cyrus编码12步规范
description	一套 12 步的 AI 编码工作流规范。适用任务：新功能开发 / 修 bug / 重构 / 发布和热修 / 本地网页·API 调试验证。只要用户在用 AI 编程工具（Claude Code、Codex、Cursor 等）做开发任务，就应加载本 skill。效果：AI 按工程标准干活——先访谈需求再写计划、先定义验收再写代码、隔离分支开发、强制验证留证据、交付带回滚方案。

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 访谈你【核心】

任何代码任务，写第一行代码之前必须先有：

1. Task Spec：这次做什么、明确不做什么（范围越清楚，AI 跑偏越少）
2. 实现计划：不超过 10 步，具体到改哪个文件
3. 验收标准：可运行的检查（一条命令、一个测试，不是"应该没问题"）
4. 风险 + 回滚方案：搞砸了怎么退回去

说不清需求怎么办（小白最常卡在这）：直接告诉 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 糊弄的一步】

1. 优先可复现的脚本化检查（就是第 3 步定义的那个），而不是"我看了一眼没问题"。
2. 至少留一个确定性证据：测试输出 / 接口返回内容 / smoke 测试结果（smoke 测试 = 上线后最基本的"冒烟检查"：核心功能点一下，确认没冒烟没着火）。
3. curl ≠ 浏览器：网页相关的改动，必须用真实浏览器验证完整页面加载（AI 可以用 Playwright——一个让 AI 操作真浏览器的工具——自动做这件事）。命令行请求正常，不代表页面在浏览器里能正常打开。
4. 自动验收 + 截图存证：让 AI 用 Playwright 真实打开页面、按验收步骤逐步操作、每步截图，统一存到 test-evidence/<日期-任务名>/ 并生成 REPORT.md。你不用自己打开浏览器挨个点，只看截图报告确认——验收从"人肉点一遍"变成"看一份带图的报告"。
5. 修 bug 先复现，再动手：没在自己机器上看到 bug 发生，就不许改代码——改一个复现不了的 bug，等于闭眼开枪。bug 是修过又复发的：先看 git 历史上次改了什么 → 验证那个改动还在不在生效 → 不生效才从头排查。
6. 失败路径必须真测过：脚本/流程里写了"出错就回滚"，就必须真的制造一次失败看它会不会回滚。只打印"开始回滚"不真执行的回滚，是假的安全感（真实事故教训）。
7. 四条铁律背下来：
   • HTTP 200 ≠ 功能正常（要验响应内容）
   • 改了源码 ≠ 已部署（确认构建 + 推送 + 上线）
   • 改了一处 ≠ 改全了（用全文搜索把项目里所有同类入口都找出来）
   • 部署完成 ≠ 部署对了（验证线上跑的是这次改的版本，不是旧包）

第 7 步 · 上下文管理【核心 · 治"越改越乱"】

AI 编程工具的记忆（上下文）是会塞满、会变笨的。三条规则：

1. 一个会话只干一个任务。任务完成就开新会话，不要在一个窗口里从早聊到晚——塞满之后 AI 开始忘记你前面说过的话。
2. 纠正 2 次还不对 → 停手，开新会话重来。失败的尝试会污染上下文，AI 会在错误方向上越陷越深（俗称鬼打墙）。新会话 + 更精确的描述，比在原地纠缠快得多。
3. 大范围翻代码的活让 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 质量门禁【进阶 · 触发条件：代码要合并/上线/给别人用】

合并前过一遍，聚焦五点：

1. bug 风险与边界条件
2. 安全与 secret 泄露
3. 性能热点
4. 测试缺口
5. 文档和 .env.example 有没有跟代码漂移

长期项目建议加独立 Critic——AI 自己审自己的代码永远有盲区。做法：AI 在此处提示用户："建议你另开一个全新的 AI 会话，把这段代码粘进去让它独立挑毛病，再把报告拿回来。" 这一步由用户执行，AI 负责提醒和消化审查报告。

第 12 步 · 交付契约【核心】

每个任务结束，AI 的交付报告必须包含五项，缺一不收货：

1. 改了哪些文件
2. 跑了什么命令
3. 验证结果（带证据）
4. 风险
5. 回滚路径

---

附 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 ≠ 功能正常 —— 必须验证响应内容
• 改了源码 ≠ 已部署 —— 确认构建 + 推送 + 上线
• 只改一处 ≠ 改全了 —— 全文搜索整个项目确认所有入口
• 部署完成 ≠ 部署对了 —— 验证线上跑的是新版本
• 自动化之前先确认手动流程是对的 —— 不要自动化一个错误的流程
• 动手修之前先问一句：这个东西该不该存在？ 能消除整个流程，就不要去优化它
• 同一项目同一件事只有一种做法 —— 不混用两套写法
• "兼容别名"不留超过一个版本周期 —— 要么迁移完删掉，要么别建