/x-tech-design

name: x-tech-design
description: |
  基于已确认并落盘的功能 spec、项目现有代码/架构和开发规范，生成同一 spec 目录下独立的 tech-design.md 待确认草案。主线必经环节：位于 x-spec 确认之后、x-req 拆任务之前，是拆解的前置。用户提到 x-tech-design，或要求"根据 spec 做技术设计""输出架构文档""确定模块、协议与数据流"时使用。独立于 x-spec，不整理产品需求、不拆开发任务、不写业务实现。

x-tech-design

把已确认的功能需求转成可供用户审查、后续任务拆解引用的技术设计。功能行为以 `spec.md` 为唯一事实源，技术决策与编号测试用例的主定义以独立的 `tech-design.md` 维护；关键约束正文留在 spec，后续任务和报告只回指约束/用例 ID。

输入与产物

| 输入 | 要求 | |---|---| | 项目根目录 | 可访问的明确路径；代码、规范和设计中的仓库路径相对此目录 | | spec 路径 | 已落盘的功能 spec；通常为 `docs/spec/<spec-name>/spec.md` | | spec 确认状态 | 用户确认的结论、来源及对应版本/内容基线；文件存在或父 agent 说“写完了”不等于用户已确认 | | 约束 | 用户明确的范围、技术限制、开发规范及尚未解决的问题；没有额外约束也要注明 | | 现有设计 | 相关架构/协议/数据归属文档路径及确认状态；若无，注明并从代码调查现状 |

产物固定为输入 spec 的同目录 `tech-design.md`，通常是 `docs/spec/<spec-name>/tech-design.md`。记录 spec 路径、版本/内容基线、确认依据、设计状态与本轮范围。默认状态为 **待用户确认**，不能把完成编写、通过自检或父 agent 接收当作批准。

若 `tech-design.md` 已存在，先读取其内容、状态和用户已有修改，基于原文做本轮设计差异；保留无关内容，不盲目覆盖已确认决策或其他人的编辑。项目采用不同 spec 路径时仍取该输入文件的父目录，不另建平行功能文档。

工作流

1. 核对输入与功能边界

完整读取 spec，核对确认依据是否覆盖当前落盘内容与范围。缺少项目根目录、spec 文件、确认依据或必要约束，以及 spec 仍待确认时，停止设计编写，报告缺项和阻塞原因；不要假定继承父会话，不编造用户批准。

读取项目适用的 `AGENTS.md`、相关 `.agents/skills` 和开发规范。设计前读取 [开发规范](references/development-rules.md)，结合项目已有规范逐条判定适用性；引用已有权威规范，不复制维护多份。冲突会影响设计时列出来源与影响，返回澄清。

场景用 `featNN 场景M` 回指（如 `feat02 场景3`），已有 Scenario ID 时沿用；关键约束用 spec 的 C 编号回指，不复制概述或 GIVEN/WHEN/THEN。发现功能行为、边界或数据含义存在歧义，向用户/委派方报告具体回指、分歧和影响，交回需求澄清；不得用技术假设补完产品行为。可继续调查不受影响的现状，受影响设计标为阻塞，不能宣称整体可交接。

C、D、用例 T 是新条目的编号示例，各自在约束、设计、用例范围内唯一；已有约束/用例 ID 或章节定位沿用，不为了本流程重命名。旧 spec 没有 C 章节时从已确认场景和现有约束提取依据，不新造用户决定；新增约束先交 x-spec 确认。

2. 调查现有架构

围绕 spec 范围读取现有目录、模块公开入口、依赖、协议/schema、数据读写、配置与测试。区分“代码当前如此”“用户已确认”“本轮建议”，为现状和复用结论给出可定位的文件/符号证据，不把建议写成既成事实。

优先复用现有模块、技术栈与权威协议。新增模块、引入技术或替换现有方案时，说明现有方案为何不足，以及依赖、调用方、数据迁移、兼容性与维护成本的影响；只写本需求涉及的影响，不借机重构全仓。

3. 编写技术设计

读取 [精简模板](templates/tech-design.md) 并按影响范围填写。为可引用的设计条目分配稳定编号 `D01`、`D02` 等；保留已有编号，场景、设计和后续任务可据此追踪。覆盖下表，内容可以合并但不能漏掉适用项。

| 设计内容 | 必须说明 | |---|---| | feat 与场景映射 | 本轮范围内每个 feat 回指准确场景标识，映射设计编号、参与模块、协议/结构、流程和验证方式；不需新设计的说明沿用来源。普通场景共用主设计，失败、并发、重试等特殊场景按实际需要补设计 | | 关键约束与测试 | 引用本轮适用的已确认 C 编号，说明对应 D 机制，并展开稳定编号测试用例；一个约束可对应多个用例，不能用正常流程测试代替禁止结果验证 | | 模块与依赖 | 职责、具体目录、公开接口、调用方和单向依赖；跨模块只通过公开边界访问，检查循环与越界访问 | | 数据与协议 | 核心结构、关键字段的含义/约束（按需含可空性、单位、标识、关系和不变量）；数据所有者、运行时值的权威存储、协议/schema 的权威来源与使用方；派生值及缓存/索引/快照的策略 | | 主要功能数据流 | 回指相关场景，写清入口 → 边界校验 → 处理模块 → 状态变化/持久化 → 返回；按实际需要补充异步、幂等、并发、失败恢复，或说明不适用理由 | | 关键决策 | 推荐方案、理由、备选与代价、影响范围、待用户确认项；区分关键架构/协议/数据归属与普通实现细节 | | 规范与验证 | 所有规范的适用性、对应设计条目、落实位置和验证方式/证据；代码可检查的采用静态检查或测试，其余提供可定位的审查证据 |

在模板的验证章节定义用例 `T1`、`T2` 等（引用时写“用例 T1”，与 checklist 的任务行 T1 区分），沿用已有用例编号，不重排或复用。每个用例最少包含：依据（C/场景及 D 机制）、前提/触发、预期结果和禁止结果、拟验证层级或证据。只定义一次正文，映射表、req、dev 和 verify 均引用该定义；新增用例补到此处，不在下游另维护验收标准。用户已给具体场景时回指其 GWT，只展开测试安排。

按约束相关风险选择失败、重复、并发、取消、恢复等用例；不机械全套套用，不适用要有具体依据。若只能人工观察或代码审查，写清拟取得的证据和局限，不能伪称自动化覆盖；约束尚未确认或机制不可行时列阻塞，不能从实现推断预期或悄改标准。

例如（仅为设计写法示意）：spec 已确认 `C1`“同一次发送的重试不得重复发送”，`feat01 场景3` 描述重试行为。`D01` 需要幂等或结果核对机制：服务端成功但回执丢失属于结果未知，不能假定失败后无条件重发。用例 `T1` 依据 C1/该场景/D01，前提为服务端已成功且回执丢失，触发同一次发送重试；预期最终只有一条且取得该次结果，禁止再次产生发送副作用；拟用保留真实去重/结果核对路径的集成测试，观察发送记录与最终结果。若并发重试也在 C1 范围内，再定义相应用例，不以 T1 代替全部覆盖。

feat 是追溯需求的单位，不等于模块；不要求每个场景一模块或一张图。共享模块、协议与数据结构只在一处定义，由多个 feat/场景引用。用模板的 Mermaid flowchart 或 sequenceDiagram 解释难以用表述讲清的数据流/依赖或调用顺序，按需选择，不堆无关图。

协议说明包含输入、输出、错误、校验边界及权威来源。已有 schema 优先引用文件路径/符号，只说明本轮重要约束或差异，不复制声明形成第二份维护源。新结构可用模板中的 Zod 或 Pydantic 写设计示意，选择实际使用的语言；明确标注示意和正式实现的计划位置/权威来源，示例字段不构成业务需求，落地后改为引用正式 schema。

小改动只写相对现有设计的差异：引用基线，列出受影响模块、字段/协议、流程与决策，其他条目注明“沿用 + 来源”。不补无关系统架构，也不以“小改动”为由省略实际受影响的协议或数据归属。

4. 检查并交付草案

• 本轮每个 feat 及相关场景回指真实存在，能追到模块、协议/结构、流程和验证；特殊场景有相应设计或共用依据，不新增产品行为。
• 本轮每条已确认关键约束均映射到机制和编号用例，用例依据、触发、预期/禁止结果和层级/证据完整；未覆盖项和证据局限明确，不把用例通过等同全部需求覆盖。
• 模块公开接口、数据所有者、协议来源与数据流相互一致；所有新增/替换有复用调查及影响依据。
• [开发规范](references/development-rules.md) 中每条规则及项目附加规则都有“适用/不适用 + 原因”，适用规则有落实位置和验证依据。
• 区分已执行检查、代码阅读证据与计划在实现阶段执行的测试。没有实现时写明预期判定标准，不伪造通过结果，不为产出证据先写业务实现或安装工具。
• 所有关键问题、阻塞及草案状态清楚；模板注释、占位符和空示例已删除。

交付摘要包含：输出路径、spec 基线与确认依据、覆盖的 feat/场景和设计差异、主要复用/新增决策、待用户确认问题（含推荐及影响）、验证结果与未验证项、是否具备交接条件。无待选方案也要请用户审查草案，不能自动标为已确认。

确认与 x-req 对接契约

技术方案先输出为待确认草案。用户确认关键架构、协议、数据归属及影响方案后，记录实际确认结论、来源与对应设计版本/条目；只确认部分时保留剩余待确认项，不能宣称整体已确认。普通函数、局部变量等实现细节由开发者按已确认设计决定，无需逐项交给用户审批。

通过本技能交接给 req 拆任务时，提供：已确认的 spec 路径/基线、`tech-design.md` 路径/基线及关键条目的确认依据、适用 C 编号、D 机制与用例编号的映射及已知阻塞。任务继续回指 spec 场景，技术安排引用设计条目，不复制维护协议或设计正文。关键设计未确认或功能歧义未解决时，本技能不得宣告可交接。

本技能是主线必经环节：`x-req` 的就绪检查要求同目录存在关键条目已确认的 `tech-design.md`，否则阻断拆解。本技能仍不自动调用 x-req、不创建任务、不编写业务实现。后续实现若需改变已确认的重大架构、协议或数据归属，先更新受影响设计并请求用户确认，再按新结论实施。

spec 后续变更

对照记录的 spec 基线分析变化。纯措辞且行为、数据、接口均未改变时，记录影响判断即可，不重做设计。行为、数据或接口变化时，先列出受影响场景、设计编号和已有任务路径/编号（尚未拆任务则注明）；变更后的功能 spec 未确认时只报告影响和待澄清项，确认后再更新相关设计。关键决策变更标为待确认，已确认且不受影响的条目保留。缺少旧基线时如实报告无法完整判断，不把旧确认套用到新内容，也不自动改写后续任务。

子 agent 委派契约

父 agent 可把技术设计委派给子 agent；委派前提供自足输入，不依赖父会话隐含信息。委派消息至少包括：

任务：使用 x-tech-design，仅输出技术设计草案。
技能入口：<本技能 SKILL.md 的可访问路径，并读取其引用资源>
项目根目录：<明确路径>
spec 路径：<明确路径>
spec 确认状态：<用户确认结论、来源、对应版本/内容基线>
范围与约束：<本轮范围、用户开发规范/路径、技术限制、未决问题；无则注明>
现有设计：<相关文档路径、状态与基线；无则注明>
输出路径：<spec 所在目录>/tech-design.md
返回：输出路径、覆盖场景/设计编号、交付摘要、待确认问题、检查证据与阻塞。
权限边界：只创建或更新设计文档；不改功能 spec、不拆任务、不写业务实现；设计默认待用户确认。

子 agent 缺输入时返回缺项与影响，不补造确认；完成后向委派方返回草案和摘要，无权代替用户批准。父 agent 负责把待确认事项交给用户，并在得到真实确认后执行上述交接契约。