Skip to content

文档审查系统设计

由 Markdown 原样翻译并转换为 Astro Starlight MDX 格式。

向 superpowers 工作流添加两个新的审查阶段:

  1. 规格文档审查 - 在头脑风暴之后、编写计划之前
  2. 计划文档审查 - 在编写计划之后、实施之前

两者都遵循实现审查所使用的迭代循环模式。

目的: 验证规格是否完整、一致,并且已经准备好进行实施规划。

位置: skills/brainstorming/spec-document-reviewer-prompt.md

它检查什么:

类别要查找的内容
完整性TODO、占位符、“TBD”、不完整章节
覆盖范围缺失的错误处理、边界情况、集成点
一致性内部矛盾、相互冲突的需求
清晰度模糊需求
YAGNI未请求的功能、过度工程化

输出格式:

## 规格审查
**状态:** 已批准 | 发现问题
**问题(如果有):**
- [章节 X]:[问题] - [为什么它重要]
**建议(顾问性):**
- [不阻止批准的建议]

审查循环: 发现问题 -> 头脑风暴代理修复 -> 重新审查 -> 重复,直到批准。

分派机制: 使用 Task 工具,并设置 subagent_type: general-purpose。审查者提示模板提供完整提示。头脑风暴技能的控制器分派审查者。

目的: 验证计划是否完整、是否匹配规格,并具有适当的任务分解。

位置: skills/writing-plans/plan-document-reviewer-prompt.md

它检查什么:

类别要查找的内容
完整性TODO、占位符、不完整任务
规格对齐计划覆盖规格需求,没有范围蔓延
任务分解任务原子化,边界清晰
任务语法任务和步骤上的复选框语法
块大小每个块低于 1000 行

块定义: 一个块是计划文档中任务的逻辑分组,由 ## Chunk N: <name> 标题分隔。writing-plans 技能基于逻辑阶段创建这些边界(例如,“Foundation”、“Core Features”、“Integration”)。每个块都应该足够自包含,以便独立审查。

规格对齐验证: 审查者会同时收到:

  1. 计划文档(或当前块)
  2. 用于参考的规格文档路径

审查者读取两者并比较需求覆盖情况。

输出格式: 与规格审查者相同,但范围限定在当前块。

审查流程(逐块):

  1. writing-plans 创建块 N
  2. 控制器使用块 N 内容和规格路径分派 plan-document-reviewer
  3. 审查者读取块和规格,返回裁决
  4. 如果有问题:writing-plans 代理修复块 N,回到步骤 2
  5. 如果批准:继续到块 N+1
  6. 重复,直到所有块都被批准

分派机制: 与规格审查者相同 - 使用 Task 工具,并设置 subagent_type: general-purpose

brainstorming -> spec -> 规格审查循环 -> writing-plans -> plan -> 计划审查循环 -> implementation

规格审查循环:

  1. 规格完成
  2. 分派审查者
  3. 如果有问题:修复 -> 回到 2
  4. 如果批准:继续

计划审查循环:

  1. 块 N 完成
  2. 为块 N 分派审查者
  3. 如果有问题:修复 -> 回到 2
  4. 如果批准:下一个块或实施

任务和步骤使用复选框语法:

- [ ] ### Task 1: Name
- [ ] **Step 1:** Description
- File: path
- Command: cmd

审查循环终止:

  • 没有硬性迭代限制 - 循环会持续,直到审查者批准
  • 如果循环超过 5 次迭代,控制器应该将此情况呈现给人类以获得指导
  • 人类可以选择:继续迭代、在已知问题下批准,或中止

分歧处理:

  • 审查者是顾问性的 - 他们标记问题但不阻止
  • 如果代理认为审查者反馈不正确,它应该在其修复中解释原因
  • 如果同一问题上的分歧在 3 次迭代后仍然存在,则呈现给人类

审查者输出格式错误:

  • 控制器应该验证审查者输出具有必需字段(状态,如适用则包括问题)
  • 如果格式错误,则带上关于预期格式的说明重新分派审查者
  • 在 2 次格式错误响应后,呈现给人类

新文件:

  • skills/brainstorming/spec-document-reviewer-prompt.md
  • skills/writing-plans/plan-document-reviewer-prompt.md

修改文件:

  • skills/brainstorming/SKILL.md - 在规格写入后添加审查循环
  • skills/writing-plans/SKILL.md - 添加逐块审查循环,更新任务语法示例
-
0:000:00