分级五步开发法（业务型开发者版）
服务对象：懂业务、不逐行读代码的开发者。用户的控制点在 Plan（业务审批） 和 Verify（证据验收），不在代码行。
设计取向：强模型时代只在模型天然薄弱处（顺从执行仓促指令、不主动验证、跳过流程）设最小闸门，规则宁删毋加；本文件每变长一分都是代价。
第 0 步：任务分级（必做，先输出分级结论再动手）
| 级别 | 判据 | 流程 |
|---|---|---|
| A 微小 | 文案/样式/间距/单个明显小 Bug；不碰数据库、接口、权限 | 快速定位 → 最小修改 → 页面验证（不走完整五步） |
| B 普通 | 新页面/表单/列表/普通接口/模块内功能迭代；不碰核心架构 | 五步全走，Review 派子代理 |
| C 高危 | 数据库结构、权限体系、支付/订单、公共模块重构、生产部署、多项目共用能力 | 五步全走 + 业务控制点检查 + 独立审查 + 人工批准 |
判级拿不准时，就高不就低。分级结论要用一句话向用户说明理由。
第 0.5 步：模型档位前置确认（分级后、动手前必做）
输出分级结论的同时，对照当前主会话模型（见系统提示中的模型名），执行档位匹配检查：
| 分级 | 当前主模型 | 动作 |
|---|---|---|
| A 级 | Fable 5 或 Opus | 不阻塞：直接完成本任务，在收尾输出中附一行降档提醒（如「本次为 A 级小改已直接完成；若后续还有流水活建议 /model sonnet」） |
| B 级 | Fable 5 或 Opus | 停下，不开工。输出降档确认提示（见下），等用户答复后才继续 |
| A / B 级 | Sonnet / Haiku | 匹配，直接开工 |
| C 级 | 任何模型 | 直接进入五步流程（拍板点按既有规则提醒升档） |
降档确认提示模板：
【档位确认】本任务判级为 B 级，Sonnet 即可胜任，当前主模型是 Fable 5（额度消耗快）。建议
/model sonnet后重发这条需求；如果你想就用当前模型继续，回复"继续"即可。
用户明确回复"继续"（或等价表述）后，本任务内不再重复此提醒。用户切换模型后重发需求的，按新模型正常执行。
第 0.8 步：需求碰撞（动手前的最后一道闸门）
大模型输出质量的上限由输入需求的质量决定，而用户的指令往往是仓促的第一直觉。本步骤的职责：在执行前把仓促指令锤炼成完整需求——这是 AI 的责任，不是用户的。
姿态四铁律：
- 追问目标而非手段——区分"用户说的做法"和"用户要解决的问题"，永远先确认后者。用户说"加个导出按钮"，先问"导出给谁用、解决什么场景"，答案可能指向完全不同的方案
- 有不同意见必须说——如果判断用户的方案不是最优解，必须直说并给出备选方案 + 取舍理由，不许顺着做；用户坚持原方案则尊重执行
- 能查就别问——提问前先自查：这个答案能不能通过读代码/项目文档/已有配置得到？能查到的不问用户，直接去查
- 每个问题必须自带推荐答案——不许抛出一个空问题让用户自己想答案；先做出判断，把推荐答案和理由一起给出，用户只需确认或推翻，不用从零构思。想不出推荐答案，说明功课没做够，先补课（重新走第 3 条）再问
按分级执行碰撞深度：
| 分级 | 碰撞深度 | 提问节奏 | 动作 |
|---|---|---|---|
| A 级 | 零碰撞 | — | 一句话复述理解，直接干 |
| B 级 | 轻量碰撞 | 打包问，一次最多 3 个 | 输出：我理解的业务目标 + 最多 3 个关键澄清问题（各附推荐答案）+ 用户可能没考虑到的 1~2 个点；答复后进入 Research |
| C 级 | 完整碰撞 | 逐个问，一次一个 | 见下方清单，形成《需求简报》并落盘，用户确认简报后才进入 Research |
B 级打包问快、C 级逐个问深，是刻意的取舍：B 级任务风险低，打包节省往返；C 级任务决策之间往往互相依赖（前一个答案会改变下一个问题是否还需要问），逐支下钻才能问准，问完一个等用户答完再问下一个。
C 级完整碰撞必做四件事：
- 反问采访：按决策树逐支下钻、一次一个问题，沿依赖关系问到底（先问会改变后续方向的问题，被前面答案排除掉的分支不再问），每问必附推荐答案（可调用 interview-me 技能辅助整体框架）
- 备选方案：至少给出 1 个不同于用户原始指令的方案，附取舍理由
- 补齐边界：列出用户没提到的——异常流、权限影响、数据兼容、回滚方式
- 《需求简报》落盘：写入项目内文件（同时对抗长会话上下文压缩），模板：业务目标 / 可验收的成功标准 / 范围内与范围外 / 已确认的关键决策 / 备选方案及否决理由 / 边界与风险清单 / 尚未明确（迷雾区：当下无法回答、待前置决策解锁的问题——不许硬问硬答产生伪决策）
Research 及之后各步以《需求简报》（C 级）或碰撞后的确认结论（B 级）为准，不再以用户原始指令为准。
超纲升级：任务大于单个会话时（先制图，再动工）
触发时机：0.8 碰撞或 Research 阶段发现任务规模超出单个会话可承载——信号例：待决问题超过 5 个且互相依赖、实施明显要分多期、牵涉 3 个以上子系统。此时停止直接进入五步，先制图，并向用户报告"本任务超纲，建议先建地图"。
- 建地图文件：
docs/maps/<任务名>.md（项目无 docs 目录则放.claude/maps/），五段结构——目的地（要抵达的业务结果）/ 备注（背景与约束）/ 已定决策（每条含理由与日期）/ 尚未明确（迷雾区） / 范围外 - 决策票据：地图内维护票据清单，每张票据 = 一个待决策项（"要不要、怎么做"的问题，不是代码任务），标注状态（待解决/解决中/已定）与依赖（被哪张票挡住）。迷雾区里"还问不出精确问题"的部分，等前置票据解决后再"毕业"成新票据
- Plan, don't do：地图完成的标志 = 迷雾区清空、无票据待决——动手实施前没有任何事还需要先决定
- 一会话一票据：每个会话只认领一张票据（或已定方案的一期实施），完成即更新地图、结束会话；下个会话从地图继承上下文，不依赖会话记忆
- 地图内每期实施自身照常按分级走五步；地图更新纳入该期 Verify 的收尾动作（与写运行日志并列，不更新地图不算完成）
五步执行规则
1. Research —— 先理解，不要直接写
- 先读项目文档（CLAUDE.md / AGENTS.md / docs/）和相关现有代码，找到可复用能力和依赖关系
- 输出简短的现状理解 + 明确列出不确定项，随 Plan 一并呈批；若 Research 发现推翻碰撞结论或《需求简报》前提的事实，立即停下报告用户，不得带着变更后的前提直接写 Plan
- B/C 级检索由广到深：广撒网了解 → 聚焦关键区域 → 检查遗漏和隐性依赖
2. Plan —— 用户的主控制点
- 输出：目标 / 本次做什么 / 本次不做什么 / 改哪些文件 / 是否影响数据库、权限、API、公共组件、部署 / 如何验证 / 如何回滚
- 用业务语言写，让不读代码的人能判断"这个流程是不是我要的、范围有没有膨胀"
- C 级任务在此节点输出模型切换提醒（见下方规则）
- 等用户明确批准后才进入实施
3. Implement —— 按批准的计划执行
- 只按批准计划做；最小改动；优先复用现有模块；不顺便重构无关区域；超出计划立即停下报告
- 多文件实施优先派
implementer（Sonnet）；计划里已含完整代码的抄写派scribe（Haiku） - 每完成一项跑局部验证并记录，再继续下一项
4. Review —— 换视角检查，不许自评了事
- B 级：派
task-reviewer（Sonnet）做任务级审查 - C 级：派
final-reviewer（Opus）做独立终审 - 检查清单：需求符合性 / 范围膨胀 / 无关文件改动 / 重复建设 / 权限与数据风险 / 错误处理 / 测试真实存在
5. Verify —— 拿证据证明完成
- "已完成 / 应该可以运行"不算验证；必须给证据，每条附一句业务语言说明它证明了哪条业务目标；能让用户亲自操作确认的（打开页面点一遍、看数据是否还在），优先交用户做最终验收：
- 构建 / 类型检查 / 测试命令的实际输出
- Web 改动必须真实打开页面操作（浏览器验收）
- 数据真的落库、刷新后仍存在
- 不同权限账号无法越权
- 旧功能未被破坏
- 没有证据时不得宣称完成，要明确列出"未验证事项"
- 收尾动作（不做不算完成）：往
~/.claude/skills/five-step-dev/logbook.md追加本任务运行记录（格式见该文件头部）；若发现日志已满 10 条，主动提议用户运行「五步复盘」（five-step-retro 技能）
模型切换提醒（桌面客户端手动切换专用）
主会话日常保持 sonnet；审查环节靠派单解决（子代理模型已钉死），无需切主模型。共三个信号需要提醒用户手动切换——降档信号在第 0.5 步前置执行（见上），升档信号如下：
- C 级任务的方案拍板点——Plan 写完、请求批准时，附带输出：
【建议切换】本任务为 C 级高危，建议先
/model fable审定此方案再批准；审定后/model sonnet切回实施。 - 疑难升级——同一错误第 3 次尝试仍失败时，停止重试：若本环境配有 advisor（全局 settings.json 已兜底），先调用 advisor 诊断（自动转发完整上下文，无需简报、无需用户操作）；advisor 不可用或其意见仍无法解决时，再输出：
【建议切换】同一问题已失败 3 次，advisor 诊断未果，建议
/model fable深挖。
切换提醒前，先把关键上下文落盘（决策简报 / 进度账本），避免长会话上下文压缩导致背景丢失。
C 级业务控制点（实施前由 AI 逐项自答并各附一句依据；用户只对答"是"或存在风险的项拍板该后果是否接受）
- 是否影响现有销售流程 / Shopify 店铺的正常运行？
- 是否影响 Supabase 权限或数据结构？
- 是否影响多公司、多项目、多销售的共用结构？
- 是否会新建与现有 AI 接口重复的能力？
- 是否修改公共组件？影响面是否已列出？
- 是否触碰生产站点？回滚方案是什么？
- 哪些动作必须人工确认后才能执行？
移植说明（供其他使用者）
本技能源自作者的实际工作环境，直接使用前请做两处适配：
- 具名子代理：
implementer/task-reviewer/final-reviewer/scribe是作者在~/.claude/agents/中预建的自定义代理（模型分别钉死为 Sonnet / Sonnet / Opus / Haiku）。你的环境若没有同名代理，可以：- 建立自己的同名代理（推荐，防止模型参数漏写）；或
- 把这些名称替换为
general-purpose代理 + 显式model参数
- C 级业务控制点：清单中的 Shopify / Supabase / 多公司结构是作者的业务栈，请替换为你自己项目的高危资产清单（例如你的支付渠道、数据库、部署平台）。
模型名称（fable / sonnet / opus / haiku）对应 Anthropic Claude 系列，其他模型体系可按"最强档 / 标准档 / 轻量档"同构替换。
Codex 迁移
本技能格式与 Claude Code 无关，可直接迁移到 Codex，需替换以下四处：
-
安装方式：软链到 Codex 的个人技能目录，与本仓库
discover-project-skills用法一致：mkdir -p ~/.codex/skills ln -s "$PWD/skills/five-step-dev" ~/.codex/skills/five-step-dev调用方式改为
$five-step-dev（Codex 的显式技能调用语法），触发暗号照旧可用——只需把「五步法」映射写进 Codex 的全局AGENTS.md：我说「五步法」= 显式调用 $five-step-dev 处理该条需求 -
模型档位映射：技能里所有
/model fable、/model sonnet字样，替换为 Codex 的推理档位切换命令（如 GPT-5.6 的高/低 reasoning 档切换）。第 0.5 步的判断逻辑（分级 vs 当前档位，档位过高先停下确认）原样保留，只改命令文本。 -
具名子代理 → 独立会话审查：Codex 没有 Claude Code 的具名子代理机制（
implementer/task-reviewer/final-reviewer/scribe）。等效替换：- Implement 阶段的"派 implementer"，改为"在当前会话按批准计划直接实施"（Codex 无原生子代理派单，不必强行模拟）
- Review 阶段的"派 task-reviewer / final-reviewer"，改为"开一个新的 Codex 会话，只贴 Plan + Diff，不贴实现过程，要求独立审查"——用会话隔离代替代理隔离，达到同样的"换视角检查"效果
- Verify 阶段不受影响，证据要求原样保留
-
需求简报落盘路径：第 0.8 步产出的《需求简报》文件，路径按 Codex 项目约定调整（如有
.codex/或等价目录则放入，否则放项目根目录docs/decisions/下）。
其余步骤（分级判据、需求碰撞三铁律、五步执行规则、C 级业务控制点清单）均与工具无关，无需改动。
致谢
第 0.8 步「需求碰撞」的提问纪律（逐一提问、每问自带推荐答案、能查不问）参考了 obra/superpowers 的 grilling 技能设计，在此基础上按任务分级做了轻重区分（B 级打包问、C 级逐支问）。「超纲升级」一节的地图/决策票据/迷雾区机制参考了 mattpocock/skills 的 wayfinder 技能设计，将其 issue-tracker 地图简化为项目内 markdown 文件版，以适配非工程师使用者的工具链。