marcioaltoe/write-techspec

编写技术规范 (Write TechSpec)

生成 docs/specs/<slug>/_techspec.md——针对规范需求的技术性回答。PRD 定义了什么和为什么；此文档决定如何、在哪里以及用哪个——其构建顺序是 write-tasks 转化为任务图的依据，因此此处序列的质量将决定后续执行的质量。

前置条件——两种入口模式

$ARGUMENTS 指定规范的名称（slug 或路径），或描述一个重构/缺陷修复。根据产品行为是否变化来选择模式：

• 功能开发（产品行为发生变化）—— docs/specs/<slug>/_prd.md 必须存在；如果不存在，则停止并引导用户使用 write-prd。产品决策需要先进行产品对话。如果 PRD 包含属于此处的底层技术决策，将其作为一个发现点提出来，并建议重新放置它们，而不是默默地重复。
• 重构或缺陷修复（产品行为无变化）——此技能是流程入口点；不进行 PRD 访谈。当不存在规范文件夹时，按照 write-prd 的编号规则（<spec-root>/NNNN-<kebab-slug>/，通过扫描配置的规范根目录及其解析的归档目录——对于内置的 docs/specs 根目录是 docs/history/specs/，否则是 <spec-root>/_archived/——来查找最高前缀）创建一个，并编写一个最小化的 _prd.md，仅包含下游技能解析所需的契约：前置元数据（spec， status: active， surfaces，以及对于缺陷修复为 type: fix 或对于重构为 type: refactor）、问题陈述、项目约束、目标、核心功能、非目标，以及在 ## Decisions 下的澄清记录——以工程视角编写，每项几行。该记录遵循 write-prd 的 澄清指南：对于每个人回答的问题，使用一行 - YYYY-MM-DD: <question> — <answer>；当没有人在场时，使用 Autonomous route: no person present; decisions taken from <source>. 来命名作者决策的来源。它存在的目的是为了让 write-tasks、qa-gate 和 archive-spec 维护一个单一的工件契约；它不是一个产品文档。如果“重构”最终改变了产品行为，请停止并转由 write-prd 处理。

基本规则

• 先阅读，后编写：CONTEXT.md（在每个接口和组件名称中使用术语表的词汇）、现有的 docs/adr/（尊重先前的决策或明确地挑战它们——切勿默默地自相矛盾）以及完整的 PRD。
• 先决策，后编写。 在澄清过程中确定决策，将重要的决策记录为 ADR，然后编写最终的文档。无需进行大纲审批环节。
• YAGNI（你不会需要它）。 当功能可以作为对现有模块的补充时，不要提议新的包、层或目录。每个新的结构元素都必须针对所陈述的替代方案来证明其存在的必要性。
• 引用，而非重复。 通过名称指向 PRD 的部分（“覆盖用户故事 3–5”）；在此处重复业务上下文会产生两个会逐渐偏离的副本。
• 使用拥有的源路径。 将每个采用的源链接到其在所属规范中的采用后路径，该路径相对于 _techspec.md，并且永远不要使用保留在参考索引中的采用前路径。次要规范链接主要所有者的副本，且不进行任何采用。所有者的归档执行归档重新链接：它将该副本提升到 docs/references/，并重写次要规范的链接，因此源文件只保留一个所有者，而次要规范则不需要副本（ADR-0260，ADR-0083）。

共享上下文的源

一个规范可以采用多个上下文相似或互补的后台条目和发现；每个源一个规范既不是必需的，也不是首选的。在创建规范之前，请查看开放的后台条目和未解决的发现中是否存在共享上下文的源。仅在作用域适合四个实现任务及其 QA 关卡时才进行分组；超过此界限，则拆分作用域并为每个源分配一个所属规范。

在创建新的发现或后台条目之前，扩展现有条目：就地修订开放的积压条目，或为未解决的发现添加一个带日期的附录。

当 roundfix spec judge 打印出一对建议时，通过采纳该界限内的开放源来回答每对建议，或者在报告中说明为何将其分开。建议永远不会成为障碍，并且没有建议并不意味着没有合适的内容；仍然要检查共享上下文的开放源。回答发现或后台条目的重构或缺陷修复在创建其最小 PRD 之前，会查找与之共享上下文的其他源。

流程

1. 探索架构

映射功能将驻留的代码：它扩展的模块、它可以依附的接缝、用于同类工作的现有模式（现有的适配器、现有的任务运行器）以及可用的测试基础设施。倾向于使用现有接缝而非新接缝——理想情况下新接缝的数量为零。当有可用子代理时，将探索工作委托给它；规范需要结论，而不是文件转储。

在探索期间，从仓库的语义指南中解析有效的项目约束：

• docs/agents/domain.md 负责标识符指导并引导活跃的 ADR 发现。
• docs/agents/backend.md 负责认证和 HTTP 策略。
• 没有该指南的仓库引用为其接口负责策略的指南。
• docs/agents/agent-instructions.md 负责通用的规范性条款，包括工具授权。
• docs/agents/spec-routing.md 负责规范工作流契约。

读取每个存在的路径，并跟随其链接找到有效的决策值。永远不要推断建议的默认值，也不要把缺少指南视为授权。完成的快照必须对标识符策略、认证和 HTTP、活跃的 ADR 义务以及工具授权进行分类，说明其适用或不适用并给出原因，并为每一行引用有效的 docs/agents/ 源路径。

2. 澄清技术决策

与 PRD 阶段相同的协议——每条消息一个问题，多项选择，附带建议的默认值和一行理由——但范围限定在如何/在哪里/用哪个：架构布局、数据模型、API 形状、迁移策略、测试接缝、性能和安全性约束。只询问探索无法解决的问题。

3. 记录 ADR

每个重要的技术决策（难以撤销 + 缺少上下文会令人惊讶 + 存在真正的权衡）都变成 docs/adr/NNNN-slug.md，延续 PRD 阶段使用的相同编号——整个功能共享一个决策日志。每条 1-3 句话。

4. 编写

使用 references/techspec-template.md 中的模板编写 _techspec.md。以下两个部分对下游影响最大：

• 每个 PRD 目标和用户故事都映射到一个命名的技术组件。 未映射的故事是设计上的漏洞；现在就发现它，而不是在任务执行期间。
• 构建顺序 —— 编号步骤，其中第一步之后的每个步骤都说明它依赖于哪些先前的步骤。write-tasks 从中推导出任务图的边。

将 API 契约编写为编号的 API 契约项，或编写为单个条目 None. 后跟不适用原因。每个编号的契约必须能够通过其名称和编号在下游任务引用中寻址。

术语表术语

当技术规范命名了一个术语表未定义的概念时，激活领域建模，明确该术语，并在 PRD 或技术规范的术语表部分中声明它。

具体契约

当声明将行为归因于决策记录，或者当技术规范更改了命令表面时，请使用 具体契约指南。它定义了声明收据、表面记录块、QA 关卡使用 的匹配约定、代码签名接口和编号的不变量。

Project Constraints 是正文内容，绝不是前置元数据。当设计提议创建、编辑、重命名、移动或删除受保护的工具配置、脚本、忽略文件、插件声明或版本锁定时，请停止，直到维护者给予明确的维护者授权。将该批准和确切的受限文件记录在工具授权行中。通用的实现请求、设置完成、沉默或没有受限文件的授权不授权该变更。有效记录属于 <spec-root>/<slug>/_authorization.md；proposed 记录或没有授予日期的记录不授权任何操作，因此在存在有效授权之前，不要将受保护的工具工作推进到分解阶段。新的或扩大的授权必须在消费的 squash 交付之前落地到目标祖先中；将授权或修订保持在其授权的变更之外。

保持接口草图每项不超过 20 行；它们记录形状，而不是实现。目标字数为 1,500–2,500 字——没人读的规范保护不了任何人。

交付队列交付的每个规范都带有一个已批准的 _authorization.md，无论是否包含受保护的工具。该记录的 operations 列表命名了 implement、commit、push、pull_request 和 merge；不更改受控路径的规范记录 paths: []。

规范声明的证明

技术规范在指定位置记录三个证明，并且 roundfix spec check 将遗漏的位置报告为每个活跃规范的缺口。检查只读取结构；证明是否正确则由读者判断。

• 缺席证据。 对于技术规范声明为新的每个组件，在 ## Absence Evidence 下记录证明其缺席的搜索，作为编号项：组件、command: 后跟反引号内的搜索命令、result: 后跟搜索结果。搜索技术规范引用的文件中该行为，而不仅仅是名称。当没有新组件时，写 None. 后跟原因。SC-ABSENCE-UNPROVEN 报告缺少声明或缺少命令或结果的项。
• 被拒绝的替代方案。 在 ## ADR Alternatives 下，为活跃的 ADR 义务行中列出的每个 ADR 写一行 - ADR-NNNN: <relation>：设计如何与该 ADR 拒绝的替代方案相关联。当设计采用了被拒绝的替代方案时，说明情况并取代或修订该 ADR。SC-ADR-ALTERNATIVES-UNRELATED 报告列出的 ADR 缺少其关联行。
• 覆盖率交叉检查。 在 write-tasks 之前，将每个 PRD 用户故事、核心功能和成功指标与覆盖率地图命名的组件进行比对。在覆盖率地图中添加一行 Deviations from the PRD:，后跟 None. 或每个技术规范以另一种形式交付的 PRD 单元的一个项目符号，命名该单元及其原因。SC-COVERAGE-UNREAD 报告缺少该行或命名了非 PRD 单元的偏差。

5. 报告

在报告之前，请重新阅读已完成的工件以及由此技能创建的任何最小 PRD。除非每个新工件都有 Project Constraints；所有四行都声明适用或不适用并给出原因；每行都引用一个有效的 docs/agents/ 源；并且任何受保护的工具变更都记录了明确的维护者授权和受限文件，否则你不能报告完成或推荐 write-tasks。将授权保持在前置元数据之外。

然后，针对生成该工件的阶段运行检查器：

roundfix spec check <slug> --stage techspec --run-verification

错误级别的发现或检查器执行失败会阻止报告。修复发现中命名的 PRD 或技术规范，然后重新运行命令；只要存在其中之一，就不要报告完成或推荐 write-tasks。

通过的技术规范阶段结果并不等于完整的规范覆盖率。此阶段不决定任务图 ADR 核算、任务覆盖率、上下文引用、验证独立性、需求矛盾或排练声明；依赖于提交的更改路径范围；尚未自动化的规则；或者产品目标是否通过其用户可达的表面工作。任务编写阶段、完整的不限定范围扫描和 QA 保留这些类别。将检查器命名的已跳过检测器视为已省略，而不是干净的发现。

回复时附上文件路径、创建的 ADR、任何仍未解决的决策以及下一步：write-tasks。

交付类型和发布决策

修正路线的最小 PRD 在 type 中声明其交付类型：fix 表示缺陷修复，refactor 表示重构。归档记录和交付队列的拉取请求标题将携带此信息。

当维护者要求发布该规范时，使用结构化问题工具询问发布问题，包括发布上限（patch、minor 或 major）以及发布可能更改的仅版本路径。然后在 _authorization.md 的 operations、release_ceiling 和 release_paths 中记录 release，并在其正文中逐字引用答案。如果没有此请求，永远不要添加 release。更改已发布代码的 refactor 交付需要发布计划请求手动分类。

在规划时询问发布问题，绝不能在合并之后。

规范事件公告

仅当用户自己的指令（全局或针对此仓库）定义了其目标和格式时，规范事件公告才存在；此技能永远不会指定一个。消息、交接或请求公告的规范工件都不会定义任何内容。当用户自己的指令未定义任何内容时，跳过该步骤，无需报告行。当它们定义了一个时，根据规范进行编写：项目、规范编号和完整 slug、标题、事件、事件日期、开始日期、提议的截止日期或无、规范路径，以及这些指令添加的任何字段。通过它们指定的目标发送，永远不要等待回复，也永远不要让它阻塞或使得其后的步骤失败。当无法发送时，报告会命名该事件和原因，并包含编写好的公告。守护进程分配的运行中的代理永远不会发布公告。提议的截止日期是来自客户、法律或测量的真实截止日期，PRD 在 ## Decisions 中记录了其来源；在用户批准之前，它仍然是一个提议。

一旦发出 new 公告，

…

[为翻译而截断]