document-review

文档评审

通过多角色分析评审需求或计划文档。并行分派专门的评审 Agent，自动修复质量问题，并提出供用户决策的战略性问题。

阶段 0：检测模式

检查技能参数中是否包含 mode:headless。参数可能包含文档路径、mode:headless，或两者兼有。以 mode: 开头的标记是标志，不是文件路径——请从参数中移除这些标记，并将剩余标记（如果有）用作文档路径，以供阶段 1 使用。

如果存在 mode:headless，则在后续整个工作流中启用无头模式。

无头模式改变的是交互方式，而不是分类边界。文档评审仍按相同标准判断哪些问题有明确的正确修复方案，哪些需要用户判断。唯一的区别在于如何交付无法自动处理的发现：

• auto 修复会静默应用（与交互模式相同）
• present 类发现会以结构化文本形式返回，供调用方处理——不会出现 AskUserQuestion 提问，也不会请求交互式批准
• 阶段 5 会立即返回“评审完成”（不会询问是继续完善还是完成）

调用方可在技能参数中加入 mode:headless 来启用无头模式，例如：

Skill("compound-engineering:document-review", "mode:headless docs/plans/my-plan.md")

如果不存在 mode:headless，技能将以默认交互模式运行，行为保持不变。

阶段 1：获取并分析文档

**如果提供了文档路径：**读取文档，然后继续。

**如果未指定文档（交互模式）：**询问要评审哪份文档，或使用文件搜索/Glob 工具（例如 Claude Code 中的 Glob）在 docs/brainstorms/ 或 docs/plans/ 中查找最新文档。

**如果未指定文档（无头模式）：**输出“评审失败：无头模式需要提供文档路径。请使用以下命令重新调用：Skill("compound-engineering:document-review", "mode:headless ")”，且不要分派 Agent。

文档类型分类

阅读后，对文档进行分类：

• 需求——来自 docs/brainstorms/，重点说明要构建什么以及为什么
• 计划——来自 docs/plans/，重点说明如何构建及其实现细节

选择条件角色

分析文档内容，确定要启用哪些条件角色。检查以下信号：

product-lens —— 当文档对要构建什么以及原因提出可质疑的主张，或拟议工作的重要性超出当前问题时启用。系统的用户可能是终端用户、开发者、运营人员、维护人员或其他任何受众——判断标准不受领域限制。检查以下任一方面：

方面 1 — 前提主张： 文档对要构建什么或原因表明了立场，而有相关知识的利益相关者可能会对此提出合理质疑——不只是描述任务或重述已知需求：

• 问题界定中提出的需求并非显而易见，也无法从现有背景中直接得出
• 方案选择中存在其他合理选项（明示或暗示）
• 优先级决策明确排序哪些内容要构建、哪些内容要推迟
• 目标陈述预测了具体的用户成果，而不只是重述约束或描述交付物

方面 2 — 战略影响： 即使前提合理，拟议工作仍可能影响系统的发展方向、用户认知或竞争定位：

• 会影响系统给人的印象，或系统未来以何种特性著称的变更
• 会影响采用、入门体验或认知负担的复杂性或简洁性取舍
• 会开辟或关闭未来发展方向的工作（路径依赖、架构承诺）
• 机会成本影响——构建这项内容意味着无法构建其他内容

design-lens —— 当文档包含以下内容时启用：

• UI/UX 相关内容、前端组件或视觉设计语言
• 用户流程、线框图、屏幕／页面／视图相关内容
• 交互描述（表单、按钮、导航、模态框）
• 响应式行为或无障碍相关内容

security-lens —— 当文档包含以下内容时启用：

• 身份验证／授权、登录流程、会话管理相关内容
• 向外部客户端公开的 API 端点
• 数据处理、PII、支付、令牌、凭据、加密相关内容
• 涉及信任边界的第三方集成

scope-guardian —— 当文档包含以下内容时启用：

• 多个优先级层级（P0/P1/P2、必需／应该有／锦上添花）
• 大量需求（超过 8 项不同的需求或实施单元）
• 延伸目标、锦上添花的内容或“未来工作”章节
• 与既定目标似乎不一致的范围界定措辞
• 与需求之间缺乏明确联系的目标

adversarial —— 当文档包含以下内容时启用：

• 超过 5 项不同的需求或实施单元
• 明确的架构或范围决策及其给出的理由
• 高风险领域（身份验证、支付、数据迁移、外部集成）
• 新抽象、框架或重要架构模式的提案

第 2 阶段：宣布并分派角色

宣布评审团队

告知用户哪些角色将参与评审，以及原因。对于条件角色，请说明启用理由：

Reviewing with:
- coherence-reviewer (always-on)
- feasibility-reviewer (always-on)
- scope-guardian-reviewer -- plan has 12 requirements across 3 priority levels
- security-lens-reviewer -- plan adds API endpoints with auth flow

构建 Agent 列表

始终包含：

• compound-engineering:document-review:coherence-reviewer
• compound-engineering:document-review:feasibility-reviewer

添加已启用的条件角色：

• compound-engineering:document-review:product-lens-reviewer
• compound-engineering:document-review:design-lens-reviewer
• compound-engineering:document-review:security-lens-reviewer
• compound-engineering:document-review:scope-guardian-reviewer
• compound-engineering:document-review:adversarial-document-reviewer

分派

使用平台的任务/Agent 工具（例如 Claude Code 中的 Agent 工具、Codex 中的 spawn），并行分派所有 Agent。省略 mode 参数，以便应用用户配置的权限设置。向每个 Agent 传入根据下方子 Agent 模板构建的提示词，并填入以下变量：

变量	值
{persona_file}	Agent Markdown 文件的完整内容
{schema}	下方所含的发现项架构内容
{document_type}	Phase 1 分类结果中的“requirements”或“plan”
{document_path}	文档路径
{document_content}	文档全文

将完整文档传给每个 Agent，不要拆分成多个部分。

错误处理： 如果某个 Agent 失败或超时，继续使用已完成的 Agent 提供的发现结果。在 Coverage 部分注明失败的 Agent。不要因单个 Agent 失败而阻止整个审查。

分派限制： 即使达到最大数量（7 个 Agent），也要并行分派。这些文档审查者的范围明确，均只阅读一份文档，因此并行处理既安全又快速。

阶段 3-5：综合、呈现与后续操作

所有已分派的 Agent 返回结果后，阅读 references/synthesis-and-presentation.md，了解综合流程（验证、门控、去重、提升、解决矛盾、按自动修复类别路由）、自动修复应用、发现项呈现方式和后续操作菜单。在 Agent 分派完成前不要加载此文件。

---

所含参考资料

子 Agent 模板

@./references/subagent-template.md

发现项架构

@./references/findings-schema.json