authoring-technical-design

authoring-technical-design — SKILL.md

变体： standard · 适用时机： 为一个功能/组件设计如何编写技术设计文档（或修订已获批准的文档）——达到工程师无需重新推导设计即可据此实现的标准。

概述

这项技能讲解如何编写一份优秀的技术设计文档（TDD）——针对现有系统中的一个功能或组件的详细实现设计。PRD 说明产品做什么，功能规格说明说明每项功能如何表现；TDD 则说明如何构建这项功能——包括选定的方案、各组件及其职责、控制流与数据流、关键接口、重要逻辑、故障模式、横切关注点（安全/隐私/可观测性）、权衡过的备选方案、测试和发布。这项技能承载撰写者的判断——一种设计研究方法和一项可实现性标准——而非章节列表。它假定有两位协作者：一个提供章节结构的技术设计模板工具，以及一个以证据为设计提供依据的深度研究能力。撰写者会收到已批准的 PRD + 功能规格（以及在存在时提供的架构文档 + API 规格 + 数据模型），必须详细说明如何构建这项功能——绝不能只输出通用框架。需要达到的标准是：工程师无需重新推导设计即可根据文档实现该功能，并且选定的方案至少与一个真实备选方案进行了比较论证。这项技能的标准与其评审关卡 reviewing-technical-design 保持单一来源，作者应严格以关卡要求为目标，避免偏离。

何时启用

• 为一个已编写功能规格的功能/组件撰写 TDD，设计如何在现有系统中构建它。
• 决定并记录实现方案：组件分解、控制流/数据流、接口、详细逻辑、故障模式、可观测性、测试和发布。
• 修订已获批准的 TDD，以版本化增量记录（例如，选定方案在开发过程中被证明不可行、功能规格中的行为得到修正，或出现新的故障模式）——见步骤 6。
• 填写技术设计模板，提供经过研究、决策完整且可追溯到功能需求的内容。

请勿在以下情况启用：

• 设计整个系统的结构、服务拓扑或长期技术选型 → 这属于更高层级的架构文档。TDD 设计的是该架构内的一个功能，并引用架构文档。
• 编写API 契约（线路/端点接口）或数据模型（持久化架构）本身 → 这些各有独立文档，TDD 只引用它们，绝不重复。
• 编写 PRD 或功能规格 → 它们是此处的上游输入。
• 评审或评分已完成的 TDD → 请使用 reviewing-technical-design。

输入

阅读计划交给你的每一份文档——即 depends_on 集合（通过上游文档发现流程确定会为本文档提供依据的文档）——并将本文档内容追溯至这些文档。典型的上游文档包括已批准的 PRD + 功能规格（以及在存在时提供的架构文档 + API 规格 + 数据模型）；这些是方法指导，而非你所能收到材料的上限。请做到自包含——根据你实际收到的所有上下文编写文档；如果缺少预期的依据文档，请基于现有信息继续，并将这一缺口明确列为假设，绝不可编造内容填补。并且在具备研究能力时，使用研究能力（深度研究）让文档全面、详尽，而不仅仅是填充模板。

工作流

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

从你的技术设计模板工具（全面版）中获取章节结构。此处不要重述或重新推导章节列表；本技能提供的是填充这些章节的方法。如果没有可用模板，请获取（请求或编写）一份全面的技术设计结构，然后继续。此类文档的关键章节——背景/问题、需求追踪、选定方案 + 组件分解、控制流 + 数据流、接口/契约、详细设计、错误处理、横切关注点（安全/隐私 + 可观测性）、备选方案、测试、发布/迁移、版本管理/变更日志——均由模板提供；你的工作是确保填入其中的内容质量。在生成的文档中标注模板的 template: technical-design 前置元数据——这是 reviewing-technical-design 用来识别的激活信号。

步骤 2：加载上游文档；依据需求推进设计

阅读已批准的 PRD + 功能规格——它们是你的输入，而不是一张白纸；如果存在，也要阅读架构文档（功能必须融入的系统）、API 规格和数据模型。功能规格中的需求和验收标准是你的覆盖检查清单：追踪必须双向进行——每项需求都要有对应设计（不得有覆盖缺口），每项设计决策也都必须追溯到某项需求（不得有无需求支撑的决策/范围蔓延）。如果上游文档内容不足，请将缺口明确列为待解决问题或已说明的假设，绝不要默默采用默认值。如果无法依据现有信息可信地完成某项功能设计，请将其标记为阻塞项，而不是自行编造。

步骤 3：通过研究为设计提供依据

开展深入研究，从两个方面为设计提供依据：（a）成熟的工程设计实践——设计文档 / RFC 这一文档类型如何处理此类问题（采用经过验证的模式，而非自行发明）；（b）项目的实际约束——功能所接入的现有架构、技术栈和代码。设计应顺应现有基础。如果没有研究能力，切勿捏造方案、限制或接口——应将其明确标记为假设，并注明须在构建前验证。

第 4 步：按章节应用设计方法

按照此方法填写模板中的各个章节。精简功能不需要的章节（没有并发就不写并发相关内容；没有持久化变更就不写迁移；简单的内部辅助工具只需轻量级可观测性）。每个方面的详细内容见 references/design-method.md 和 references/failure-test-rollout-amend.md。

• 背景 + 需求追溯 — 在功能层面说明功能及其要解决的问题；通过链接引用更深入的材料，而不是直接展开。列出设计必须满足的需求，并将每项需求双向追溯到 PRD 目标／功能规格标准／约束。没有需求支撑的设计决策属于范围蔓延；没有设计对应的需求则属于覆盖缺口。区分目标与非目标——即那些合理来说可以成为目标、但经过审慎考虑后决定排除的事项（明确列出，让评审者知道这是有意为之）。
• 所选方案 + 组件分解 — 先简要概述，再将方案分解为各自只承担一项职责的组件／模块及其协作者。将它们置于现有系统中——引用架构文档说明周边结构，不要重新绘制。保持在功能／组件层级。
• 控制流 + 数据流 — 用图表呈现主要运行路径，并逐步叙述；确保图表与文字描述保持一致。此处说明成功路径；失败情况放在错误处理中。
• 关键接口 + 契约 — 给出功能新增或变更的签名／消息结构／事件，作为契约而非实现。对于已由 API 规格或数据模型规定的内容，只需引用并说明差异——绝不能重复列出端点或重新声明架构（重复内容会逐渐偏离）。
• 详细设计 — 只说明不显而易见且影响重大的逻辑：核心算法、持有的状态及其转换，以及并发／顺序／幂等性方面的考量。简单的 CRUD 无需展开说明。
• 错误处理 + 失败模式 — 列出每种失败（输入错误、依赖项失败／超时、部分失败），说明其检测方式、处理／恢复方式及对用户可见的影响，并明确重试／超时／幂等性策略。不能只写成功路径。
• 横切关注点 — 安全与隐私： 功能的身份验证／授权／机密信息（引用存储位置，绝不内嵌机密信息）、不可信输入的入口，以及涉及的个人身份信息（PII）／保留期限／数据分类；规模与限制： 功能在 10×/1000× 规模下的行为——逐项操作还是整集合操作、无界增长、热点路径；对于影响重大的方面，明确说明应对策略；可观测性（首要考虑，而非事后补充）：列出要发出和监控的健康状况／故障信号——成功／错误指标、关键日志／跟踪，以及针对主要故障模式的告警——这些信号也用于触发回滚。没有相关影响面的关注点标注为 N/A。
• 考虑过的替代方案 — 至少提出一个真实且非稻草人式的替代方案，即有能力的工程师确实可能选择的方案；说明其权衡和最终决定所依据的判断标准。只盖章认可单一方案是一种危险信号。
• 测试方法 — 说明单元／集成／端到端测试覆盖、上述失败情况，以及功能对外提供的任何契约的符合性测试；引用功能规格的验收标准，不要重述。
• 发布、迁移 + 风险 — 说明如何发布（分阶段／功能标志／金丝雀），迁移及向后兼容策略，带有可衡量触发条件的回滚计划（与可观测性信号关联，而不是“如果看起来不妙就回滚”），以及剩余风险和待解决问题。

步骤 5：交付前，根据可实现性标准进行自检

确认以下各项均满足——这是 reviewing-technical-design 所要求的标准（作者和审核门槛共用同一标准，避免标准偏移；审核门槛的 11 项条件与以下内容一一对应）：

1. 需求追溯完整且双向——每项需求都已列出并追溯到来源；每项决策都能追溯到需求；没有孤立的决策，也没有未覆盖的需求。
2. 范围限定为一个功能／抽象层级恰当——在架构范围内设计一个功能／组件；引用系统级结构，但不重新设计。
3. 方案与拆分可实现——组件及其职责具体到足以进行构建；控制流和数据流既以图示展示，也有文字说明，且二者一致。
4. 引用而非重复——API 规范／数据模型／架构文档已定义的接口和数据接触点，只需引用并说明差异；不得内联重复内容。
5. 至少有一个真实备选方案，并明确决策标准——通过权衡比较一个真正可行（而非稻草人）的方案，并说明最终决策所依据的标准。
6. 处理故障模式——列出重要故障，并说明为其设计的检测与处理／恢复方案；在适用时，处理并发／幂等性以及安全／规模／隐私方面的影响。
7. 处理可观测性——明确列出健康状况和故障信号，并将其用于触发回滚。
8. 处理测试——以可测试的方式说明验证方案，包括故障情况和任何契约一致性检查。
9. 处理发布／迁移／回滚——说明如何发布、如何迁移并保持向后兼容，以及如何根据可衡量的触发条件进行回滚。
10. 假设明确且有依据——将每项未知因素列为假设／开放问题，而非默默设为默认值；设计应反映此功能的具体情况和真实的周边系统，不得凭空捏造。
11. 处理修订（适用于修订情况）——对已批准的 TDD 进行增量修订时，限定修订范围、更新版本和变更日志、标记已被取代的内容，并分析影响范围（步骤 6）。

输入不足时的门槛：如果现有信息不足以设计某项功能，甚至无法做出可信的假设，应将其列为阻塞项（“设计信息不足——需要架构／产品决策”），而不是用臆造的方案敷衍了事。

步骤 6：修订已批准的 TDD（增量修订路径）

收到已批准的 TDD 和变更请求（而非空白功能需求）时，应在原文档中以带版本的增量修订方式进行修改——不要重新生成整份文档。完整流程见 references/failure-test-rollout-amend.md；方法如下：

• 限定变更范围，仅修改受影响的设计决策——组件职责／接口契约变更／故障模式及处理方案／发布步骤／备选方案及决策标准。只修改这些内容，其余内容保持不变。
• 重新梳理所修改部分的内部链路——修改后的决策是否仍能追溯到需求；其故障模式／可观测性／测试／发布方案是否仍然成立；备选方案的决策标准是否仍能支持该选择。
• 分析双向影响及 SSOT 影响范围：上游——若变更由需求变更引起，应先修订 PRD／功能规范（遵循先修改上游文档、再修改下游文档的顺序）；内部——重新梳理上述链路；下游及 SSOT——若变更涉及契约，应由负责该契约的 api-spec／data-model 自行修订（TDD 仅说明差异），并更新基于 TDD 编写的实现／测试计划／发布运行手册的引用。
• 更新版本和变更日志——提升所产出文档自身的版本，并添加变更日志条目（谁／何时／变更内容／原因）。
• 标记已被取代的决策（注明取代它的内容，并添加对应说明），不要悄然删除。

规则

硬性规则（绝不违反）：

• 每项决策都必须追溯到一条需求，反之亦然。 每项设计选择都必须有对应的 PRD／功能规格条目；每条需求都必须有对应的设计。
• 引用，不要重复。 由 API 规格／数据模型／架构文档定义的接口、架构和系统结构，应当通过引用说明，仅阐述差异。在 TDD 中内嵌这些内容会导致其与事实来源产生偏差。
• 至少提供一个真实的替代方案。 比较一个真正的替代方案及其权衡，并说明决策标准。用稻草人方案或只列出一个未经权衡的选项，都不符合要求。
• 每种故障模式都必须说明处理方式。 只列出故障，却不说明如何检测和恢复，不算完成。
• 可观测、可回滚。 面向生产的功能必须说明健康状态／故障信号，以及带有可衡量触发条件的回滚方案。“以后再加日志”／“看起来不好就回滚”不符合要求。
• 绝不编造设计。 不要为了让文档看起来完整而虚构方案、限制或接口。缺少依据时，应将其标为明确标注的假设，并在构建前验证。
• 组合，不要重复大纲。 采用模板工具中的章节结构；本技能负责填充该结构。不要另行粘贴一份大纲。
• 设计一个功能，而不是整个系统。 聚焦于功能／组件层面；系统级内容一律引用架构文档。
• 修订，不要重写。 对已批准的 TDD，应以范围明确、版本化且分析过影响的增量进行修改，而不是重新生成。
• 必须可实现。 不要交付需要工程师重新推导才能构建的设计。

偏好（可覆盖）：

• “全面”决定输出的目标，但仍需适度：应确保关键决策完整，而不是一味追求篇幅。设计文档通常较短；小型功能可省略不需要的章节。
• 消息交互优先使用时序图，决策／数据流优先使用流程图；每张图都应配有编号说明。
• 详细逻辑应使用围栏式伪代码表达（即契约／算法轮廓），而不是最终实现。

注意事项

• 设计系统，而不是功能。 重新绘制服务拓扑或重新决定数据存储属于架构工作，层级更高。引用相关内容；只设计其中的一个功能。
• 内联 API 或架构。 粘贴端点列表或表的 DDL 会重复 API 规范／数据模型，并且其中任一内容变更时就会过时。链接到对应的文档，只说明该功能所需的差异。
• 稻草人式替代方案。 “替代方案：什么都不做／全部重写”不是真正的权衡。替代方案必须是有经验的工程师确实可能选择的设计，并说明将其排除的标准。
• 只设计理想路径。 永不失败的流程不算经过设计。列出故障模式及其恢复方式——实现缺陷往往藏在这些地方。
• 事后才考虑可观测性。 “以后再加指标”会让功能无法运维，也无法安全回滚。将信号纳入设计。
• 图表与文字描述不一致。 如果时序图显示了叙述中未提及的步骤（反之亦然），读者就只能靠猜。保持两者一致。
• 照抄模板大纲。 在内容（或本技能）中重新推导章节列表，会重复模板工具的内容，并逐渐与之不一致——应根据判断填写各章节。
• 修订时重写。 仅修改一个决策却重新生成整份 TDD，会丢失评审历史和稳定的决策 ID。只编辑变更部分；为其添加版本号和变更日志。

对比示例——表面合规的模糊描述与可实现的描述（用它来自检）：

方面	模糊／无法构建（拒绝）	可实现（交付）
需求追溯	“这是对导出功能的设计。”	“设计 feature-spec §3.1 CSV 导出；满足验收标准‘10k 行数据的导出在 < 5s 内完成’。”
分解	“一个导出器组件负责导出。”	“ExportJob（负责排队并跟踪状态）将行流式传输委托给 RowSerializer；通过现有的 ReportQuery 端口读取——参见 architecture-doc §Reporting。”
接口	“它调用报表 API。”	“复用 GET /reports/{id}/rows（api-spec §Reports）；此功能只新增 format=csv 查询参数——差异已在该文档中注明。”
替代方案	“我们选择了最佳方案。”	“选择流式传输而非缓冲：缓冲更简单，但超过约 50k 行时会发生 OOM；选择标准 = 在 10k 行的目标规模下将内存用量限制在固定范围内。”
故障模式	“会处理错误。”	“如果 ReportQuery 在流式传输过程中超时，则将任务标记为 failed，丢弃部分文件，并向用户显示可重试的错误。”
可观测性	“我们会监控。”	“发出 export_duration_seconds + export_failures_total{reason}；当 5m 内失败率 > 5% 时发出告警——同一信号也会触发回滚。”

如果你的填写内容看起来像左栏——适用于任何功能、没有追溯关系、没有具体组件、没有选择标准、没有处理方式、没有信号——那就还没完成。

反模式

• “我会重述架构，让文档自成一体。” 这会重复架构文档的内容，并导致偏离；应引用架构文档，并在其基础上设计功能。
• “我会粘贴 API／架构定义，这样评审者就不用查阅了。” 将由 API 规范／数据模型维护的契约内嵌到文档中，必然会导致内容偏离——应添加链接，并且只说明差异。
• “显然有一个选项是正确的，讨论其他选项只是徒劳。” 备选方案一节旨在促使权衡思考；应列出一个真正的备选方案及判断标准，否则该选择就缺乏依据。
• “成功路径就是设计；失败情况属于实现细节。” 设计的价值恰恰体现在失败模式上——应逐一列出并说明处理方式。
• “可观测性／发布是运维的事。” 达到生产级别的设计应说明如何观测和回滚功能；这是构建功能的一部分，而非事后工作。
• “我自己来写大纲。” 这会重复模板工具的内容——应采用它提供的结构。
• “跳过调研吧，我懂设计文档。” 调研为这个系统的约束和解决这个问题的成熟模式提供依据——而非设计文档理论。
• “这次改动就重新生成整篇文档吧。” 已获批的 TDD 应通过有明确范围、带版本的增量修改进行更新——重写会丢失历史记录和稳定的决策 ID。

输出

一份完整的技术设计文档，达到 Step 5 可实施性标准（每项决策都能双向追溯到需求；提供可实施的方法和任务分解；以同步的图示和文字说明呈现控制流／数据流；引用接口／数据的归属文档；涵盖故障模式、跨领域关注点［安全／隐私和可观测性］、测试、发布／回滚；至少列出一个真实的备选方案及判断标准；明确列出假设；范围限定为一项功能；修订时提供有明确范围、带版本的增量修改）。以 Markdown 文本形式呈现——包括说明文字、Mermaid 时序图／流程图、围栏代码块中的接口／伪代码，以及权衡表；方法和标准不受媒介限制。抽象读者是负责实现功能的工程师，以及 reviewing-technical-design 门禁（用于验证是否达到相同标准）。TDD 依赖于 PRD + feature-spec（以及适用时的 architecture-doc / API spec / data-model）作为输入。其结构由模板工具提供；此技能负责内容质量。

相关内容

• 一个技术设计模板工具（例如内容／模板网关）——提供此技能要填充的章节结构。应与之配合使用；切勿重述其大纲。
• 一项深度调研能力——以成熟的设计文档实践和项目的实际约束为设计提供依据。
• 上游 PRD + feature-spec——本设计展开说明的需求（作为输入，绝不在此处重新编写）。
• architecture-doc / API spec / data-model（如有）——TDD 所引用的系统、契约和架构定义（也可说明需要新增哪些文档），绝不重复其内容。
• reviewing-technical-design——运行时用于验证最终 TDD 是否达到相同可实施性标准（11 条条件组成的单一来源检查清单）的门禁；作者和评审者遵循同一标准，避免标准偏离。（文档库中的 technical-design 工件有专属评审者；通用的 design-review 门禁评审其工程类同类文档——RFC／ADR／规范／计划——而非此工件。）

渐进式披露

• references/design-method.md — 需求追踪矩阵（RTM）机制、架构层级（C4）框架、分解 + 同步流程方法、参考而非重复／单一事实来源（SSOT），以及详细设计／伪代码形式。填写第 1–6 节时加载。
• references/failure-test-rollout-amend.md — 失效模式（FMEA）方法、可观测性信号分类、测试金字塔 + 契约符合性细节、发布／功能标记／可量化回滚模式，以及修订影响传递流程。填写第 7–12 节或进行修订时加载。
• references/sources.md — 方法 + 可实现性标准的研究来源。仅在审查指导内容的来源时加载。

正文篇幅限制

• description ≤ 1,024 个字符（agentskills.io 上限）。Claude 会在技能列表中将 description + when_to_use 的合计内容截断至 1,536 个字符。
• 正文 ≤ 约 500 行 / 5,000 个 token。
• 大量内容放在 references/ 中，按需加载。

更新日志

• 1.2.0 (2026-06-14) — 面向生产环境的重构：新增修订／差异方法（步骤 6），将可观测性提升为首要的横切关注点，深化测试 + 发布（加入可量化的回滚触发条件），将步骤 5 的自检扩展为 11 个检查点，并与新的 reviewing-technical-design 门禁共用唯一来源，将深入内容扩展到两个新的 references/ 文件。方法主干 + 参考而非重复／真实备选方案／架构层级规则保持不变。
• 1.1.0 (2026-06-04) — 首个经审查的版本。