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