write-techspec

编写技术规范

生成 docs/specs/<slug>/_techspec.md，为规范中的需求提供技术方案。PRD 说明了_做什么_和_为什么_；本文档决定_如何做_、在哪里做_以及_使用什么。其中的构建顺序会被 write-tasks 转换为任务图，因此这里的排序质量将决定后续的执行质量。

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

$ARGUMENTS 可以是规范名称（slug 或路径），也可以描述重构或 Bug 修复。根据产品行为是否发生变化选择模式：

• 功能开发（产品行为发生变化）——必须存在 docs/specs/<slug>/_prd.md；若不存在，则停止并引导用户使用 write-prd。必须先与产品相关人员沟通，再做产品决策。如果 PRD 包含应由本文档负责的底层技术决策，应将其作为一项发现指出，并建议迁移，而不是默默重复记录。
• 重构或 Bug 修复（产品行为没有变化）——此技能是流水线入口；不会进行 PRD 访谈。如果规范文件夹尚不存在，则按照 write-prd 的编号规则创建一个（<spec-root>/NNNN-<kebab-slug>/，同时扫描配置的 Spec Root 及其解析后的归档目录以查找最高前缀；内置 docs/specs 根目录对应 docs/history/specs/，其他情况对应 <spec-root>/_archived/），并编写一份精简的 _prd.md，仅包含下游技能会解析的契约内容：frontmatter（spec、status: active、surfaces）、问题陈述、项目约束、目标、核心功能、非目标，以及 ## 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”）；在此重复业务背景会产生两份可能逐渐不一致的内容。
• 使用归属方的源路径。 在归属方 Spec 中，为每个已采用的来源链接到其采用后的路径；链接目标相对于 _techspec.md，绝不可指向参考索引中保留的采用前路径。次级 Spec 应链接到主要归属方的副本，不采用任何内容。归档归属方时会执行 Archive Relink：将该副本移至 docs/references/，并重写次级 Spec 的链接，让来源只保留一个归属方，次级 Spec 无需保留副本（ADR-0260、ADR-0083）。

共享上下文的来源

一个 Spec 可以采纳多个上下文相似或互补的待办条目和发现；并不要求或提倡每个来源对应一个 Spec。创建 Spec 之前，先查看未关闭的待办条目和未解决的发现，寻找共享上下文的来源。只有当范围能控制在四个实现任务加一个 QA 门槛以内时才进行归组；超过这一限度，就拆分范围，并为每个来源指定一个归属 Spec。

创建新的发现或待办条目之前，先扩展符合条件的现有条目：直接修订未关闭的待办条目，或为未解决的发现添加带日期的补充内容。

当 roundfix spec judge 输出建议配对时，针对每组建议的配对作出回应：在范围限度内采纳未关闭的来源，或在报告中说明为何将它们分开。建议不是门槛；没有建议也不代表没有符合条件的来源，仍须检查共享上下文的未关闭来源。针对发现或待办条目进行重构或修复 Bug 时，在创建最小 PRD 之前，先查找其他共享上下文的来源。

流程

1. 探索架构

梳理功能将落地的代码：它要扩展的模块、可以接入的扩展点、同类工作的现有模式（现有适配器、现有作业运行器）以及可用的测试基础设施。优先使用现有扩展点，不要新增；理想情况下，新增扩展点数量为零。如果有子 Agent 可用，就委派其进行探索；Spec 需要的是结论，而不是文件内容倾倒。

在探索期间，根据仓库的语义指南确定实际生效的项目约束：

• docs/agents/domain.md 负责标识符指南，并指引如何发现当前有效的 ADR。
• docs/agents/backend.md 负责身份验证和 HTTP 策略。
• 如果仓库没有该指南，则引用负责其相关表面策略的指南。
• docs/agents/agent-instructions.md 负责通用规范条款，包括工具权威性。
• docs/agents/spec-routing.md 负责 Spec 工作流约定。

阅读所有存在的路径，并沿其链接查找实际生效的决策值。绝不可推断建议默认值，也不可将指南缺失视为授权。最终快照必须将标识符策略、身份验证和 HTTP、当前有效的 ADR 义务以及工具权威性分别归类为适用或不适用，并给出理由；每一项都须引用实际生效的 docs/agents/ 来源路径。

2. 明确技术决策

使用与 PRD 阶段相同的流程——每条消息只问一个问题，提供多选项、建议默认值和一行理由——但问题范围限定为如何、放在哪里、采用哪种方式：架构位置、数据模型、API 形态、迁移策略、测试扩展点、性能和安全约束。只询问探索阶段无法确定的内容。

3. 记录 ADR

每项重要的技术决策（难以撤销、缺少上下文时令人意外且存在实际取舍）都应记录为 docs/adr/NNNN-slug.md，沿用 PRD 阶段使用的编号——整个功能共用一套决策日志。每项写 1–3 句话。

4. 编写

根据模板 references/techspec-template.md 编写 _techspec.md。以下两个部分对后续工作影响最大：

• 每项目标和用户故事都必须对应一个命名的技术组件。 未映射的故事代表设计漏洞；现在就找出来，不要等到任务执行期间。
• 构建顺序——按编号列出步骤，第一步之后的每一步都说明依赖哪些先前步骤。write-tasks 会据此生成任务图的依赖边。

将 API 契约编写为带编号的 API Contract 条目，或者使用单条 None. 并说明不适用的原因。下游任务引用中必须能通过名称和编号定位每项编号契约。

术语表条目

当 TechSpec 提及术语表尚未定义的概念时，启动领域建模、明确该术语，并在 PRD 或 TechSpec 的术语表部分中声明。

具体契约

当某项声明将行为归因于决策记录，或 TechSpec 更改命令接口时，请使用 具体契约指南。该指南定义了声明凭据、接口记录块、QA 门禁使用的匹配约定、代码签名接口以及编号不变量。

Project Constraints 是正文内容，绝不是前置元数据。如果设计提议创建、编辑、重命名、移动或删除受保护的工具配置、脚本、忽略文件、插件声明或版本固定项，请暂停，直到维护者明确授权。将该批准以及确切的受限文件记录在 Tooling authority 行中。一般性的实现请求、完成设置、保持沉默，或未列明受限文件的授权，都不构成变更授权。有效记录必须位于 <spec-root>/<slug>/_authorization.md；proposed 记录或没有授权日期的记录均不构成授权，因此在有效授权存在之前，不要将受保护工具相关工作推进到分解阶段。新增或扩大的授权必须在使用它的 squash 交付之前进入目标祖先；授权或修订必须独立于其授权的变更。

每份接口草图都应少于 20 行；它们用于记录形态，而非实现。目标长度为 1,500–2,500 个词——没人阅读的规格说明无法保护任何人。

Delivery Queue 交付的每份 Spec 都必须附带已批准的 _authorization.md，无论是否涉及受保护工具。该记录的 operations 列表必须列出 implement、commit、push、pull_request 和 merge；不更改任何 Governed Path 的 Spec 应记录 paths: []。

Spec 声明的依据

TechSpec 必须在指定位置记录三项依据，而 roundfix spec check 会将每份活动 Spec 中缺少的位置报告为缺口。该检查只读取结构；依据是否正确由读者判断。

• 缺失证据。对于 TechSpec 声明为新增的每个组件，应在 ## Absence Evidence 下以编号条目记录证明其不存在的搜索：包括组件、使用反引号括起搜索内容的 command:，以及说明搜索结果的 result:。搜索 TechSpec 为该行为所引用的文件，而不只是搜索名称。如果没有新增内容，请写 None.，然后说明原因。SC-ABSENCE-UNPROVEN 会报告缺失声明，或缺少命令或结果的条目。
• 被否决的替代方案。在 ## ADR Alternatives 下，为 Active ADR obligations 行中列出的每个 ADR 写一行 - ADR-NNNN: <关系>：说明设计与 ADR 所否决替代方案的关系。如果设计采用了被否决的替代方案，请明确说明，并取代或修订该 ADR。SC-ADR-ALTERNATIVES-UNRELATED 会报告已列出的 ADR 缺少对应行。
• 覆盖范围交叉审阅。在 write-tasks 之前，对照 Coverage Map 中指定的组件，逐一审阅 PRD 用户故事、核心功能和成功指标。在 Coverage Map 中添加 Deviations from the PRD:，后接 None.，或者为 TechSpec 以其他形式交付的每项 PRD 单元添加一个项目符号，注明该单元及原因。SC-COVERAGE-UNREAD 会报告缺少该行，或偏差未注明 PRD 单元。

5. 报告

报告前，请重新阅读已完成的产物以及本技能创建的任何精简 PRD。只有在每个新产物都包含 Project Constraints，四行均注明适用或不适用并说明原因，每行都引用一条有效的 docs/agents/ 来源，并且任何受保护工具的变更记录都明确说明维护者授权及限定的文件范围时，才能报告已完成或建议执行 write-tasks。授权信息不得写入 frontmatter。

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

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

错误级别的问题或检查器执行失败都会阻止报告。修复问题所指明的 PRD 或 TechSpec，然后重新运行命令；只要其中任一问题仍然存在，就不得报告已完成或建议执行 write-tasks。

TechSpec 阶段检查结果干净，并不代表 Spec 已全面覆盖。此阶段不会判定 Task Graph 的 ADR 核算、任务覆盖、上下文引用、Verification 的独立性、需求冲突或演练声明；也不会判定依赖提交的变更路径范围、尚无法机械检查的规则，或产品目标是否能通过用户可访问的界面实现。Task 编写阶段、完整的无范围限制扫描以及 QA 仍负责这些类别。检查器明确列出的跳过检测项应视为未检查，而非检查结果干净。

回复中请提供文件路径、创建的 ADR、仍待决定的事项，以及下一步：write-tasks。

辅助判断

在 roundfix spec check <slug> --stage techspec --run-verification 检查通过后、报告前，请运行 roundfix spec judge <slug> --stage techspec。对于每项提出的判断，要么修改产物并重新运行检查器，要么保留原文并在报告中说明保留理由。judge 仅提供建议，绝不是门槛。若结果为跳过，既不代表失败，也不代表通过；请报告跳过原因，然后继续。切勿打印、存储或索取任何 Jev 密钥：ROUNDFIX_OPENROUTER_JUDGE_API_KEY、ROUNDFIX_OPENROUTER_API_KEY 或 ROUNDFIX_TYPESAFE_API_KEY。

反模式

• 重复 PRD 的业务背景，而不是引用它。
• 推测性地泛化——为 PRD 中不存在的需求设计抽象。
• 将接口草图扩展成实现。
• Build Order 未说明依赖关系——这会迫使 write-tasks 猜测任务图。
• 与现有 ADR 矛盾，却不指出该 ADR，也不提议取代它。

参考资料

• references/techspec-template.md — 完整的 _techspec.md 模板。编写文件前请先阅读。