reviewing-technical-design

reviewing-technical-design — SKILL.md

**变体：**标准 · **适用场景：**将已完成的技术设计文档作为验收关卡进行评审——检查工程师能否据此实施，而无需重新推导设计，然后输出 VERDICT: approve|revise，并附上可执行的发现。全新项目，或修订（限定差异范围）。

概述

此技能是技术设计产出/评判配对技能中的评审部分。评审者加载此技能时，手中有一份已完成的技术设计文档（TDD）——即位于功能规格之下、说明如何在现有系统中构建某项功能的文档。此技能围绕一个问题评判该文档：工程师能否据此实施该功能，而无需重新推导设计？所选方案是否有充分理由，足以胜过一个真实的替代方案？此技能采用固定的 11 项可实施性检查清单（与 TDD 作者遵循的标准相同——authoring-technical-design 的第 5 步——以确保产出标准和评审标准保持一致），然后输出一条可由机器解析的判定，以及作者可以在一次修订中处理的发现。这是一道验收关卡——它不会撰写、修复或改写设计；它只负责评判并返回发现，由产出者进行修订。

评审标准与作者使用的标准单一来源。作者使用的技术——FMEA 故障模式分析、RTM 跟踪矩阵、C4 层次框架、序列图与流程图的选择、伪代码形式——都是评审者根据结果进行判断的辅助方法（每项决策是否都可追溯？是否处理了故障？是否命名了信号？），绝不是必须要求的条件。**但请注意边界：**发布、可观测性和测试确实是 TDD 的关键条件（条件 7/8/9），而不是像针对功能规格时要求发布计划那样，在此处「凭空添加」的条件。属于辅助方法的是技术（FMEA/RTM/C4/图表选择），而不是结果（具名信号、可追溯的决策、回滚触发条件）。

何时启用

• 已完成的技术设计文档需要在工程师据此实施之前作出接受/修订判定。
• 你是刚由产出者撰写的 TDD 的独立评审者 / 关卡审核者。
• 在先前判定为 revise 后，重新评判修订后的 TDD。
• 评审一份修订案——已批准的 TDD 加上一项变更请求——并限定差异范围进行评审（条件 11）。

请勿在以下情况启用：

• 撰写或修复 TDD → 使用 authoring-technical-design。此技能绝不撰写设计。
• 评审上游 PRD 或功能规格（是什么/为什么；每项功能的行为）→ 使用 PRD 评审 / 功能规格评审技能。此关卡评判的是如何构建功能，位于下一层。
• 评审 api-spec 或 data-model 本身（线缆协议 / 持久化架构）→ 它们是 TDD 引用的独立文档，各自有独立的评审关卡。
• 评审通用 / 临时的工程设计文档、RFC、ADR、规格或计划（非由文档库作为 technical-design 产出的文档）→ 使用 design-review，它会针对代码库验证所有这些类型文档中的设计声明。此关卡适用于文档库中的 technical-design 文档——其权威标识是 frontmatter 中的 template: technical-design；仅当前置元数据缺失时，才将 # Technical Design: 标题作为备用标识（通用文档即使只把自己命名为「Technical Design」，但没有该标记，仍应使用 design-review）。
• 检查模板/章节是否符合要求 → 这是模板方面的问题。此技能评判的是质量是否达到标准，而不是每个标题是否都已出现。

工作流

步骤 1：以全新、独立的视角通读整份设计

从头到尾阅读 TDD，仿佛是第一次接触它，不受作者的引导。你的立场是把关下一步（实现）：只有当某项发现表明，如果不重新推导设计本应明确的内容，就无法按设计构建该功能时，这项发现才有分量。将上游功能规格 + PRD（以及 TDD 引用的架构文档 / API 规格 / 数据模型）放在手边——步骤 2 的第一个条件会从正反两方面检查设计是否符合需求，条件 4 会检查引用的契约是否存在重复。这是修订吗？ 如果你收到的是针对现有 TDD 的变更请求 / 差异，请执行限定差异范围的路径（条件 11 生效；将审查范围限定在变更的决策及其连带影响）。首次构建绿地项目时不存在变更请求——条件 11 不适用。

步骤 2：执行可实现性检查清单——逐项判断条件

对于以下每个条件，判断为通过或存在缺口。只有确实存在明确指出的缺陷时，条件才算未通过——“我会采用不同的设计”不算缺口。对于每个缺口，记录准确位置及缺失内容（步骤 4 会将其转化为可执行的发现）。这些条件是统一的判定标准；不要另行添加自己的标准。

1. 需求追溯完整且双向。 功能必须满足的每项需求（PRD 目标／功能规格标准／约束）都有对应的设计元素予以满足；每项非平凡设计决策也都能追溯到某项需求——两个方向都要检查。没有对应需求的决策属于范围蔓延／过度设计；没有设计对应的需求属于覆盖缺口。对于孤立决策、未覆盖需求或未说明／无法还原的可追溯性，标记为缺口。（不可折叠基线——无论规模大小，不服务于任何需求的决策都是有问题的。）
2. 范围限定为单项功能／处于正确层级。 文档在现有架构内设计一项功能／组件；系统级结构应当引用，而不是重新设计。当 TDD 重新决定拓扑／数据存储／服务边界（在错误层级开展架构工作），而不是引用架构文档时，标记为缺口。（不可折叠基线。）
3. 方案与拆分可实现。 提供简短的方案概述；各组件／模块各有一项职责，并说明其协作对象，具体程度足以据此构建；主要控制流和数据流通过图示和带编号的说明展示，且二者相符。对于巨型组件、仅以功能名称标注的方框、没有图示的流程，或与正文相矛盾的图示，标记为缺口。（可折叠：小型功能的组件较少，流程也较短。）
4. 引用而非重复（SSOT）。 api-spec／data-model／architecture-doc 已负责维护的接口／架构／拓扑应当引用，并且只说明差异，不要将其内容内联。当 TDD 粘贴了负责维护该内容的文档中已有的端点列表、表 DDL 或服务拓扑时，标记为缺口（必然导致未来内容不一致）。（可折叠：未涉及任何由其他文档维护的契约时，无内容可供引用——不算缺口。）
5. 至少有 1 个真实备选方案，并给出决策标准。 至少列出一个真正可行的备选方案（不是稻草人方案），即一名胜任的工程师可能会选择的方案；通过权衡比较，并说明最终选择所依据的决策标准。对于只有一个盖章通过的方案、稻草人方案（“什么都不做／全部重写”），或仅凭断言做出的选择（“我们选了最好的”），却没有决策标准的情况，标记为缺口。（不可折叠基线——无论规模大小，都应遵循权衡纪律。）
6. 故障模式与横切面健壮性。 列出重要故障（错误输入、依赖故障／超时、部分失败），并针对每项故障说明其检测方式、处理／恢复方式和用户可见影响；在适用时说明并发／顺序／幂等性策略；功能涉及安全／规模／隐私时，应说明相关方面。对于只设计了成功路径的情况、列出故障却没有处理方式的情况，或明显涉及安全／数据方面却未加以处理的情况，标记为缺口。（可折叠：精简功能的故障面较小，也可能不涉及安全／隐私／并发；涉及的方面较少没问题，但故障未说明处理方式本身就是不可折叠基线。）
7. 说明可观测性。 列明功能产生／监控的健康状态和故障信号（成功／错误指标、关键日志／追踪、主导故障模式的告警）——这些信号也用于触发回滚。对于面向生产的功能，如果只说“之后再添加日志”，或回滚（cond-9）没有对应信号支撑其触发条件，标记为缺口。（可折叠：简单的内部辅助工具可以简要说明；可以精简，但在适用时不可完全缺失。）
8. 说明测试方案。 用可测试的术语说明验证方法——适用于该功能的单元／集成／端到端测试层级、cond-6 中的故障用例，以及针对功能所暴露契约的契约一致性检查；应引用功能规格中的验收标准，而不是重述。对于只说“我们会测试”、未覆盖故障用例的策略，或暴露的契约没有一致性检查的情况，标记为缺口。（可折叠：简单功能可能只需单元测试；未暴露契约时无需一致性检查。）
9. 说明发布／迁移／回滚方案。 说明发布方式（分阶段／功能标记／金丝雀）；在涉及数据／契约变更时说明迁移和向后兼容策略；回滚方案应包含可衡量的触发条件（与 cond-7 信号相关，而非“看起来不行时就回滚”）。对于有风险的变更却默认一次性全面发布、数据／契约变更却没有迁移方案，或回滚没有可衡量触发条件的情况，标记为缺口。（可折叠：简单的内部增量功能发布流程可以很简单，且无需迁移；精简说明即可。）
10. 明确说明有依据的假设，不得臆造。 将真正未知的事项列为假设／待解决问题，不要用文字将其包装成已确定事实；设计应体现此功能的具体情况和实际周边系统；不得为了显得完整而虚构方案／限制／接口。对于设计看似完整无缺，却不符合实际情况的内容，或断言某项限制／接口／方案似乎系凭空捏造（没有上游依据或调研支持）的情况，标记为缺口。（不可折叠基线。）
11. （仅修改时适用）差异范围明确、无连带遗漏、版本已更新。 审查相对于现有 TDD 的变更时：差异部分针对所涉及的决策满足条件 1–10；变更后的决策仍可追溯到某项需求（否则应明确标记为需要修改上游 PRD／功能规格）；已处理SSOT 连带影响（若契约有变，应指出需要修改负责维护该契约的 api-spec/data-model，并说明下游实现／测试计划／运行手册需要重新指向该版本）；文档自身版本号已更新，并附有变更日志（谁／何时／改了什么／为什么）；被取代的决策应明确标记，不得悄然删除。对于范围不明的差异、断裂的需求追溯、未标记的 SSOT 连带影响、缺少变更历史或悄然删除内容的情况，标记为缺口。（可折叠：从零开始的首次构建不适用此条件——不要重新全面审查未变更的 TDD，也不要要求初稿附带变更日志。） 适度原则。“无需重新推导设计即可实现”应与功能规模相匹配。轻量功能可以合理省略不需要的内容——没有并发 → 无需说明并发策略；没有持久化 → 无需迁移；简单的内部辅助工具 → 采用轻量级可观测性；没有对外暴露的契约 → 无需一致性测试；初稿 → 无需变更日志。评判的是决策是否完整，而非字数或模板章节是否齐全。只要小型设计完整，并满足所有适用条件，就通过。不要因为简短就臆造缺陷。

第 3 步：确定结论

• approve — 所有适用条件均通过。工程师无需重新推导设计即可按设计实现此功能；所选方案有充分依据。即使你能想到文风上的改进，也应批准；评判标准是能否实现，而非是否完美。
• revise — 一个或多个条件存在真实且明确的问题，阻碍了实现（例如，决策没有落到实处、重新设计的范围不当、将 api-spec 契约内联、只列出一个未经权衡的选项、失败处理缺失、生产功能缺少可观测性、策略未涵盖失败情况、回滚没有可衡量的触发条件、修订未界定范围／引发连锁问题等）。

不要为了表示做过努力或索要锦上添花的内容而要求修改。条件要么满足，要么不满足。

第 4 步：输出结论和可执行的问题

将结论单独写成一行——必须是字面文本 VERDICT: approve 或 VERDICT: revise，独占一行，不要添加代码围栏、引号或其他文字（此处的围栏仅为示例）：

VERDICT: approve

然后在后续各行列出问题。若结论为 revise，每个问题都必须可执行——指出未满足的条件、确切位置以及修复方法，让作者一次修改即可解决。若结论为 approve，问题说明可以省略；如有，也只能是非阻塞备注，不得暗示必须修改。

好的问题说明会指出缺陷和修复方法：

revise — 不重复已有内容（条件 4），§5 接口：完整复制了 api-spec 中的 GET /reports 端点列表（参数、响应架构）。修复方法：引用 api-spec §Reports，并且只说明此功能的变更（新增 format=csv 参数），使该契约只有一个事实来源。

不好的问题说明含糊且无法执行：

接口章节可以再精简一些。（哪个契约？为什么不符合标准？如何修复？）

规则

硬性规则（绝不可违反）：

• 恰好输出一行判定：VERDICT: approve 或 VERDICT: revise——该字面标记独占一行，行内不含其他内容。下游工具会解析它。
• 只做评审，不要代写。 返回发现的问题；不要重写、修正或补全设计。由编写者负责修改。
• 采用统一标准。 根据步骤 2 中的 11 项条件进行评审——这与作者（authoring-technical-design 步骤 5）采用的标准相同。不要另设条件，也不要私自提高标准。
• 评判的是结果，绝不强求使用辅助方法。 FMEA、RTM 矩阵、C4 抽象层级措辞、时序图与流程图的选择，以及伪代码形式，都是作者的方法——要评判决策是否有依据、故障是否得到处理、信号是否明确，绝不能说“你没用 FMEA／没画 RTM／没用时序图”。（发布、可观测性和测试的结果是实际条件 cond-7/8/9——只有方法才是辅助工具。）
• 不要错误地要求修改。 设计满足所有适用条件时就应批准，即使小功能的设计较简略也一样。只有存在真实且明确的问题时才要求修改。较小的功能可以合理地省略迁移、并发、独立的可观测性章节和变更日志。
• 不要错误地批准。 不要为了表示友善而对真实问题视而不见。存在阻塞性问题时，判定为 revise。
• 故障没有处理方案就是问题（cond. 6）。 不得让构建者自行设想恢复方案。
• 引用而不重复是关键要求（cond. 4）。 在文档中内嵌由其他文档维护的契约，属于真实问题（会导致内容不一致），而非风格小问题。
• 根据文档提供的上游材料进行评审。 评估 TDD 时，应检查其 depends_on 集合及其引用的文档。上游材料未产出，绝不能作为要求修改的理由。TDD 忽略了已产出且本应引用的上游材料，则可以据此提出问题。
• 修订只评审变更范围。 对现有 TDD 的变更进行评审时，只检查差异及其连带影响（cond-11）——不要全面重审未变更的设计；对全新初稿，也不要要求提供变更日志。
• 每项修改意见都必须可执行——指出未满足的条件、具体位置和明确的修复方法。

偏好（可酌情调整）：

• 按严重程度排列发现的问题——先列阻塞性问题，再列次要问题。
• 在每项发现中注明条件编号／名称，便于作者对应评审标准。
• 批准时的备注应尽量少，并明确说明它们不会阻碍批准。

易踩的坑

• 为了完整性而批准，而不是为了可构建性。 每个部分都可能齐全，但功能仍然无法构建（拆分方式含糊、失败后没有处理方式、内联的契约会逐渐偏离）。判断标准是能否无需重新推导设计即可实现功能，而不是模板是否填满。
• 列出了失败情况却没有处理方式。 设计列举了坏输入、超时和部分失败，看起来很全面，但如果没有针对每种情况说明检测方式 + 处理/恢复方式，构建要求仍未充分明确（条件 6）。
• 随意放过稻草人式备选方案。 “备选方案：什么也不做”不是真正的权衡；条件 5 要求的是一个有能力的工程师确实可能选择的选项，以及否决该选项的标准。
• 把发布/可观测性/测试当成凭空增加的条件。 对于功能规格，要求发布方案就是凭空增加条件；但对于 TDD，这些是门槛（条件 7/8/9）。不要误用功能规格审查者的立场，从而对这些内容审查不足。
• 凭空增加条件（最主要的偏移）。 添加门槛中没有的私有要求（“必须使用 FMEA／绘制 RTM 矩阵／使用时序图而非流程图”），会导致审查门槛偏离产出门槛。评判技术时只看结果。
• 系统性过度标记问题（错误要求修改）。 被要求找问题的审查者往往会矫枉过正。只有针对明确指出的真实缺陷，才算条件未满足；审查者原本会做出不同决策，并不构成缺口。
• 对内容精简的功能错误要求修改。 小功能的 TDD 本就应当简短；无需设置的部分（无迁移、无并发、无单独的可观测性、无变更日志）不构成缺口。
• 不要把这与功能规格门槛或设计审查混为一谈。 TDD 的评判重点是如何构建功能——比功能规格的行为要求低一层，且不同于 design-review（它通过对照代码库核验声明，来审核通用设计文档/RFC/ADR/规格/计划）。此门槛专门用于审核文档库中的技术设计产物。
• 判定标记漂移。 “已批准”“LGTM”“需要修改”，或埋在段落中间的判定结果都无法解析。必须单独一行输出字面内容 VERDICT: approve|revise。

反模式

• 走过场式批准。 为避免进入修改循环而草草浏览后批准——放过内联契约或未处理的失败，会导致缺陷或构建进行到一半时手忙脚乱。
• 吹毛求疵式要求修改。 把措辞、图表样式或锦上添花的内容说成缺口并据此阻止通过。只有真正妨碍实现的问题才应要求修改。
• 默默重写。 “直接改好设计更省事”——在审查过程中代为编写，会破坏产出与评判的分离。
• 凭空增加条件。 添加门槛中没有的要求（指定技术、指定图表类型）——这是该门槛重点防范的主要偏移。
• 对修订内容进行全面复审。 因为小幅改动，就重新评判整个未变更的设计——应按比例审查改动及其连带影响（条件 11）。
• 含糊的判定。 “基本批准，但是……”或给出两行判定。只能有一个决定，且只能有一个标记。

输出

针对一份技术设计文档给出一份审查结果：

• 一行判定——在单独一行原样输出 VERDICT: approve 或 VERDICT: revise。
• 审查发现——若判定为 revise，针对每个阻塞性缺口各给出一条可执行的审查发现（未满足的条件 + 位置 + 具体修正方法）；若判定为 approve，可选择提供非阻塞性备注。

抽象的使用方是负责协调产出→审查循环的组件：approve 表示接受设计并进入实现；revise 表示将审查发现返回给产出方，进行一次范围受限的修订。介质：当前受评产物是文本格式的 Markdown TDD；门槛不依赖介质。

相关内容

• authoring-technical-design — 这一对技能中的编写部分；它会按照本技能评审所依据的同一套 11 项条件标准编写设计文档。将两者配对可确保标准只有一个来源，避免编写和评审的标准出现偏差。
• 一个 feature-spec-review 技能 — 位于上一层的关卡，用于评审功能规格说明（即每项功能的行为）。文档不同，标准也不同。
• 一个 design-review 技能 — 用于评审通用工程设计文档、RFC、ADR、规格说明和计划的关卡（会根据代码库核验声明）。本技能专门评审文档库中的 technical-design 产物；design-review 不负责评审该产物。
• 若存在 api-spec / data-model，它们就是 TDD 所引用的契约；cond-4 会检查是否引用了这些契约，而不是在此处重复定义。
• 一个 technical-design template / content-template 工具 — 负责章节的 结构；本技能评判的是 是否达到标准要求的质量，而非结构是否符合规范。

渐进式披露

• references/implementability-bar.md — 展开说明 11 项检查条件，并为每项提供通过/不足信号和已完成的发现示例（双向追踪、SSOT/引用而非重复检查、真实备选方案及判定标准测试、包含处理方式的故障表、可观测性信号分类、测试/符合性信号、发布/可衡量的回滚信号，以及限定差异范围的修订信号）。当某项条件处于临界状态、需要更明确地判断通过或不足时加载。
• references/sources.md — 评审方法的研究依据（设计文档/RFC 实践、FMEA、RTM/可追溯性、单一事实来源、可观测性、RFC/ADR 修订生命周期）。

正文预算

• description ≤ 1,024 个字符（agentskills.io 上限）；在列表中，description 与 when_to_use 合计超过 1,536 个字符的部分会被截断。
• 正文 ≤ 约 500 行 / 5,000 个 token — 每轮都会保留在上下文中。
• 每个参考文件：超过 10k 个 token 时警告，超过 25k 时错误。参考文件总计：超过 25k 个 token 时警告，超过 50k 时错误。