authoring-architecture-doc

authoring-architecture-doc — SKILL.md

变体： standard · 使用时机： 根据已批准的 PRD 编写完整系统架构文档，使新工程师能够理解系统，并能将某项功能的技术设计置于其中。

概述

这项技能讲解的是如何编写高质量的完整系统架构文档——重点在于编写者应如何判断，而非章节列表。它假设有三种协作者：提供章节结构的架构文档模板工具、提供独立决策记录格式的ADR 模板工具，以及用于根据证据和既有实践为各项选择提供依据的深度研究能力。编写者拿到的是已批准的 PRD + 产品方向（范围、用户角色、非功能目标），并在此基础上展开阐述，绝不使用泛泛的模板内容。文档聚焦于整个系统：整个系统所依托的组件、拓扑、边界、技术以及 NFR 实现方式。达标的标准是：新工程师能够理解系统结构及其主要决策背后的原因，而某项功能的技术设计也能在其中找到定位。

何时启用

• 根据已批准的 PRD，为系统或产品编写新的架构文档。
• 将简略的产品方向扩展为完整系统架构（规模应与产品相称）。
• 使用经过研究、决策完备的内容填写架构文档模板，并将关键决策记录为关联的 ADR 文件。

请勿在以下情况启用：

• 审查或评估已完成的架构文档 → 使用 reviewing-architecture-doc，即专用审查技能（而非通用设计审查；架构文档产物不属于其范围）。
• 设计单项功能的实现 → 使用技术设计（TDD）技能；它关注的层级更低，并会引用本文档。
• 规定线协议契约（每个端点）→ 使用 API 规范技能；规定持久化模型（每张表）→ 使用数据模型技能。本文档从结构层面说明主要服务接口和数据存储，而非详尽罗列。
• 编写无需架构文档的一句话说明或微小变更。

输入

阅读计划交给你的每一份文档——即你的 depends_on 集合（上游文档，由 discovery 确定会为本文档提供信息）——并将本文档内容追溯到这些文档。不要假设输入固定不变：本技能列出的典型上游文档只是方法指引，并不限制你实际收到的内容。务必做到自包含——根据你实际获得的任何上下文编写文档；如果预期提供信息的文档缺失，就基于现有内容继续，并将缺失明确列为假设，绝不可捏造内容来填补。并且，在有研究能力可用时务必使用（deep-research），确保文档全面详尽，而不只是填满模板。

能力上下文（如已提供）： 如果调用方注入了 capability_record（来自 capability-map.yaml product_capabilities 的记录），请在 Step 1 之前阅读。它定义了你的范围边界：owns = 你负责涵盖的实体；refs = 你会引用但不负责的实体；publishes/consumes = 你需要说明的事件；entry_points/exit_points = 用户如何进入和离开；has_ui/has_api/has_persistence = 适用的界面。若存在此记录，必须将其视为硬性约束，不得超出其定义的边界。

工作流

第 1 步：沿用模板工具提供的结构——不要自行编造大纲

从架构文档模板工具（综合版）获取章节结构，并从 ADR 模板工具获取独立的决策记录格式。此处不要重述或重新推导章节列表；本技能提供的是如何填充这些章节的方法。如果没有可用模板，请获取一套全面的架构结构（请求或创建一套，或改用规范的架构文档章节集）和规范的 ADR 格式，然后继续。

如果注入了所有能力记录：使用完整能力列表进行组件分解，并将 depends_on DAG 作为依赖关系图的输入。使用分类字段（scale、security、infrastructure）来构建 NFR 框架。

第 2 步：加载 PRD 和方向；发现差距；着手完善内容

阅读已批准的 PRD 和产品方向。起草前，先填补知识空白——范围所需的实际组件、外部依赖、实际使用的技术栈，以及 PRD 设定的 NFR 目标。每个组件、边界和决策都必须追溯到这个产品，而不是泛泛地套用模板。如果输入信息不足，请明确列出假设（作为待解决问题或明示的假设），绝不要默默采用通用内容。

第 3 步：开展研究，让每项选择都有成熟实践依据

通过深入研究，让结构以成熟的架构实践为依据（例如公认的文档模型，如 C4、广为人知的参考架构，以及项目实际使用的技术栈），而非凭空编造。研究具体领域和候选技术，而不是泛泛地研究“架构”。如果没有可用的研究能力，就不要捏造拓扑结构、基准测试或理由——应将未经研究的选择标记为待验证的假设。

第 4 步：采用各章节方法（在标题基础上的增量）

按照此方法填写模板的各个章节：

• 先明确边界。 在介绍任何组件之前，先划定范围：包含哪些内容，明确不包含哪些内容（以及由谁负责），涉及哪些参与者，以及每项外部依赖提供什么（用一句话说明）。边界是新读者首先需要了解的内容。
• 干系人与关注点（覆盖主线）。 识别干系人及其各自关注点（ISO/IEC/IEEE 42010），然后确保后续章节／视图涵盖每一项明确列出的关注点——这是检验文档是否覆盖全部关注点的标准，而不是凭感觉判断。按比例确定：规模较小的产品，干系人与关注点较少；关键在于“没有明确列出的关注点未得到回应”，而不是必须制作矩阵。
• 每个组件只承担一项职责。 将读者之后会遇到的每个主要组件／服务列出一次，并说明其单一职责和类型（服务／数据存储／客户端／工作进程／队列）。后续不得出现未解释的方框。
• 每条箭头都说明协议；图示与叙述保持一致。 在拓扑中说明哪些组件彼此通信、通信方向以及通信方式（同步请求／响应，还是异步事件／消息）。图中的每个方框和箭头都必须在文字中说明，反之亦然——不得出现孤立元素；只有在运行时流程不明显时才添加时序视图。
• 说明每个边界的故障语义。 对每个集成接口：说明跨接口传递的内容（链接到 API 规范／数据模型，不要直接嵌入架构定义）、通信方式、谁负责维护契约以及契约如何进行版本管理，以及对端响应缓慢或不可用时会发生什么（超时／重试／回退／降级）。
• 说明重要技术选择的理由。 只讨论读者可能会提出疑问，或会影响架构的选择（运行时、数据存储、消息传递、托管／框架），无需列出每个库。每项选择都要说明其服务的驱动因素（需求或非功能需求），以及相较于哪些方案被选中。如果注明“团队默认”，也可以接受。
• 为每个非功能需求目标说明实现方式。 PRD 负责定义目标；架构负责说明实现方式。 对每项质量目标——可扩展性、可用性、安全性、可观测性、部署拓扑——记录满足目标的机制。只重述目标而不说明机制，就存在缺口；没有目标支撑的机制，则可能是过度设计。对于关键目标，应将其量化为质量属性场景（来源／刺激／制品／环境／响应／响应度量）——响应度量（“在 1000 rps 下，p99 < 200ms”）是可测试的约束；对于简单系统，普通文字说明即可。
• 将可观测性视为一项首要系统关注点。 不要停留在“我们会记录日志”——明确说明运维人员用于诊断生产环境系统的系统级信号（金牌信号、健康状况／SLO 监控策略、关键指标／跟踪／告警）。这是系统层面的能力，与单项功能的信号不同（后者属于 TDD 的关注点）。
• 明确说明质量属性之间的权衡。 当两种属性相互冲突（延迟与一致性、成本与可用性、安全性与性能）时，说明权衡取舍、最终选择及其原因（采用 ATAM 的敏感性／权衡表述方式）。架构明显面临某种矛盾，却始终未予说明，即是一个缺口。
• 立足实际，不要凭空杜撰；明确指出缺口。 如实反映实际产品与技术栈；将未知事项列为明确的假设／待解决问题，而不是自行编造答案。

第 5 步：将每项关键决策记录为独立且带链接的 ADR（核心机制）

架构决策不会内嵌在正文中。 将每项重要决策记录为独立的 ADR 文件（每个文件记录一项决策，使用 ADR 模板，包含 Status / Context / Decision / Alternatives / Consequences），并且只在架构文档中保留一个摘要索引，其中链接到各个 ADR。具体原则：

• 每个文件记录一项决策。 将两项决策合并记录是错误的——应拆分。
• 追溯依据 + 备选方案。 每项决策都应追溯到一个驱动因素（需求或 NFR），并列出一个实际备选方案及其落选的权衡。没有考虑过备选方案的决策，显得未经审慎考量。
• 接受后不可更改。 决策变更时，应创建一个新的 ADR 来取代旧 ADR（旧 ADR 的 Status 改为 "superseded by …"）；不要重写已接受的记录。这样可以让索引成为忠实的、只追加不修改的历史记录。
• 索引与文件保持同步。 索引中的每项决策都应有有效的 ADR 链接；每个已接受的 ADR 都应出现在索引中。索引不同步就是缺陷。

第 6 步：修订已批准的架构文档（增量路径）

架构文档是动态文档——通过增量变更而非重写来演进。当收到一份已批准的文档及变更请求（新的重要决策、组件拆分/合并、依赖替换、NFR 目标调整）时，不要重新生成整份文档。具体做法：

• 将变更限定在受影响的决策 / 组件 / 边界 / NFR 实现 / 横切原则，并在原处修改，同时保留稳定的章节 / 决策 ID 和评审历史。
• 决策变更应通过取代旧决策实现，绝不能就地编辑。 决策变更时，应创建一个新的 ADR 来取代旧 ADR（旧 ADR 的 Status → "superseded by NNNN"，并添加互为对应的 "supersedes NNNN" 注记）；决策索引也应更新，以反映新的 ADR 和旧 ADR 的取代状态。重写已接受的 ADR 是修订时最严重的缺陷——这会破坏历史记录。
• 重新梳理内部链条。 拓扑结构是否仍然成立；图示是否仍与正文一致；NFR 实现是否仍满足目标；受影响边界的故障语义是否仍有说明？
• 更新文档自身的版本号和变更日志（谁 / 何时 / 做了什么 / 为什么——指生成的文档中的 Version，与此技能的语义化版本号不同）。
• 分析由下至上的广泛影响。 架构文档特有的影响范围是下游各功能技术设计文档：这些文档将自身定位于已变更的结构中（每份文档都可能需要单独修订），以及变更所涉及的 api-spec / data-model / deployment / release-runbook。上游方面：由需求驱动的变更意味着应先修订 PRD / 产品方向（遵循 spec→plan→impl 顺序）。标明每份受影响的下游文档；切勿让它们在未告知的情况下过时。

第 7 步：交付前依据可用性标准进行自检

确认以下各项均满足（这是专职审查者 reviewing-architecture-doc 所坚持的标准；这 10 项条件以此检查为唯一来源）：

1. 结构易于理解；涵盖边界和关注点 — 新工程师阅读上下文、组件和拓扑后，能够说明系统是什么，以及各部分如何配合；明确说明边界（范围内/外及负责人），列出所有外部依赖，并通过某个章节/视图回应每项已识别的利益相关方关注点。
2. 明确命名组件和边界，并说明职责 — 每个主要组件和集成边界都有明确名称，并说明其职责/跨越边界的内容。无法解释的方框或分界均不合格。保持在全系统层面（不是功能 TDD 细节，也不是 API 规范/数据模型枚举）。
3. 图示与叙述一致 — 每个方框/箭头都在文字中出现，反之亦然；图示可独立理解；在运行时/部署视图起关键作用时，必须提供该视图。
4. 关键决策以独立 ADR 文件形式记录、建立索引且不可变 — 每项重要决策都必须是单独的 ADR 文件（每个文件一项），并在索引中提供有效链接；索引与文件保持同步；已接受的 ADR 绝不重写（变更通过后续 ADR 取代）。将完整记录嵌入文档、索引没有链接，或重写已接受的 ADR，均不合格。
5. 说明重要技术选择的理由 — 每项选择都必须附有理由（驱动因素及其胜过的实际替代方案）。未说明理由的重要选择不合格。
6. 每个 NFR 目标都有实现机制；明确权衡 — PRD 中提及的每个质量目标都有已记录的实现机制（在起关键作用时提供可衡量的场景）；明确并解决质量属性之间的权衡。仅重述目标而没有实现机制，不合格。
7. 在系统涉及的范围内处理横切关注点 — 说明每个集成边界的弹性策略、安全（信任边界/身份验证/密钥）、敏感数据流经之处的隐私，以及系统级可观测性策略。
8. 覆盖需求/ASR — 每项架构重要需求都有对应的实现结构/决策；不存在无对应需求的结构。便于下游使用：功能的技术设计无需询问作者，即可确定自身在架构中的位置。
9. 基于实际情况，而非套用模板；明确说明假设；与现实一致 — 结构/技术应反映实际产品，并以成熟实践为依据；将未知项列为假设/待解决问题（绝不默认为既定事实，也不捏造）；关于系统现状的描述必须与真实代码/拓扑一致。
10. （仅限修订）变更范围明确 — 对于变更请求，明确界定变更范围并在原文中编辑；通过后续决策替换已变更的决策（并保持索引同步）；更新文档版本和变更日志；标明对下游内容（相关 TDD 及 API 规范/数据模型/部署）的影响。绿地项目的首次构建不适用此项。

所有条件均应遵循比例原则： 精简的产品可以合理地省略其不具备的内容（一项组件 → 无需拓扑；单进程 → 无需部署视图；没有严格的 NFR → §6 可从简；初稿 → 无需变更日志）。不可省略的基准：不捏造信息、明确边界和外部依赖、保持在全系统层面、绝不重写已接受的 ADR，以及为每个实际存在的目标提供实现机制。

规则

硬性规则（绝不违反）：

• 组合，不要重复。 章节结构取自模板工具，决策记录的格式取自 ADR 模板工具；本技能负责填充这些内容。不要粘贴与之竞争的大纲。
• 决策应链接，不应内嵌。 每项重大决策都应单独记录在一个 ADR 文件中；文档中只保留带链接的索引。绝不要内联完整的决策记录。
• 一个组件只承担一项职责，一个 ADR 只记录一项决策。 不要留下没有说明的框，也不要在一条记录中打包两项决策。
• 论证重大选择。 没有理由（驱动因素 + 替代方案）的重大技术选择，就不算完成。
• 落实每项 NFR 目标。 PRD 负责定义目标；仅仅重述目标而没有实现机制，就是缺口。这里绝不要设定目标。
• 保持在全系统视角。 从结构上说明主要数据存储和服务接口；不要逐一列出所有端点（API-spec）或所有表（data-model），也不要偏离到某个功能的实现设计（technical-design）。
• 绝不捏造。 不要为了填充某个章节而虚构拓扑、基准测试、供应商声明或理由。将未知项标记为待验证的假设。虚构机制比坦诚承认缺口更糟。
• 详述给定输入。 具体内容应来自 PRD + 研究，而非通用套话。
• 确保图示与叙述一致。 图示中的每个元素都要在文字中说明，反之亦然。
• 按增量修订并标记取代关系，绝不重写。 收到变更请求时，界定增量范围并就地修改；通过新的 ADR 取代原决策（绝不修改已接受的 ADR），保持索引同步，更新文档版本 + 变更日志，并指出对下游 technical-design 文档 + api-spec/data-model/deployment 的影响。
• 能力边界（提供了 capability_record 时）。 文档内容范围应受该记录的边界约束。生成边界之外的内容（把 refs 实体当作自身拥有的内容来描述；设计越过 exit_point 的流程）属于范围违规，等同于虚构规范中不存在的内容。

偏好（可覆盖）：

• “全面”决定输出的目标水准，但仍要适度——完整覆盖决策 + 达到内容广度底线，而不是追求字数。精简产品可以合理地省略不需要的章节（例如只有一个组件、没有消息传递机制、部署也很简单）。
• 在当前媒介中以文字呈现所有内容——叙述 + 组件/容器/部署图 + 决策索引表；未来改用设计工具后端，只会改变媒介，不会改变方法或标准。
• 优先采用能够传达结构的最少图示（通常上下文视图 + 容器/拓扑视图就足够）；仅在运行时行为不明显时才添加时序视图。

易错点

• 内嵌决策。 在文档中粘贴完整的背景/替代方案/后果，而不是链接到 ADR，会导致每项决策无法单独寻址且文档臃肿——应建立索引并链接到独立 ADR 文件。
• 修改已接受的 ADR。 重写已接受的决策会破坏历史记录——应编写新的 ADR 来取代它。
• 没有说明的框。 图示中出现了组件，却没有说明其职责——应在组件章节中说明一次。
• 重述目标。 将 PRD 中的“99.9% 正常运行时间”复制到文档，却没有冗余/故障转移机制，这只是重述，并未落实——每项目标都要说明如何实现。
• 对精简产品过度设计。 为一个 CLI 工具臆造消息总线、缓存层和三个环境——应根据实际范围确定规模；无法服务任何目标的机制就是警示信号。
• 偏离视角。 开始描述“这个函数调用那个类”（feature-TDD）或“GET /v1/users 返回……”（API-spec）——应保持全系统视角；说明接口并链接到契约。
• 图示/叙述不一致。 叙述中描述了图示未包含的 worker（或反之）——两者必须一致。

反模式

• “我自己来写大纲。” 这会重复模板工具的内容——从模板工具获取结构，从 ADR 模板工具获取 ADR 形式。
• “我会在这里用一个章节列出决策。” 这会把本应独立并链接的 ADR 嵌入文档中——每个决策单独成文，编入索引并添加链接。
• “技术栈无所谓；我会选个合适的。” 这是缺乏依据的重要选择——每项选择都需要有驱动因素和真正的替代方案，并以实际产品为依据。
• “PRD 说 p99 要达到 100ms，所以我就把它写下来。” 重述目标不等于实现目标——要记录实现目标的机制。
• “我会加个队列和缓存，以防万一。” 这是为假设性需求添加推测性结构——应根据产品的实际范围确定规模。
• “跳过研究吧，我懂架构。” 研究能以成熟实践为依据，确定这个产品的拓扑结构和技术选型——而不是讲解架构理论。
• “我会详细说明每项功能的构建方式。” 那属于更低层次的技术设计文档——本文档定义整个系统的结构，其他文档将在该结构内展开。

输出

一份全系统架构文档，达到Step 7 可用性标准（结构易于理解并覆盖各项关注点；明确组件和边界及其职责；图示与叙述一致；关键决策以独立、不可变的 ADR 形式记录，并在索引中链接且保持同步；技术选型有依据；每项目标非功能需求都有实现方案并说明权衡；覆盖横切关注点；满足架构决策记录（ASR）覆盖要求；基于实际情况而非套话，且与现实一致；可增量修订），并附上一组由文档的关键决策索引链接的独立 ADR 文件。抽象使用者包括所有在系统内开发的工程师、下游的各功能技术设计文档（这些文档会说明自身在架构中的位置），以及 reviewing-architecture-doc（它会按照同一套 10 项条件标准进行审核）。文档的结构来自模板工具；此技能负责提供内容质量和决策记录机制。

相关内容

• 架构文档模板工具（例如内容／模板网关）——提供全面的架构章节结构，由此技能填充内容。
• ADR 模板工具——提供独立决策文件使用的决策记录格式（Status / Context / Decision / Alternatives / Consequences）；没有单独的决策编写技能，因为这种格式是固定的。
• 深度研究能力——以成熟实践和证据为依据，确定结构和技术选型。
• 上游的 PRD + 产品方向——这是此技能展开阐述的输入背景（范围、用户角色、非功能需求目标）；绝不是一张白纸。
• 下游的各功能 技术设计文档——这些文档会说明自身在此架构中的位置。
• reviewing-architecture-doc——专门的审核工具，负责检查此技能的 Step 7 标准（包含 10 项条件的门槛，与自检标准保持一致），并输出 VERDICT: approve|revise。完成的架构文档（及其链接的 ADR 文件）应提交给该工具审核——而非通用的 design-review；后者不负责架构文档产物（但仍负责审核通用设计文档、RFC、独立 ADR、规格说明和计划）。

渐进式披露

• references/architecture-method.md——边界与关注点／分解与拓扑结构／图示同步／ADR 机制／非功能需求实现与可衡量场景／可观测性与韧性的详细说明（填写这些章节时加载）。
• references/amend.md——基于替代约定的修订流程、索引同步和自上而下的广泛影响（修订已批准的文档时加载）。
• references/sources.md——方法、ADR 机制和质量标准的研究溯源（仅在审核指导依据时加载）。

正文篇幅限制

• description ≤ 1,024 个字符（agentskills.io 上限）。
• 正文约 500 行 / 5,000 个词元（宽松目标——质量优先；如果持续超过 700 行 / 7,000 个词元，请标记）。
• 大量内容放在 references/ 中，按需加载。

更新日志

• 1.3.0（2026-06-21）— capability_record 上下文注入：可选地注入调用方提供的全部 capability 记录，并在步骤 1 中使用（基于完整列表进行组件分解、depends_on 有向无环图、分类字段）；新增 capability_boundary 规则；放宽正文篇幅限制，改为目标值。未注入任何记录时可平稳回退。
• 1.2.0（2026-06-14）— 面向生产环境的重构：新增迭代/修订方法（步骤 6——差异 + ADR 替代 + 自上而下的广泛影响）、干系人/关注点覆盖主线、可衡量的质量属性场景、将可观测性作为一等系统关注点，以及质量属性权衡；扩展自检（步骤 7），纳入与新的专用评审者 reviewing-architecture-doc 共用的 10 项条件标准；将评审交由配套工具处理（设计评审从架构文档制品中单独划出）。此版本为增量更新——此前的整套方法（边界优先、单一职责组件、独立关联的 ADR 机制、论证重大选择、每项 NFR 对应一个实现方案、图文同步、层级规则）均保持不变。
• 1.1.0（2026-06-04）— 此前已评审的版本。