sdd-workflow 1.1.0

package/templates/skills/sdd-review/SKILL.md

@@ -0,0 +1,498 @@
+---
+name: sdd-review
+description: 独立质量评审 - 3个独立Agent并行评审代码、对照spec/plan合约，仲裁合并后输出评分和问题清单。人类审批决定是否迭代。
+invocable: true
+---
+
+# SDD Review - 独立质量评审器（MACE 多Agent竞争评审）
+
+> **受 Anthropic Harness 设计思想启发**：将执行（Generator）与评审（Evaluator）分离。
+> Agent 倾向于积极评价自己的工作，独立评审能发现自我评估遗漏的问题。
+>
+> **MACE 升级**：评审由 3 个独立 Agent 并行执行，通过共识机制提高评审准确性和置信度。
+
+在实现阶段完成后，独立审查代码和交付物，对照 spec/plan/testcases 进行多维度评分，输出结构化评审报告。
+
+## 核心定位
+
+> Review 是 SDD 流程的**独立质量门禁**，不参与实现，只负责评审。
+> 评审结果由人类审批，决定是否通过或需要迭代。
+
+## 前置条件
+
+- 已有功能规格: `.specify/specs/{feature_id}/spec.md`
+- 已有技术计划: `.specify/specs/{feature_id}/plan.md`
+- 已有部分或全部实现代码
+- 可选: 测试用例 `.specify/specs/{feature_id}/testcases.md`
+
+## 评审维度
+
+### 维度定义
+
+| 维度 | 权重 | 硬阈值 | 说明 |
+|------|------|--------|------|
+| 功能完整性 | ★★★ | ≥ 4/5 | spec 中定义的所有功能点是否都已实现？有无存根、TODO、占位符？ |
+| 需求一致性 | ★★★ | ≥ 4/5 | 实现是否与 spec/testcases/plan 的定义一致？有无偏离或遗漏？ |
+| 代码质量 | ★★ | ≥ 3/5 | 是否符合宪法约束？命名清晰？架构分层正确（参考 constitution.md）？ |
+| 边界处理 | ★★ | ≥ 3/5 | spec 中的边界条件和异常场景是否覆盖？空数据、并发、权限等 |
+| 集成完整性 | ★★ | ≥ 3/5 | 前后端对接是否完整？API 调用链路是否通畅？数据流是否闭环？ |
+
+### 硬阈值规则
+
+- **功能完整性 < 4** → 必须 ITERATE（功能缺失无法交付）
+- **需求一致性 < 4** → 必须 ITERATE（实现偏离需求）
+- 任意维度出现 **HIGH 严重度问题** → 必须 ITERATE
+- 所有硬阈值通过且无 HIGH 问题 → PASS（建议修复项可后续处理）
+
+## 多Agent竞争评审架构（MACE）
+
+> **核心改进**: 评审不再是单个 Agent 的自说自话，而是 3 个独立 Agent **并行评审** + **仲裁合并**。
+> 每个 Agent 拥有独立的上下文窗口，审查视角不同，通过共识机制提高评审准确性和置信度。
+
+### 评审 Agent 配置
+
+| Agent | 角色 | 审查维度 | 输入上下文 |
+|-------|------|----------|------------|
+| A: 严苛审查员 | 找出所有代码问题 | 功能完整性 + 代码质量 | spec + plan + 代码 |
+| B: 需求守护者 | 代表最终用户 | 需求一致性 + 边界处理 | spec + testcases + 代码 |
+| C: 集成检查员 | 端到端验证 | 集成完整性 + 架构合规 | plan + testcases + 代码 + constitution |
+
+### 仲裁规则
+
+1. **问题确认**: ≥2 个 Agent 同时发现的问题标记为「确认」（提升一级严重度），仅 1 个 Agent 发现的标记为「待确认」
+2. **评分聚合**: 每个维度取对应 Agent 的评分；如同一维度有多个 Agent 交叉评分，取中位数
+3. **硬阈值不变**: 功能完整性 ≥ 4, 需求一致性 ≥ 4
+4. **亮点合并**: 任意 Agent 提到的亮点均纳入最终报告
+5. **合约检查**: 任一 Agent FAIL 的合约项标记 FAIL（取并集）
+
+## 执行步骤
+
+### 1. 加载评审上下文
+
+读取以下文档（按优先级）：
+
+1. `.specify/specs/{feature_id}/spec.md` 或 `spec/README.md` — 功能规格与完成定义
+2. `.specify/specs/{feature_id}/plan.md` 或 `plan/README.md` — 技术方案与阶段合约
+3. `.specify/specs/{feature_id}/testcases.md` — 测试用例（如有）
+4. `.specify/memory/constitution.md` — 项目宪法
+5. `CLAUDE.md` — 项目配置
+
+### 2. 确定评审范围与收集代码文件
+
+询问用户评审范围：
+
+- **Phase Review**: 只评审某个 Phase（如 Phase 1 后端、Phase 2 前端）
+- **Full Review**: 评审所有已完成的实现
+
+根据评审范围，确定需要审查的代码文件列表，记录所有文件的完整路径。
+
+### 3. 并行派发 3 个评审 Agent
+
+> 使用 Agent 工具**同时派发 3 个独立评审 Agent**，每个 Agent 拥有独立上下文窗口。
+> 将评审所需的文档内容直接注入到每个 Agent 的 prompt 中，使 Agent 无需自行定位文件。
+> 3 个 Agent 调用必须在**同一条消息中**发出，确保并行执行。
+
+#### Agent A: 严苛审查员
+
+派发参数：
+- **subagent_type**: `general-purpose`
+- **description**: `SDD评审-严苛审查员`
+- **prompt** 内容模板：
+
+```
+你是一位严苛的代码审查专家。你的职责是找出代码中的所有问题，不放过任何瑕疵。
+你不关心代码编写者的感受，只关心代码质量是否达标。
+
+## 审查任务
+
+请仔细阅读以下文档和代码，然后对「功能完整性」和「代码质量」两个维度进行评分。
+
+### 功能规格
+{此处注入 spec.md 的完整内容}
+
+### 技术方案
+{此处注入 plan.md 的完整内容}
+
+### 待审查代码文件
+请读取以下文件并逐一审查：
+{代码文件路径列表，每行一个}
+
+## 评分维度
+
+对以下 2 个维度打分（1-5 分），每个分数必须提供具体论据：
+
+1. **功能完整性** (权重★★★): spec 中定义的所有功能点是否都已实现？
+   - 对照 spec 的每个用户故事和功能需求，逐一检查是否有对应实现
+   - 检查是否存在未完成的功能（存根方法、空实现、TODO 注释）
+   - 检查 plan 中定义的每个 API 端点是否都有对应实现
+
+2. **代码质量** (权重★★): 是否符合架构约束？命名清晰？
+   - 检查架构分层是否正确（参考 constitution.md）
+   - 检查是否有重复代码、硬编码
+   - 检查命名是否清晰、一致
+   - 检查是否有明显的性能问题（N+1 查询等）
+
+## 输出格式
+
+严格按以下格式输出评审结果，不要输出其他内容：
+
+---REVIEW-START---
+AGENT: A-严苛审查员
+SCORES:
+- 功能完整性: {score}/5 | {具体论据，列出每个功能点的检查结果}
+- 代码质量: {score}/5 | {具体论据，列出发现的质量问题}
+ISSUES:
+- [{HIGH|MEDIUM|LOW}] [{功能完整性|代码质量}] {问题描述} | 参考: {关联文档条款} | 定位: {文件:行号}
+CONTRACTS:
+- {合约项描述} | {PASS|FAIL} | {备注}
+HIGHLIGHTS:
+- {值得肯定的设计决策或实现模式}
+---REVIEW-END---
+```
+
+#### Agent B: 需求守护者
+
+派发参数：
+- **subagent_type**: `general-purpose`
+- **description**: `SDD评审-需求守护者`
+- **prompt** 内容模板：
+
+```
+你是最终用户的代言人。你的职责是检查每个用户故事和验收标准是否被满足。
+你代表用户利益，不遗漏任何需求细节。如果用户期望的功能没有实现完整，你必须指出。
+
+## 审查任务
+
+请仔细阅读以下文档和代码，然后对「需求一致性」和「边界处理」两个维度进行评分。
+
+### 功能规格
+{此处注入 spec.md 的完整内容}
+
+### 测试用例
+{此处注入 testcases.md 的完整内容}
+
+### 待审查代码文件
+请读取以下文件并逐一审查：
+{代码文件路径列表，每行一个}
+
+## 评分维度
+
+对以下 2 个维度打分（1-5 分），每个分数必须提供具体论据：
+
+1. **需求一致性** (权重★★★): 实现是否与 spec/testcases 的定义一致？
+   - 逐一对照 spec 中的每个用户故事（US-1, US-2...）
+   - 检查验收标准（Given-When-Then）是否被满足
+   - 检查 UI 实现是否与 spec 的界面需求一致
+   - 检查交互流程是否与 spec 的用户故事一致
+
+2. **边界处理** (权重★★): 边界条件和异常场景是否覆盖？
+   - 空数据处理、加载中状态、错误状态
+   - 权限控制、并发场景
+   - 数据量上限、特殊字符输入
+   - 用户误操作场景（重复提交、中途取消等）
+
+## 输出格式
+
+严格按以下格式输出评审结果，不要输出其他内容：
+
+---REVIEW-START---
+AGENT: B-需求守护者
+SCORES:
+- 需求一致性: {score}/5 | {具体论据，列出每个用户故事的检查结果}
+- 边界处理: {score}/5 | {具体论据，列出每个边界条件的检查结果}
+ISSUES:
+- [{HIGH|MEDIUM|LOW}] [{需求一致性|边界处理}] {问题描述} | 参考: {关联文档条款} | 定位: {文件:行号}
+CONTRACTS:
+- {合约项描述} | {PASS|FAIL} | {备注}
+HIGHLIGHTS:
+- {值得肯定的设计决策或实现模式}
+---REVIEW-END---
+```
+
+#### Agent C: 集成检查员
+
+派发参数：
+- **subagent_type**: `general-purpose`
+- **description**: `SDD评审-集成检查员`
+- **prompt** 内容模板：
+
+```
+你是一位系统集成专家。你的职责是端到端验证所有接口和数据流，确保系统完整性。
+你关注的是组件之间的对接是否正确，数据流是否闭环。你对照宪法约束检查架构合规性。
+
+## 审查任务
+
+请仔细阅读以下文档和代码，然后对「集成完整性」和「架构合规」两个维度进行评分。
+
+### 技术方案
+{此处注入 plan.md 的完整内容}
+
+### 测试用例
+{此处注入 testcases.md 的完整内容}
+
+### 项目宪法
+{此处注入 constitution.md 的完整内容}
+
+### 待审查代码文件
+请读取以下文件并逐一审查：
+{代码文件路径列表，每行一个}
+
+## 评分维度
+
+对以下 2 个维度打分（1-5 分），每个分数必须提供具体论据：
+
+1. **集成完整性** (权重★★): 前后端对接是否完整？数据流是否闭环？
+   - 检查前端 API 调用是否与后端端点匹配
+   - 检查请求参数和响应格式是否与 API 设计一致
+   - 检查数据流是否闭环（用户操作 → API → 数据层 → 返回 → UI 更新）
+   - 检查错误码和异常处理是否贯穿前后端
+
+2. **架构合规** (权重★★): 是否符合宪法约束和项目架构原则？
+   - 检查是否遵循 constitution.md 中定义的架构模式
+   - 检查分层是否正确（参考 constitution.md）
+   - 检查数据访问层是否正确封装
+
+## 输出格式
+
+严格按以下格式输出评审结果，不要输出其他内容：
+
+---REVIEW-START---
+AGENT: C-集成检查员
+SCORES:
+- 集成完整性: {score}/5 | {具体论据，列出每个接口和数据流的检查结果}
+- 架构合规: {score}/5 | {具体论据，列出每个架构约束的检查结果}
+ISSUES:
+- [{HIGH|MEDIUM|LOW}] [{集成完整性|架构合规}] {问题描述} | 参考: {关联文档条款} | 定位: {文件:行号}
+CONTRACTS:
+- {合约项描述} | {PASS|FAIL} | {备注}
+HIGHLIGHTS:
+- {值得肯定的设计决策或实现模式}
+---REVIEW-END---
+```
+
+### 4. 仲裁合并
+
+收集 3 个 Agent 的评审结果后，执行仲裁合并：
+
+#### 4.1 解析评审结果
+
+从每个 Agent 的输出中提取：
+- 评分（每个维度的分数和论据）
+- 问题清单（严重度、维度、描述、关联文档、代码定位）
+- 合约检查结果
+- 亮点
+
+#### 4.2 问题去重与确认
+
+1. 比对 3 份报告的问题清单，按语义相似度分组
+2. 确认规则：
+   - **≥2 个 Agent 报告的相似问题** → 确认，并提升一级严重度
+     - 例：2 个 Agent 都报告 MEDIUM → 升级为 HIGH
+     - 例：2 个 Agent 都报告 LOW → 升级为 MEDIUM
+   - **仅 1 个 Agent 报告** → 待确认（保持原始严重度，标注发现者）
+
+#### 4.3 评分聚合
+
+每个维度取对应 Agent 的评分：
+
+| 维度 | 主评审 Agent |
+|------|-------------|
+| 功能完整性 | Agent A |
+| 需求一致性 | Agent B |
+| 代码质量 | Agent A |
+| 边界处理 | Agent B |
+| 集成完整性 | Agent C |
+
+如同一维度有多个 Agent 在 issues 中间接覆盖到，标注交叉验证信息。
+
+#### 4.4 合约检查合并
+
+取 3 个 Agent 合约检查结果的**并集**：
+- 任一 Agent FAIL → 合约项 FAIL
+- 所有 Agent PASS → 合约项 PASS
+
+### 5. 生成最终评审报告
+
+保存到: `.specify/specs/{feature_id}/review-{phase}-r{n}.md`
+
+报告格式：
+
+```markdown
+# 评审报告
+
+> 评审时间: {date}
+> 评审范围: Phase {N} - {阶段名称}
+> 评审轮次: 第 {round} 轮
+> 评审方式: MACE 多Agent竞争评审
+
+## 总评
+
+**结论: PASS / ITERATE**
+
+| 维度 | 分数 | 评审Agent | 说明 |
+|------|------|-----------|------|
+| 功能完整性 | {n}/5 | A-严苛审查员 | {一句话} |
+| 需求一致性 | {n}/5 | B-需求守护者 | {一句话} |
+| 代码质量 | {n}/5 | A-严苛审查员 | {一句话} |
+| 边界处理 | {n}/5 | B-需求守护者 | {一句话} |
+| 集成完整性 | {n}/5 | C-集成检查员 | {一句话} |
+
+## 硬阈值检查
+
+- [ ] 功能完整性 ≥ 4: {PASS/FAIL}
+- [ ] 需求一致性 ≥ 4: {PASS/FAIL}
+
+## 阶段合约检查
+
+| # | 合约项 | 状态 | 确认情况 | 备注 |
+|---|--------|------|----------|------|
+| 1 | {合约描述} | ✅/❌ | [A+B+C] | |
+
+## 问题清单
+
+| # | 维度 | 严重度 | 确认情况 | 问题描述 | 关联文档 | 定位 |
+|---|------|--------|----------|----------|----------|------|
+| 1 | 功能完整性 | HIGH | [A+B确认] | {描述} | spec US-X | {文件:行号} |
+| 2 | 代码质量 | MEDIUM | [仅A发现] | {描述} | constitution | {文件:行号} |
+
+## 迭代建议
+
+### 必须修复（阻断项 - ≥2个Agent确认）
+- [ ] #1: {修复建议}
+- [ ] #2: {修复建议}
+
+### 建议修复（改善项 - 单Agent发现）
+- [ ] #3: {修复建议}
+
+## 亮点
+
+- {值得肯定的设计决策或实现模式}
+
+## Agent 评审详情
+
+### Agent A: 严苛审查员
+- 功能完整性: {n}/5 — {论据摘要}
+- 代码质量: {n}/5 — {论据摘要}
+- 发现问题: {N} 个
+
+### Agent B: 需求守护者
+- 需求一致性: {n}/5 — {论据摘要}
+- 边界处理: {n}/5 — {论据摘要}
+- 发现问题: {N} 个
+
+### Agent C: 集成检查员
+- 集成完整性: {n}/5 — {论据摘要}
+- 架构合规: {n}/5 — {论据摘要}
+- 发现问题: {N} 个
+
+## 变更记录
+
+### CR-REV-{n}: {简述}
+- **评审轮次**: 第 {round} 轮
+- **发现**: {问题}
+- **建议**: {修复方向}
+```
+
+### 6. 向用户汇报
+
+展示评审摘要，等待用户决策：
+
+```
+## 评审结论: {PASS/ITERATE}
+
+评审方式: MACE 多Agent竞争评审（3个独立Agent并行评审）
+
+| 维度 | 分数 | 评审Agent |
+|------|------|-----------|
+| 功能完整性 | {n}/5 | A-严苛审查员 |
+| 需求一致性 | {n}/5 | B-需求守护者 |
+| 代码质量 | {n}/5 | A-严苛审查员 |
+| 边界处理 | {n}/5 | B-需求守护者 |
+| 集成完整性 | {n}/5 | C-集成检查员 |
+
+确认问题 {N} 项（≥2个Agent确认）:
+  1. [HIGH] {问题描述} [{确认Agent列表}]
+
+待确认问题 {N} 项（仅1个Agent发现）:
+  2. [MEDIUM] {问题描述} [仅{Agent}发现]
+
+下一步:
+  → 输入 "iterate" 进入迭代修复
+  → 输入 "pass" 忽略问题，标记完成（不推荐）
+  → 输入具体问题编号只修复指定项
+```
+
+## 迭代模式
+
+用户选择 iterate 后：
+
+### 1. 加载评审报告
+
+读取最新的评审报告，提取必须修复项和建议修复项。
+
+### 2. 逐一修复
+
+按严重度从高到低排序，逐一修复问题：
+- **确认问题**（≥2 个 Agent 确认）优先修复
+- 每修复一个问题，更新评审报告中的状态
+- 修复过程中如触发自循环反馈，按 L1/L2/L3 规则处理
+
+### 3. 修复后自检
+
+对照评审报告检查所有已修复项：
+- 确认问题已解决
+- 确认修复未引入新问题
+
+### 4. 重新评审
+
+修复完成后，**重新派发 3 个评审 Agent**（回到步骤 3）。
+
+**迭代限制**: 最多 3 轮迭代。超过 3 轮后暂停，等待用户决策：
+- 继续迭代（用户确认）
+- 接受当前状态
+- 暂停开发，回溯到 plan/spec
+
+## 评审报告存储
+
+评审报告按轮次存储：
+
+```
+.specify/specs/{feature_id}/
+├── review-phase1-r1.md    # Phase 1 第 1 轮评审
+├── review-phase1-r2.md    # Phase 1 第 2 轮评审（迭代后）
+├── review-phase2-r1.md    # Phase 2 第 1 轮评审
+└── review-final-r1.md     # 最终评审
+```
+
+## 与其他 SDD 步骤的关系
+
+```
+sdd-specify  ←── 评审发现需求问题
+sdd-testcases ←── 评审发现测试盲区
+sdd-plan     ←── 评审发现设计缺陷
+sdd-implement ──→ sdd-review ──→ iterate/complete
+```
+
+评审发现的问题，按照自循环反馈机制回溯到源头：
+
+| 评审发现 | 回溯目标 | 反馈级别 |
+|----------|----------|----------|
+| 功能缺失但 spec 中有定义 | implement（未完成） | L1 |
+| 功能缺失且 spec 中未定义 | spec → plan → tasks → implement | L2 |
+| 实现与 plan 设计不一致 | plan → implement | L1/L2 |
+| 代码质量问题 | implement | L1 |
+| 发现新边界条件 | spec → testcases → plan → implement | L2 |
+| 架构设计不合理 | plan → implement | L2/L3 |
+
+## 注意事项
+
+1. **独立性**: 每个评审 Agent 必须拥有独立上下文，不能看到 Generator 的思考过程
+2. **并行性**: 3 个 Agent 必须在同一条消息中并行派发，不能串行执行
+3. **上下文注入**: 文档内容直接注入 Agent prompt，确保 Agent 独立上下文完整
+4. **具体性**: 每个问题必须关联到具体文档条款和代码位置
+5. **可操作性**: 每个问题必须给出修复建议，不仅仅是指出问题
+6. **建设性**: 评审不仅要发现问题，也要肯定亮点和值得复用的模式
+7. **效率**: 评审应聚焦于合约项和关键质量标准，不做过度审查
+8. **人类主权**: 评审结果由人类审批，AI 不自行决定通过或失败
+9. **共识优先**: ≥2 个 Agent 确认的问题优先级高于单 Agent 发现的问题
+10. **技术栈适配**: 审查标准应结合项目实际技术栈和架构模式（参考 constitution.md）