write-design

生成 docs/specs/<YYYY-MM-DD>-<feature>/design.md：说明如何满足已批准的需求。以技能集中的 templates/design.md 为起点——如果作为插件安装，则将 templates/ 解析为 ${CLAUDE_PLUGIN_ROOT}/templates；否则相对于此 SKILL.md 使用 ../../../templates。其中每个标题都是必需项。需求文件是你的输入契约——请先完整阅读。

开始前，为每个步骤（1–4）创建一条待办事项，并按顺序完成——此技能有自己的待办列表，与 write-requirements 的上游列表和 write-plan 的下游列表彼此独立。仅当满足相应步骤的 完成条件： 时，才将其勾选。

步骤 1：上下文与决策

用 2–4 段说明当前已有的内容、影响方案的约束，以及该约束排除的替代方案。为了解“当前已有的内容”而又不让上下文过于冗长，请派遣一个扫描子 Agent，绘制受影响范围的映射——设计将涉及的连接点：当前签名、数据形状、保存／加载路径——并返回摘要文件（.skills/<slug>-scan.md），而非原始源码。基于摘要进行设计；仅当某项决策取决于特定文件的确切内容时，才将该文件读入上下文。（没有子 Agent？直接阅读相关范围，但只读决策所需的部分。）

用编号列表记录探索阶段已敲定的决策。任何难以撤销、若无上下文则出乎意料且涉及实际权衡的决策，也必须记录为 ADR（必需子技能： domain-modeling 负责 ADR 审核）。

如果存在 docs/architecture/ 架构主干，其中的 **ARCH-N** 不变量就是本设计的输入：请阅读并注明本功能所依赖的不变量（你将在步骤 2 中引用）。如果某项设计决策必须违反某个不变量，则必须记录 ADR 或进行取代——在架构主干中对该不变量添加删除线——绝不可悄然违反。若不存在架构主干，则跳过此项；该层为可选。 完成条件：“上下文与决策”部分须说明约束条件、因此被排除的替代方案，以及——若存在架构主干——本功能所依赖的 **ARCH-N** 不变量。

步骤 2：架构与 Satisfies 行

每个组件或领域使用一个 ### 章节。每个章节都包含一行 Satisfies: CODE-N.M, CODE-N.M，列出该章节要满足的需求 ID。没有 Satisfies 行的章节要么属于基础设施（请说明），要么不应纳入此功能。如果设计依赖某项架构不变量（步骤 1），章节还要包含一行 Respects: ARCH-N——trace 检查会验证所引用的不变量是否仍然有效。 每个章节还要在 Satisfies: 行旁边包含一行 Reuse: <rung> — <concrete target>，标明适用的最高阶梯，以及它基于的具体现有产物（例如，Reuse: existing — extends src/util/dates:parseISO (rung 2)、Reuse: dependency — zod (rung 5)）；或者填写 Reuse: none — new code (rung 7)，并用一句话说明为什么较低阶梯都不适用。 引入全新的第三方依赖——即项目尚未使用的依赖——是用户的决定，不能擅自作主。如果阶梯指向项目尚未采用的库，请停下来，将其作为明确的选择交给用户：用通俗语言说明“我想添加 <library> 来处理 <problem>”，说清该库是什么、为什么它比自行实现更适合解决这个问题，以及代价是什么（需要维护一个新依赖、它的体积和供应链攻击面）。介绍时要以当前事实为依据，而非凭记忆：在提及库之前，通过 Context7 MCP（或使用它的 research）查询该库最新的稳定版本和 API；基于训练数据截止时的记忆所作的介绍，可能会引用已不存在的版本、包名或 API。等用户同意后，再将其写入设计，作为选定方案；如果用户拒绝，就沿阶梯回退——使用已安装的依赖，或编写能解决问题的最少新代码。已安装的依赖（第 5 阶）无需征求同意，可直接复用。Reuse: 行本身仅供参考；是否采用新依赖才由用户决定。

对于真正棘手的部分，要设计两次：派出 2–3 个并行子 Agent，分别采用不同约束（最小化接口／最大化灵活性／优化常见调用方），比较接口深度和接缝位置，并说明理由，选定一个方案。要有明确立场——用户需要的是有力的建议，而不是一组选项。“真正棘手”指接口本身尚有待确定的问题——例如新的持久化边界、并发模型或插件接缝。形态显而易见的部分不符合条件：向现有存储添加字段、按既定模式接入新路由，或普通 CRUD 表单，都只需设计一次；派出三个子 Agent 得出相同答案只会白费功夫。

在决定构建任何组件之前，沿着复用阶梯逐级检查，并停在适用的最高阶：已有且可用的最简方案，胜过新增代码：

1. 它真的有必要吗？ 没有需求强制要求它 → 删除（YAGNI）。
2. 代码库中已经有了吗？ 步骤 1 扫描发现的 helper、util、类型或模式 → 复用或扩展；重新实现几份文件之外已有的东西，是最常见的低质量做法。
3. 标准库或语言内置功能能实现吗？ 使用它。
4. 平台／框架／运行时功能能满足需求吗？ 优先于手写实现。
5. 已安装的依赖能解决吗？ 使用它——几行代码能实现的事，绝不新增依赖。
6. 能写成一行吗？ 那就写一行。
7. 只有到这一步——才编写能解决问题的最少新代码。

复用阶梯是种条件反射，而不是研究项目：它根据步骤 1 的扫描摘要（“现有情况”）逐级检查，并且只在理解问题之后执行——先追踪变更实际影响的流程，再沿阶梯检查。它绝不能成为忽略重要事项、图省事走捷径的借口：不得删去信任边界处的输入验证、防止数据丢失的错误处理、安全性、无障碍支持，或需求明确要求的任何内容。 这三个杠杆环环相扣，各有不同职责：扫描（步骤 1）收集现有内容； 阶梯决定是否构建；删除测试（见下文）完善构建到多深——且仅适用于第 7 阶的新组件。

以深度为目标进行设计：对于第 7 阶的新组件，模块的接口应远比其隐藏的实现简单。应用删除测试——如果这个模块消失，调用方需要了解多少才能重建它？如果答案是“它所做的一切”，那么接口就很浅；请重新设计。 **完成标准：**每个架构章节都有一行 Satisfies。

步骤 3：商定测试接缝

填写“测试接缝”表：测试将针对哪些公共边界编写、每个接缝覆盖哪些需求 ID，以及测试类型（单元/集成/e2e）。优先使用现有接缝；理想情况下，新增接缝数量为零或一个。tdd 技能拒绝在此处未商定的接缝上编写测试——此表就是约定。 **完成标准：**每个需求 ID 至少对应一行接缝。

步骤 4：覆盖情况自检，然后进入审批关卡

从头到尾检查 requirements.md：每个 ID 都恰好出现在一行 Satisfies 中（或者列为有意未映射，并说明原因）。然后检查占位符和内部矛盾（同一个名称有两种用法、数据流跳过某个组件）。

• **复用覆盖：**验证每个架构章节都遵循了步骤 2 的 Reuse: 规则。

**独立设计审查——派发审查，不要自行审查。**全新的上下文不会受你的表述影响（这种偏见会重新解释过时的需求，而不是发现问题）。派发一个审查子 Agent，并提供此设计、requirements.md 和代码库；让它核实每项面向代码的陈述——每个具名接缝、签名和数据路径都确实如描述所示存在，且每项 Satisfies: 映射都能在对应接缝实现——通过搜索/阅读实际文件并引用 file:line，默认标记问题。审查结果写入 .skills/<slug>-design-review.md；你无需在此处加载代码即可修复问题。（没有子 Agent？请在全新阅读代码的过程中自行完成此检查。）

**向上游同步回写——不得跳过。**设计过程中经常会发现与已批准需求相矛盾的事实：原本的前提被证明是错误的、需求中写错了机制、某项约束并不成立（例如，需求说存储的正文是 ProseMirror-JSON，但你发现它实际是 Markdown）。发生这种情况时，你 MUST 更正需求原文，并重新提交审批——绝不能悄悄重新解释你已知为假的字句，以此满足需求。指向措辞有误的需求的 Satisfies: 行，会让追踪链引用谎言，这个错误会一路遗留到代码中。你正在编写的 ADR 若与现有 ADR 矛盾，也同样如此：必须明确注明要取代的编号。如果你更改了任何需求，在提交审批时必须准确说明更改了哪项以及原因。

将文件逐节呈现给用户；设计篇幅较大时，分节呈现，然后停下等待审批。审批通过后，将 Status: Approved。

退出

必需的子技能：使用 write-plan。