AI 编程标准作业流程（4 阶段闭环）
Overview
每个"需求 → 设计 → 编码 → 交付"的 AI 编程任务，都必须走 4 阶段闭环：
阶段一 需求理解 → 阶段二 方案设计 → 阶段三 编程 → 阶段四 输出。
核心原则：
- COT 思维链拆解：需求侧用五问、方案侧用六步，每步显式写"我假设了 ，若不成立则 "，暴露隐藏假设、防止跳步与幻觉。
- 批评家 Loop：方案设计与代码 review 必须引入独立的 code-reviewer Subagent 当红队，用固定 rubric 找茬，视角隔离避免"自洽陷阱"。
- 每阶段闭环：产出 → Subagent/工具介入 → 人工校准，最后统一输出报告。
铁律：先 COT 拆需求，再 COT 拆方案，最后进 critic loop。跳需求直接写方案 = 把错的事做得很好。
When to Use
走完整 SOP（新需求 / 业务改造）：
- 收到 PRD / 需求文档，需要分析、设计、编码实现
- 对已有功能做业务改造（含方案设计 + 编码）
- 任何"需求 → 设计 → 编码 → 交付"完整链路的 AI 编程任务
不走 SOP（快速修复 / 咨询）：
- 纯问答、只读探索
- 单文件小修小补（改常量、改判断条件、修 typo）
- Bug 根因明确、改动局部（1-2 文件、几行），不涉及设计调整
- 无编码产出的 Bug 定位咨询
判定决策树：
1. 有 PRD / 需求文档输入？
是 → 新需求，走 SOP
否 → 2
2. 新增功能 / 业务流程变更 / 跨模块系统性改造？
是 → 新需求，走 SOP
否 → 3（按 Bug 修复）
3. Bug 修复路径：
- 根因明确 + 改动局部 → 快速修复，不走 SOP
- 根因涉架构/设计缺陷、需重构、改动扩散多模块 → 升级新需求，回头走 SOP
升级原则（重要）： Bug 修复中发现根因涉架构/设计缺陷、或改动扩散多模块、或需设计文档支撑 → 主动声明升级："该 Bug 根因涉及 X，已超出单点修复范围，升级为新需求，启动 SOP 4 阶段流程。" 不确定时先按 Bug 快速定位，定位后若超单点立即升级。
阶段一：需求阅读 + 理解
输入：人工提供的 PRD 文档（路径或全文）
执行步骤：
1. 通读 PRD（禁止阅读代码）：本阶段仅读需求文档，不得浏览代码、不得涉及系统设计/技术实现。
- 用 COT 五问逐条回答（每步显式写假设与不成立后果）：
- ⅰ. 用户是谁 — 角色、痛点、当前应对方式（现有替代方案）
- ⅱ. 场景是什么 — 触发条件、频率、并发、数据规模
- ⅲ. 核心问题 — 一句话价值，未实现的业务代价
- ⅳ. 成功标准 — 可量化、可验收，明确验收口径
- ⅴ. 约束 — 合规 / 性能 / 兼容 / 技术债 / 组织边界
- 重点梳理：涉及哪些业务模块、整个业务链路如何流转、模块间如何交互、有哪些功能点。
- 若文档不足以理解（缺前置背景、关联模块说明），主动要求用户补充，不得转向代码猜。
2. 产出需求分析文档（仅需求侧，不含代码/设计理解）：
- 需求概述与业务目标
- 业务模块与链路梳理
- 结构化需求列表（每条可测，含显式假设）
- 功能点拆解（与既有需求关联/差异）
- 验收标准梳理
- 风险点与待澄清问题清单
闭环：人工审阅纠偏 → 输出《人工干预记录》（阶段一，记次数与要点）。
产出物：[ ] 需求分析文档 [ ] 人工干预记录（阶段一）
阶段二：技术方案设计
输入：阶段一需求分析文档
执行步骤：
1. Planning（规划）：
- 理解需求分析产物
- 理解代码图谱（掌握现有架构、定位改造点）：
- 有架构全景回顾需求 → 先读 graphify-out/GRAPH_REPORT.md
- 代码知识图谱：graphify query "<问题>" / graphify path / graphify explain（默认读工作区 graphify-out/graph.json）
- 输出设计文档
2. COT 拆解（方案六步）：基于结构化需求逐条推演（每步显式写假设与不成立后果）：
- ⅰ. 选型 — 为什么 X 不用 Y，列否决项，避免惯性选型
- ⅱ. 架构 — 分层、边界、对外契约（接口/事件/数据归属）
- ⅲ. 模块拆分 — 职责单一、依赖方向
- ⅳ. 关键链路 — happy path + 异常路径逐步画（调用链/状态机）
- ⅴ. 风险 — 性能拐点、一致性、灰度、回滚
- ⅵ. 验证策略 — 单测 / 集成 / 压测 / 灰度指标
- 六步产出衔接阶段三：拆为可独立验证的子任务，单测 ↔ 子任务可追溯
3. 架构师 Subagent 评审 Loop（批评家 Loop）：
- 引入 code-reviewer Subagent 扮演架构师红队（proposer 出方案 → critic 审查 → 修订 → 再 critic）
- 视角隔离：主 Agent 不自审，由独立 Subagent 当红队
- 7 条 rubric 逐条审查（只输出 P0/P1/P2 清单，每条含位置/后果/建议改法，不重写方案）：
① 验收项全覆盖？ ② 边界/异常都处理？ ③ 性能过拐点（数据量×10 是否崩溃）？ ④ 安全/权限/审计？ ⑤ 兼容/灰度/回滚？ ⑥ 可观测/可调试？ ⑦ 是否过度设计？
- 收敛条件：critic 连续两轮提不出新 P0/P1，且 P2 有 owner/后续 issue → 定稿
- 最大轮次 3 轮，超限人工裁决，避免无限循环
- 全程记录每轮：评审内容 + 修改内容 → 生成《架构师 Subagent 评审 Loop 过程文档》
闭环：人工审阅最终设计文档与 Loop 过程 → 输出《人工干预记录》（阶段二）。
产出物：[ ] 设计文档（含 COT 拆解） [ ] 架构师 Subagent 评审 Loop 过程文档 [ ] 人工干预记录（阶段二）
阶段二评审 Loop 调用模板（每轮调用 code-reviewer 时套用）：
> 角色=红队架构评审；输入=当前设计文档全文；按 7 条 rubric 输出 P0/P1/P2 清单（每条含位置/后果/建议改法）；不重写方案、不空泛评价。
阶段三：编程阶段
输入：阶段二设计文档（含 COT 拆解变更点）
执行步骤：
1. TDD 落地（REQUIRED SUB-SKILL：superpowers:test-driven-development）：
- 加载并遵循 test-driven-development skill 工作流
- 写单测前确认每个单测对应设计文档某业务改造点
- 单测 ↔ 设计变更点必须一一可追溯
2. 架构师 Subagent Code Review：引入 code-reviewer Subagent 对编码产出 review：
- 校准业务需求：实现是否符合 PRD 与需求分析
- 校准架构边界：改动是否越界、是否符合既有架构分层
3. 编码完成报告声明：每个单测是对设计文档哪个变更点做的单测
4. 提测影响范围分析（提测前输出《提测影响范围报告》）：
- 涉及的模块/服务清单
- 受影响的接口/API/事件/数据结构变更
- 上下游依赖（调用方与被调用方）
- 数据库/配置/中间件变更
- 回归测试范围建议与灰度/回滚预案
- 风险点与监控项
闭环：人工参与编码/修正，记录度量 → 输出《人工校准记录》（阶段三）：AI 写代码行数、人工写代码行数、人工 coding 场景、干预次数、干预场景。
产出物：[ ] 代码实现 + 单元测试 [ ] 编码完成报告（含 TDD/单测 ↔ 变更点对应表） [ ] 提测影响范围报告 [ ] 人工校准记录（阶段三）
阶段四：输出
汇总各环节报告，形成完整交付包。
产出物清单：
- [ ] 需求分析报告（阶段一）
- [ ] 方案设计报告（阶段二，含架构师 Subagent 评审 Loop 过程文档）
- [ ] 编码完成报告（阶段三，含 code review 结果、TDD 执行情况、单测覆盖、单测 ↔ 变更点对应表）
- [ ] 提测影响范围报告（阶段三）
- [ ] 人工干预汇总记录（各阶段干预次数/场景汇总）
工具衔接
| 用途 | 命令 |
|---|---|
| 代码图谱查询（默认工作区） | graphify query "<问题>" |
| 代码概念间关系路径 | graphify path "<A>" "<B>" |
| 代码聚焦概念子图 | graphify explain "<概念>" |
| 代码变更后更新图谱 | graphify update . |
| 帮助 | graphify --help / graphify <command> --help |
- superpowers skill：阶段三 TDD 用
test-driven-development；会话开始遵循using-superpowers调度协议。 - code-reviewer Subagent：阶段二方案评审、阶段三 code review 均使用；评审 Loop 全程留痕，生成独立过程文档。
执行备忘
- 各阶段产出物以文件落盘到工作区（建议：需求文档侧放
prd/，设计/报告侧放docs/或任务专属目录）。 - 人工干预记录保持简洁，重在次数与场景，便于复盘 AI 协作效率。
- 定稿方案 + "为什么选 X 不选 Y"决策理由写进设计文档，可喂 Graphify 图谱/知识库，下次类似需求直接检索复用。
Common Mistakes / Red Flags
- 跳阶段写代码：未产出需求分析文档就进设计、未出设计文档就编码 → 回退，严格按阶段走。
- 阶段一偷看代码：用代码反推需求，掩盖文档理解缺口 → 禁止；文档不足就要求补充。
- COT 只走形式：五问/六步不写显式假设，或假设从不被检验 → 每条必须写"若不成立则 ___"。
- 自审方案：主 Agent 自己 review 自己的设计 → 必须独立 code-reviewer Subagent 当红队。
- critic 空泛：rubric 只说"感觉不对"、不列位置/后果/改法 → 强制 7 条 rubric 结构化输出。
- 单测不可追溯：写了单测但说不清对应哪个变更点 → 单测 ↔ 变更点必须一一对应。
- 无限 Loop：critic 轮次超过 3 仍不收敛 → 升级人工裁决，不空转。
