design-review

概述

design-review 会对设计文档进行对抗式预批准审查，涵盖规范、设计文档、RFC、ADR 或实施计划。它会查找那些反复出现、否则会在后期（甚至生产环境中）才暴露的问题：缺少引导或所有权不明、名称具有误导性、未考虑规模、假设未说明、声明与代码不符、缺少故障处理、未审查安全面、复杂性缺乏依据，以及内容不完整。关键在于，它会对照实际代码库核实声明，而不是轻信文档中的描述，并引用 file:line 证据，确保每项发现都有依据。它会生成一份发现报告和审查结论；它绝不会编辑文档，也绝不会批准——这些仍由人工审查者和作者负责。可将它用作撰写设计后、签字认可前的审核关卡。

何时启用

• ✅ 规范 / 设计文档 / RFC / ADR / 实施计划即将获批，且你希望先找出其中的疏漏。
• ✅ 文档作者希望在提交设计进行签字认可前，先进行严格审查。
• ✅ 自动化工作流需要对设计文档执行一致的预批准审查步骤。

请勿在以下情况启用：

• 该产物是代码 / 差异——使用代码审查技能（requesting-code-review / code-review）；此技能审查的是设计文档，而非实现。
• 你正在编写文档——使用内容 / 模板技能起草；design-review 只审查已有草稿。
• 该文档是 doc-library technical-design 产物——通过 template: technical-design frontmatter 权威识别（仅当前置元数据缺失时，才以 # Technical Design: 标题作为备用信号；仅仅将通用文档标题写成 “Technical Design” 而没有该标记，仍由此处处理）——使用 reviewing-technical-design，这是专用审查器，用于检查 TDD 特有的可实施性标准（需求追溯、引用而非重复、可观测性、测试、发布、限定差异范围的修订）。design-review 仍负责通用设计文档、RFC、ADR、规格和计划——只有 doc-library 的 TDD 产物被单独划出。
• 该文档是 doc-library architecture-doc 产物（完整的系统架构文档及其链接的 ADR 文件）——通过 template: architecture-doc frontmatter 权威识别（仅当前置元数据缺失时，才以 # Architecture: 标题作为备用信号；仅仅将通用文档标题写成 “Architecture” 而没有该标记，仍由此处处理）——使用 reviewing-architecture-doc，这是专用审查器，用于检查架构质量标准（边界 + 关注点、结构 + 抽象层次、图表同步、ADR 机制、NFR 落实、横切关注点、ASR 覆盖、限定差异范围的修订）。**边界（关键约束）：**此处仅划出 architecture-doc-library 产物及其链接的 ADR 文件；独立的临时 ADR 或 RFC（不属于 architecture-doc 产物）仍由 design-review 处理。
• 该文档是 doc-library data-model 产物（持久化 / 领域模型——实体、键、关系、索引、规范化、生命周期）——通过 template: data-model frontmatter 权威识别（仅当前置元数据缺失时，才以 # Data Model 标题作为备用信号；仅仅将通用文档标题写成 “Data Model” 而没有该标记，仍由此处处理）——使用 reviewing-data-model，这是专用审查器，用于检查完整性 + 可查询性标准（具有类型和键的实体、基数 + 引用规则、由访问模式证明合理的索引、规范化 + 范式选择、生命周期 / 迁移、图表 ⇄ 表格同步、单向性与 API 规格的比较、限定差异范围的修订）。该模型引用的 api-spec / feature-spec 仍由各自的审查器处理；只有 data-model 产物被单独划出。
• 该文档是 doc-library api-spec 产物（工程 API 线协议约定——操作、请求 / 响应架构、身份验证、错误模型、分页、版本控制、示例）——通过 template: api-spec frontmatter 权威识别（仅当前置元数据缺失时，才以 # API Specification 标题作为备用信号；仅仅将通用文档标题写成 “API Specification” 而没有该标记，仍由此处处理）——使用 reviewing-api-spec，这是专用审查器，用于检查约定完整性标准（每个操作的请求和响应均定义类型 + 状态码、完整错误模型、共享类型引用 data-model、逐操作授权、分页 + 平局处理规则、与架构匹配的示例、单向性与 API 参考文档的比较、限定差异范围的修订）。不受风格限制（REST / GraphQL / gRPC）。它引用的 data-model / feature-spec 以及下游 api-reference 仍由各自的审查器处理；只有 api-spec 产物被单独划出。
• 文本是一行注释，或没有待评估设计内容的非结构化文字。

工作流

步骤 1：接收输入

• **必需：**待审阅文档的路径。
• **可选：**明确指出代码库中的相关位置（设计涉及的目录／模块）。如果未提供，则根据文档自身的引用（文件路径、命令／模块名称、引用的链接）推断需要验证的模块。
• **可选：**输出偏好——内联（默认）或在文档旁写入 review.md。

步骤 2：通读文档

在评判任何部分之前，先通读整份文档。记录文档对现有行为的描述、提及的命令／文件／动词、输入、规模假设，以及引用的代码路径——这些内容将用于步骤 3–4。

步骤 3：按类别寻找缺口

依据以下评审准则逐项检查文档。此列表可扩展——发现新的缺口类型时应添加类别；核心类别不得删减。

类别	要提出的问题
引导与所有权	对于设计使用的每项输入，由谁／什么创建，以及创建顺序是什么？ 是否说明了设置顺序？
命名是否准确	每个命令／文件／动词／字段是否按其名称所暗示的方式、以暗示的顺序执行？是否有误导性命名？
规模与限制	在 10×／1000× 的规模下会怎样？是逐项操作还是针对整个集合操作？并发如何处理？是否存在无界增长？
隐含假设	单数与复数、一项与多项、默认值、“显而易见”的事项——是否明确说明，而非仅凭假设？
与已发布代码的一致性	关于现有行为、路径或接口的描述，是否与代码的实际行为一致？（在步骤 4 中验证）
幂等性／失败／重跑	重跑、部分失败、崩溃、重试时会怎样？操作是否可安全重复？
安全面	是否涉及新的授权／认证、密钥处理、外部调用、破坏性操作或不可信输入？
必要性与更简单的替代方案	是否确实需要构建此功能？设计是否忽略了实质上更简单的方案？
完整性与清晰度	是否说明了问题／目标／非目标／替代方案／风险？初次阅读者能否理解？细节层级是否恰当？

计划审查视角——当审阅文档是实施／项目计划时，还需额外检查（以上 9 个类别仍然适用）：

计划检查项	要提出的问题
任务粒度	每个叶子任务是否只涉及一个关注点、只有一个可测试的退出检查，且不可再分？标出包含多个关注点（带有“并”）或未说明退出检查的任务。
依赖顺序／DAG	depends_on／阻塞边是否构成有效的 DAG（无环），且执行顺序是否遵循这些依赖？
与配套规范的覆盖情况	规范中的每个范围项是否至少对应 1 个任务，且没有任务实现范围外的工作？
退出标准的可测试性	每个阶段／任务的“完成”是否是单一、可测试的表述（命令／观察结果），而非主观判断？

步骤 4：对照代码验证声明（必需）

对于任何关于现有行为、路径或接口的发现，阅读／搜索引用的模块并确认，然后引用 file:line。这是有依据的审查与猜测之间的区别。

• 指出不一致的发现必须引用／指向真实代码（path:line）。
• 怀疑存在但无法确认的缺口，必须明确标记为 unverified——绝不能将其断言为事实（以此杜绝捏造）。
• 全新开发：如果文档描述的是没有现有代码可供核查的全新行为，则“一致性”类别为 不适用——没有代码可供验证本身绝不能成为阻塞因素。
• **限定工作范围：**仅验证文档引用的模块；不要扫描整个代码树。

步骤 5：汇总发现

每项发现：

- [severity] <category> — <location in the doc>
  Gap: <what is missing/wrong/unstated>
  Fix: <concrete suggested resolution>
  Evidence: <path:line> | unverified

严重程度：blocker（批准前必须解决——存在错误／缺失，会破坏设计或其前提） · important（应当解决——确实存在缺口，但并非致命） · minor（建议修复）。

第 6 步：结论

最后单独一行写：ready-for-approval（没有阻碍项）或 has-blockers（先列出阻碍项，再列重要问题，最后列次要问题）。结论是给人类的建议，并非批准。

第 7 步（可选）：大型或高风险文档的独立审查

对于大型或高风险文档，可安排一位没有先前上下文的新审查者（子 Agent），让其使用相同的评审标准，然后合并其发现（去重）。如果无法安排子 Agent，则改为再进行一轮独立审查，并说明这一点。这能体现全新视角的价值；这是可选步骤，不是必需步骤。

第 8 步：输出

• **默认直接在回复中输出：**向调用方返回发现和结论。
• **按需选择：**如果收到请求，则在文档旁创建 review.md。
• **绝不编辑文档。绝不批准。**提出建议；由作者修改，由人类决定。

规则

硬性规则（绝不违反）：

• **先核实，再断言（不得捏造）。**任何关于现有行为的说法，都必须通过代码和 file:line 引用确认，否则标记为 unverified。绝不臆造缺陷。
• **仅限审查。**绝不编辑文档；绝不批准或拒绝。输出应包含发现和结论建议；由人类负责决策，由作者负责修复。
• **绿地项目不构成缺陷。**没有可供核实的代码，本身绝不能成为阻碍项。
• 将核实范围限定在文档引用的模块中，不要扫描整个仓库。
• **如实评定严重性。**仅当问题确实必须在批准前修复时，才标记为 blocker；不要夸大严重性。

偏好（可调整）：

• 分类标准可扩展——出现新的常见缺陷类型时，可新增类别。
• 优先列出阻碍项；保持报告便于浏览；如果次要问题过多，可合并列出。
• 对每项发现，优先给出一个具体的建议修复方案，而不是泛泛而谈。

常见陷阱

• **轻信文档表述。**规范可能信誓旦旦地描述代码中并不存在的行为。第 4 步的核心价值就在于对照代码核实；跳过这一步的审查只是发表意见。
• **误将绿地项目标记为问题。**全新系统的文档没有可供核实的内容；将“无法核实 X”标记为问题是错误的——应将一致性标记为 N/A。
• **扫描整个代码树。**试图对照整个代码库进行核实既缓慢又容易产生噪声；应将范围限定在所引用的模块中。
• **过度标记问题。**把每个小问题都列为阻碍项，会掩盖真正的问题。严格把握严重性，才能让结论有意义。
• **把细节误当成完整性。**细节丰富不等于设计完整；反过来说，简洁但完整也完全可以。应判断是否包含了必要的决策，而不是看字数。

反模式

• **“它可能与代码不一致”，但没有核实。**把臆造或未经核实的缺陷当作事实陈述——这是禁止的；应先核实，否则标记为 unverified。
• **“我顺手把文档修一下。”**编辑文档不在范围内；本任务仅限审查。
• **“我觉得没问题。”**敷衍盖章——没有使用评审标准或核实声明，就草草浏览并批准。
• **“我来批准吧。”**擅自决定结果；此技能只提供建议，批准权属于人类。
• **“我把整个仓库都搜一遍，保险起见。”**核实范围不受限制；应限定在所引用的模块中。

输出

一份发现报告（默认直接在回复中输出；也可选择生成 review.md）：包含零项或多项符合第 5 步格式的发现，按严重性排序，最后附上一行 ready-for-approval | has-blockers 结论。该产物是供文档作者和人类审批者在审批关口参考的建议——绝非批准，也绝非经过编辑的文档。

相关

• requesting-code-review / code-review — 面向代码/差异的类似能力；design-review 是设计文档对应的能力，在代码尚不存在时运行。
• 内容/模板技能 — 编写由此技能审查的文档（编写与审查是不同的工作）。
• reviewing-technical-design — 专门审查文档库 technical-design 工件（TDD）的技能，该工件不在此技能的范围内。将 template: technical-design 文档转交给它；design-review 继续处理通用设计文档、RFC、ADR、规范和计划。
• reviewing-architecture-doc — 专门审查文档库 architecture-doc 工件（整套系统架构文档及其关联的 ADR 文件）的技能，该工件也不在此技能的范围内。将 template: architecture-doc 文档转交给它；独立的临时 ADR/RFC（不属于 architecture-doc 工件）仍由 design-review 处理。
• reviewing-data-model — 专门审查文档库 data-model 工件（持久化/领域模型）的技能，该工件也不在此技能的范围内。将 template: data-model 文档转交给它；design-review 继续处理通用设计文档、RFC、ADR、规范和计划。
• reviewing-api-spec — 专门审查文档库 api-spec 工件（工程 API 线级契约）的技能，该工件也不在此技能的范围内。将 template: api-spec 文档转交给它；design-review 继续处理通用设计文档、RFC、ADR、规范和计划。
• 适用于 spec → plan → implement 流程，作为 spec（及 plan）的审批前关卡。

渐进式披露

• references/sources.md — 评分标准的研究溯源信息。仅在审计类别来源时加载。

此技能不包含 scripts/ 或 assets/；它通过 Read / Grep / Glob 运行，也可选择派发子 Agent。

正文篇幅限制

• description ≤ 1,024 个字符（agentskills.io 上限）；列表中合并后的 description + when_to_use 会在 1,536 个字符处截断。
• 正文 ≤ 约 500 行 / 5,000 个 token。

更新日志

• 2.4.0（2026-06-15）— 范围调整：文档库 api-spec 工件现在转交给专属审查技能 reviewing-api-spec；它引用的 data-model/feature-spec 以及下游 api-reference 仍由各自的审查技能处理。仅增加内容，不影响 9 个缺口类别和 plan 视角。（第四个也是最后一个仅针对编写环节的范围调整——现在每种文档库类型都有专属的对应审查技能。）
• 2.3.0（2026-06-15）— 范围调整：文档库 data-model 工件现在转交给专属审查技能 reviewing-data-model；它引用的 api-spec/feature-spec 仍由各自的审查技能处理。仅增加内容，不影响 9 个缺口类别和 plan 视角。
• 2.2.0（2026-06-14）— 范围调整：文档库 architecture-doc 工件（及其关联的 ADR 文件）现在转交给专属审查技能 reviewing-architecture-doc；独立的临时 ADR/RFC 仍由此技能处理。仅增加内容，不影响 9 个缺口类别和 plan 视角。
• 2.1.0（2026-06-14）— 范围调整：文档库 technical-design 工件现在转交给专属审查技能 reviewing-technical-design；design-review 继续处理通用设计文档、RFC、ADR、规范和计划。仅增加内容，不影响 9 个缺口类别和 plan 视角。
• 2.0.0（2026-06-01）— 首个经审查的版本。