reviewing-architecture-doc

reviewing-architecture-doc — SKILL.md

变体： 标准 · 适用时机： 将已完成的全系统架构文档（及其链接的 ADR 文件）作为验收门槛进行评审——检查工程师能否理解系统，以及某项功能的技术设计能否将自身定位于其中，然后输出 VERDICT: approve|revise 和可执行的评审意见。绿地项目，或修订（范围限定为增量变更）。

概述

此技能是架构文档编写/评审配套流程中的评审部分。评审者载入已完成的全系统架构文档及其链接的 ADR 文件后，会依据一个问题进行判断：新工程师能否在不询问作者的情况下，理解系统结构及其重大决策背后的原因，并且某项功能的技术设计能否在架构中定位自身？它会应用固定的架构质量 10 项检查清单（与架构文档作者编写时遵循的标准相同——即 authoring-architecture-doc 的 Step-7，确保编写标准与评审标准保持一致），然后输出一份机器可解析的单一结论，以及作者可以在一轮修订中落实的评审意见。这是一个验收门槛——它不会编写、修复或重写文档；它只负责判断并返回评审意见，由编写者进行修订。

它会评审两项产物：架构文档和其链接的 ADR 文件。 条件 4（ADR 机制——索引⇄文件同步、单个 ADR 的质量以及不得重写）无法仅凭文档验证——评审者需要链接的 ADR 文件（或 adr/ 目录）。如果未收到这些文件，应将条件 4 标记为无法验证并说明原因；绝不可捏造其内容。

评审标准与编写标准保持一致。作者采用的技术方法——C4 视图选择、arc42 章节框架、ATAM 权衡分析、4+1 视图、Mermaid 图表形式——都是评审者根据结果进行判断的辅助方法（边界是否明确？决策是否有关联并可追溯？每个 NFR 目标是否已实现？），而不是需要强制采用的条件。但请注意这个边界： ADR 机制（条件 4）、NFR 实现（条件 6）和系统级可观测性策略（条件 7）确实是架构文档中不可或缺的重要条件——它们并非“凭空发明”的条件。作为辅助方法的是技术手段（C4/arc42/ATAM/4+1/图表选择），而不是结果（关联的 ADR、已实现的目标、明确命名的可运维性信号）。

适用场景

• 已完成的架构文档需要在工程师据此构建系统（或在其中放置某项功能的技术设计）之前，作出接受或修改的决定。
• 你是独立评审者／把关人，负责评审编写者刚完成的架构文档。
• 在先前给出 revise 判定后，重新评审修订版架构文档。
• 将 amend（已批准的架构文档 + 变更请求）作为限定变更范围的评审（cond-10）。

不要在以下情况启用：

• 编写或修复架构文档 → 使用 authoring-architecture-doc。此技能不会编写文档。
• 评审上游 PRD／产品方向（做什么／为什么、NFR 目标）→ 使用 PRD 评审技能。此把关流程评判的是整个系统如何构建，低一个层级。
• 评审某项功能的技术设计（TDD——如何在架构中实现某项功能）→ 使用 reviewing-technical-design，再低一个层级。
• 评审 api-spec 或 data-model 本身（线上的契约／持久化的架构）→ 它们是架构文档引用的独立文档，各自有对应的把关流程。
• 评审通用／临时的工程设计文档、RFC、独立 ADR、规范或计划（并非作为文档库 architecture-doc 产物编写的文档）→ 使用 design-review，它会针对这些类型的文档，根据代码库验证设计主张。此把关流程适用于文档库的 architecture-doc 产物——以 frontmatter 中的 template: architecture-doc 作为权威标识；仅当前置元数据缺失时，才将 # Architecture: 标题作为备用信号（仅仅将标题写成“Architecture”但没有标记的通用文档，仍由 design-review 处理；不属于 architecture-doc 产物的独立 ADR 也仍由 design-review 处理）。
• 检查模板／章节是否符合要求 → 这属于模板范畴。此技能评判的是是否达到质量标准，而非是否包含每个标题。

工作流程

步骤 1：以全新的独立视角通读整份架构文档，并备好 ADR 文件

从头到尾阅读架构文档，仿佛第一次接触这个系统，不受作者的框架影响。你的立场是把关人，面向所有基于该系统进行构建的人：只有当某项发现表明读者无法理解系统结构或在其中放置功能，且必须重新推导文档本应明确的内容时，这项发现才有分量。保持相关 ADR 文件处于打开状态（cond-4 需要这些文件），同时打开上游 PRD／产品方向（cond-8 会据此追溯）以及文档引用的 api-spec／data-model（用于 cond-2 的层级检查）。这是 amend 吗？ 如果收到的是针对现有文档的变更请求／差异，则执行限定变更范围的流程（启用 cond-10；评审范围限定为变更的决策／结构及其连带影响）。首次构建绿地项目时，不存在变更请求——cond-10 不适用。

步骤 2：运行架构质量检查清单，逐项评判条件

对以下每项条件，判定为通过或存在缺口。只有存在真实且明确指出的缺陷时，条件才算不通过——“如果是我会采用不同的结构”不算缺口。对于每个缺口，记录具体位置和缺失内容（步骤 4 会将其转化为可执行的发现）。这些条件是唯一的评判标准；不要自行添加标准。

下方的能力边界检查项仅适用于在编写调用中注入了 capability_record 且其可用作评审上下文的情况。若没有，则视为不适用——未定义边界时，不要因文档缺少能力边界标记而扣分。

1. 上下文、边界与涵盖的关注点。 新读者能够说明系统的职责范围和非职责范围：边界（纳入／明确排除的内容及其负责人）清晰明确，所有参与方和外部依赖均已列出，上下文图与正文一致，并且每个已识别的利益相关方关注点都由某个章节／视图涵盖。若边界只是隐含的、外部依赖未列明，或某个已列出的关注点没有任何章节回应，则为 缺口。（不可折叠的基线：始终明确说明边界和外部依赖集合——缺少这些内容会掩盖集成风险。）
2. 结构与抽象层次。 每个主要组件只列出一次，并说明其单一职责和类型（不能有未解释的方框）；拓扑图说明每条边的方向和协议／风格；集成边界列明契约负责人；文档保持在整个系统的抽象层次——以结构方式列出主要接口和数据存储，而非每个端点（api-spec）、每张表（data-model），或某个功能的实现（TDD）。若出现上帝组件、未解释的方框、未说明方向／协议的边，或抽象层次滑入端点／表／功能细节，则为 缺口。（不可折叠的基线：每个组件只有一个职责，并保持抽象层次。）
3. 图示 ⇄ 叙述保持同步。 图示中的每个方框／箭头都在正文中有所说明，反之亦然；图示可独立阅读；在运行时／部署视图承担重要作用时，必须提供该视图。若图示中的元素未在正文中说明（或正文提到的组件未出现在图示中），或多服务／多环境系统缺少部署视图，则为 缺口。（可折叠：简单系统只需少量或无需图示；只要存在图示，同步规则就适用。）
4. ADR 机制（标志性条件）。 每项重要决策都必须记录在独立的、带链接的 ADR 文件中（每个文件一个决策），而非直接嵌入本文档；决策索引 ⇄ ADR 文件保持同步（双方都有有效链接，并标明已被取代的条目）；且不得改写任何已接受的 ADR（有变更时应新建一份取代它的 ADR）。若决策直接粘贴在正文中而非通过链接指向 ADR、一个 ADR 包含两个决策、索引链接失效／缺失，或已接受的 ADR 被原地修改（导致历史记录丢失），则为 缺口。（不可折叠的基线：无论系统规模大小，改写已接受的 ADR 都是违规；轻量系统只需更少的 ADR。若未提供 ADR 文件，无法验证——应标记出来，不要编造。）
5. 追踪重要决策并说明理由。 每项重要选择／决策（运行时、数据存储、消息传递、托管、信任模型等难以变更的事项）都应说明其驱动因素（需求／NFR／ASR），并列出一个真实的（非稻草人式）替代方案以及该方案在权衡中不被采用的原因。对缺少驱动因素的重要选择，或未考虑任何替代方案、仅断言“我们选择了 X”，则为 缺口。“团队默认”可接受，前提是明确说明。（不可折叠的基线——无论系统规模大小，都应遵循权衡说明规范。）
6. NFR 的实现与权衡。 PRD 中列出的每个 NFR 目标都应有一个实际实现机制（而非重复目标）；对于承担关键作用的目标，该机制应可测量（即包含带响应度量的质量属性场景）；若质量属性之间存在冲突，应列出并解决相关权衡。若只是重复目标却没有实现机制、“高可用”声明未讨论单点故障，或明显存在但从未指出的矛盾（延迟与一致性、成本与可用性），则为 缺口。（可折叠：没有硬性 NFR 的轻量系统可从简；服务于任何目标的机制若不存在，则属于过度设计。）
7. 系统涉及哪些横切关注点，就应在哪些方面予以处理。 每个集成边界都应说明韧性策略（超时／重试／熔断／回退／降级）；说明安全策略（信任边界／身份验证与授权／密钥／不可信输入）；存在敏感数据流时说明隐私策略；并提供系统级可观测性策略（黄金信号／健康状况／SLO 监控方针，以确保系统可运维）。若外部依赖没有针对变慢／宕机的应对策略、面向外部的系统没有信任边界，或多服务系统没有可观测性策略，则为 缺口。（可折叠：没有外部依赖的单进程工具可以合理地省略其中大部分内容；任何已存在的外部依赖都必须有故障应对策略，任何外部接口都必须有安全策略。）
8. 需求／ASR 覆盖。 每个架构重要需求都应有相应的实现结构／决策（不能有未覆盖的 ASR）；每个主要结构都应有驱动因素（不能有无归属的结构）。下游文档应可直接使用：某个功能的技术设计能够定位自身在架构中的位置，无需询问作者。若某项 ASR 没有对应的实现结构，或某个组件／子系统不服务于任何需求，则为 缺口。（可折叠：只有一项需求的系统可轻易完成追踪。）
9. 明确并合理依据假设，不得编造；与实际系统保持一致。 应将真实的未知事项列为假设／待解决问题，而不是掩盖为已确定的事实；不得为求完整而编造任何内容（拓扑、基准测试、供应商声明、理由等）；并且必须根据真实代码／拓扑验证系统现状声明（引用 file:line；无法确认时标记为未验证）——这正是 design-review 过去负责的与已交付系统一致性检查。若内容读起来虚假地完整、编造了限制／机制，或关于现有行为的声明与代码矛盾，则为 缺口。（绿地项目条款——不得编造是不可折叠的基线，但是，当没有现有代码／系统可供验证（全新系统或虚构／示例文档）时，一致性检查为不适用，绝不构成阻碍——应标记为未验证，不要虚假地修改文档。）
10. （仅限修订）变更范围明确、影响传递无遗漏、版本有更新。 针对现有架构文档审查变更时：变更在其涉及的元素上满足条件 1–9；通过新建取代旧 ADR 的 ADR来更改决策（不得改写已接受的 ADR），且索引保持同步；变更后的结构仍可追溯到驱动因素（否则标记需要上游 PRD 修订）；处理好向下扩展的广泛影响（列明受影响的逐功能技术设计文档集合，以及变更所涉及的 api-spec/data-model/deployment/runbook）；更新文档自身的版本号，并提供变更日志（谁／何时／做了什么／为什么）。若变更范围不明确、改写了已接受的 ADR、索引不同步、未标记影响传递，或缺少变更历史，则为 缺口。（可折叠：绿地项目的首次构建不适用此条件——不要对未更改的文档进行完整的重新审查，也不要在初稿中要求提供变更日志。）
11. 能力覆盖（无能力记录时不适用）： 所有有效能力都以具名组件的形式呈现；depends_on DAG 反映在依赖关系图中。

适度原则。 “易于理解 + 无需重新推导即可确定位置”应与系统规模相称。精简的产品可以合理省去不需要的内容——一个组件 → 无拓扑图；单进程 → 无部署视图；无外部依赖 → 无弹性矩阵；无严格 NFR → §6 可以简略；无敏感数据 → 无隐私部分；初稿 → 无变更日志。评估决策是否完整以及表面积下限，而不是字数或模板章节是否齐全。满足所有适用条件的小型完整架构应予通过。不要仅因内容简短就认定存在缺漏。

第 3 步：决定结论

• 通过 — 所有适用条件均满足。新工程师能够理解系统，并在无需重新推导架构的情况下确定功能设计的位置；主要决策均有依据且已记录。即使你能想到风格上的改进，也应予以通过；标准是易于理解且可构建，而非尽善尽美。
• 要求修改 — 一个或多个条件存在明确指出的实际缺漏（未命名的外部依赖、未解释的方框、写在正文而非关联 ADR 中的决策、被改写的已接受 ADR、重述 NFR 目标却未说明实现机制、未说明故障应对方式的外部依赖、孤立结构、捏造的声明、范围未明确或修改导致连锁影响等）。

不要为了体现投入或索要锦上添花的内容而要求修改。条件要么满足，要么不满足。

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

将结论作为单独一行输出——原文 VERDICT: approve 或 VERDICT: revise，独占一行，不要添加代码围栏、引号或其他文字（此处的围栏仅作示意）：

VERDICT: approve

然后在接下来的行中列出问题。若结论为 revise，每条问题说明都必须可执行——指出未满足的条件、准确位置，以及修复方法，让作者一次性解决。若结论为 approve，可以选择提供非阻塞说明；不要让这些说明暗示必须修改。

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

要求修改 — ADR 机制（条件 4），§7 和正文：关于“我们选择 PostgreSQL 而不是 DynamoDB”的决策写在 §5 正文中，包含完整背景、备选方案和后果，但未记录为关联的 ADR。修复方法：将其移至独立的 adr/0003-datastore.md（采用 Nygard 格式），并在 §7 的决策索引中添加链接——这样该决策可以独立引用，且索引是唯一信息来源。

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

决策部分可以再精炼一些。（哪个决策？为什么不符合标准？如何修复？）

规则

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

• 只输出一行判定：VERDICT: approve 或 VERDICT: revise——该字面标记必须单独占一行，除此之外不得有任何内容。下游工具会解析它。
• 评审，不撰写。 只返回问题；不要重写、修复或补全文档。由撰写者负责修改。
• 统一评审标准。 按照第 2 步的十项条件进行评审——这与作者（authoring-architecture-doc 第 7 步）采用的标准相同。不要另设条件，也不要套用更严苛的个人标准。
• 评判结果，而非强求辅助方法。 C4/arc42/ATAM/4+1 结构、图表类型的选择，都是作者的方法——应评判是否划清了边界、决策是否关联并可追溯、各项目标是否实现，绝不要要求“使用 C4／绘制 4+1 流程视图／运行 ATAM”。（ADR 机制／NFR 实现／可观测性这些结果是条件 4/6/7 的实际要求——只有方法才属于辅助工具。）
• ADR 机制是关键要求（条件 4）。 将决策内嵌在文档中而非链接到 ADR，或改写已接受的 ADR，都是真正的缺陷（决策无法单独引用／历史记录被破坏），而非风格问题。需要查看链接的 ADR 文件才能核实——若文件缺失，应标记为无法核实，绝不可捏造。
• 根据系统核实声明（条件 9）——适用全新项目条款。 对系统现状的声明，必须根据实际代码／拓扑（file:line）确认，或标记为 unverified；绝不可捏造缺陷。若没有可供核实的代码／系统（全新项目或虚构文档），则一致性为 N/A，绝不可据此判定不通过。
• 不得误判为需修改。 若文档满足所有适用条件，即应批准，即便小型系统的文档内容较精简。只有存在真实且明确的缺陷时才要求修改。精简的架构文档可以合理地省略部署视图、消息传递、独立的可观测性章节和变更日志。
• 不得误判为可批准。 绝不可为了表示友好而忽视真实缺陷。阻塞性缺陷应判定为 revise。
• 根据文档提供的上游资料进行评审。 按照文档的 depends_on 集合以及它引用的文档／ADR 文件进行评估。尚未产出的上游资料绝不可成为要求修改的理由。若文档忽略了已产出且本应引用的上游资料，则可据此提出问题。
• 修订评审仅限于变更范围。 收到针对现有文档的变更时，应评审变更及其影响范围（条件 10）——不要完整重审未变更的架构，也不要要求全新项目的首份草稿包含变更日志。
• 每项修改意见都必须可执行——指出未满足的条件、具体位置和明确的修复方式。

偏好（可覆盖）：

• 按严重程度排列问题——先列阻塞性缺陷，再列次要问题。
• 在每项意见中注明条件编号／名称，方便作者对应评审标准。
• 批准说明应少而精，并明确指出其不阻塞批准。

易踩问题

• 为了完整而非易于理解而批准。 每个章节都可以齐全，但系统依然可能难以理解（拆分含糊、外部依赖未命名、决策埋在行文中）。判断读者能否 理解系统并将某项功能置于其中，而不是 模板是否已填写完整。
• 内嵌在正文中的决策。 一份文档若有内容丰富的“技术选型”章节，看起来很全面——但如果重要决策是连同完整背景和后果直接贴在正文中，而不是作为独立且有链接的 ADR，那么 cond-4 就不满足（无法单独寻址，也无法被取代）。这是架构文档特有的缺口，也是通用的 design-review 会漏掉的问题。
• 改写已接受的 ADR。 原地编辑已接受的 ADR（而不是用新的 ADR 取代它）会破坏决策历史——即使新内容“更好”，仍然存在 cond-4 缺口。
• 复述 NFR 目标。 只从 PRD 复制“99.9% 正常运行时间”，却没有冗余／故障转移机制，这只是复述，并未落实（cond. 6）。
• 把 ADR 机制／NFR／可观测性当成凭空添加的条件。 对于 功能规格，这些可能是凭空添加的条件；但对架构文档来说，它们是评审标准（cond-4/6/7）。不要对它们评审不足。
• 拿虚构文档对照代码验证。 Dogfood／示例架构文档描述的是一个并不存在的系统——其中的 cond-9 一致性检查不适用（绿地条款）；把“无法验证”标记为缺口是错误的。
• 凭空添加条件（主要偏差）。 增加评审标准并未要求的私有要求（“必须使用 C4 模型／绘制 4+1 视图／运行 ATAM”），会导致评审标准偏离产出标准。只根据结果评判这些技术。
• 系统性过度标记问题（误判为需修改）。 评审者被要求找问题时，往往会过度纠正。只有明确指出的真实缺陷才算缺口，而不是你会做出不同选择的决策。
• 对精简系统误判为需修改。 小型系统的架构文档本来就应该简短；省略不需要的章节（没有部署视图、消息传递、独立的可观测性或变更日志）不算缺口。
• 结论标记偏差。 “已批准”“LGTM”“需要修改”或埋在段落中的结论都无法解析。请单独一行输出字面内容 VERDICT: approve|revise。

反模式

• 敷衍批准。 为避免反复修改而草草浏览后批准——放过正文内嵌的决策或未命名的外部依赖，之后会造成缺陷或在构建中途手忙脚乱。
• 吹毛求疵地要求修改。 把措辞、图表风格或锦上添花的内容当作缺口来阻止通过。只有真正妨碍理解或构建的问题才需要修改。
• 悄悄重写。 “直接修好架构更省事”——在评审过程中动手编写，会混淆产出与评判的界限。
• 凭空添加条件。 增加评审标准并未要求的要求（指定框架、指定图表类型）——这是此关卡要防范的主要偏差。
• 对修订进行全面重评。 仅有少量改动，却重新评判整个未改动的架构——按比例评审改动及其影响范围（cond. 10）。
• 含糊的结论。 “基本批准，但是……”或给出两行结论。必须只有一个决定，并且只有一个标记。

输出

针对一份架构文档（及其链接的 ADR 文件）给出一份评审结果：

• 一行结论 — 单独一行逐字输出 VERDICT: approve 或 VERDICT: revise。
• 问题 — 若结论为 revise，则每个阻塞性缺口给出一条可执行的问题说明（未通过的条件 + 位置 + 具体修复方式）；若结论为 approve，可选择给出非阻塞性备注。

抽象的使用方是编排产出→评审循环的任何系统：approve 表示接受该架构，以便据此构建；revise 则将问题反馈给产出方，进行有限范围的修订。媒介： 当前评判的产物是文本形式的 Markdown架构文档 + Mermaid 图表 + 链接的 ADR 文件；评审标准与媒介无关。

相关内容

• authoring-architecture-doc — 这对技能中的编写端；它会按照本技能评审所依据的同一套 10 项条件标准编写架构文档。将两者配对使用，可以让标准只有一个来源，避免编写与评审的标准出现偏差。
• reviewing-technical-design — 评审低一个层级的关卡，用于评审单个功能的技术设计（该设计会说明自身在此架构中的位置）。文档不同，标准也不同。
• 一个 PRD-review 技能 — 评审高一个层级的关卡，用于评审产品需求（目标与原因、NFR 指标）。文档不同，标准也不同。
• 一个 design-review 技能 — 通用工程设计文档、RFC、独立 ADR、规格说明和计划的评审关卡（会对照代码库核实其中的声明）。本技能专门评审文档库中的 architecture-doc 工件及其关联的 ADR 文件；design-review 不负责评审该工件。
• 在适用时，api-spec / data-model 是架构在结构上引用的契约；cond-2 会检查文档是否保持在合适的层级（进行引用，而不是逐项列举）。
• architecture-doc / ADR 模板 / content-template 工具负责定义章节结构；本技能评审的是质量是否达标，而非结构是否符合规范。

渐进式披露

• references/architecture-quality-bar.md — 对十项检查条件逐项展开说明，包括通过/缺口信号和具体评审发现示例（边界与关注点覆盖检查、层级测试、图表同步检查、ADR 机制信号［嵌入式决策 + 重写已接受的 ADR + 索引同步］、驱动因素与备选方案测试、每个目标的实现方式 + 可衡量场景信号、横切关注点/可观测性信号、ASR 覆盖检查、对照实际情况核实 + 绿地项目信号，以及限定差异范围的修订信号）。当某项条件处于边界状态、需要更明确地判断通过或存在缺口时加载。
• references/sources.md — 评审方法的研究依据（C4/arc42/ISO 42010、ADR 实践、SEI 质量属性场景 + ATAM、弹性模式、持续更新的架构文档）。

正文预算

• description ≤ 1,024 个字符（agentskills.io 上限）；列表中合并后的 description + when_to_use 会在 1,536 个字符处截断。
• 正文约 500 行 / 5,000 个 token（软性目标 — 质量优先；如果持续超过 700 行 / 7,000 个 token，则标记提醒）——每轮都会保留在上下文中。
• 每个参考文件：超过 10k 个 token 时警告，超过 25k 时报错。参考文件总量：超过 25k 个 token 时警告，超过 50k 时报错。