design-solution

生成 docs/specs/<YYYY-MM-DD>-<feature>/design.md：说明如何满足已批准的需求。从技能集的 templates/design.md 开始——按以下顺序使用第一个存在的路径：与此 SKILL.md 同级的 templates/，否则 ${CLAUDE_PLUGIN_ROOT}/templates，否则 ../../../templates。其中的每个标题都是 必填项。需求文件是你的输入契约——先完整阅读。

开始前，为每个步骤（1、2、2b、3、4）创建一个待办事项，并按顺序完成——此技能管理自己的列表，与上游 specify-behavior 和下游 plan-tasks 的列表相互独立。只有满足各步骤的**完成条件：**时，才将其勾选。

步骤 1：背景与决策

用 2–4 段说明当前已有的内容、决定方案的约束，以及该约束排除的替代方案。派遣一个扫描子 Agent，将受影响的范围——签名、数据形态、保存／加载路径——整理成摘要文件（.skills/<CODE>/scan.md，或在获得 CODE 之前写入 .skills/_pending-<slug>/scan.md），而非原始源代码；只有当某项决策取决于文件的确切内容时，才将该文件调入上下文。（没有子 Agent？直接读取相关范围，只读决策所需的部分。）

当用户表示自己从未阅读过受影响的子系统时，告知他们先运行 /understand，再将扫描摘要视为已追溯的模型。 不要调用它。入门路径表是该行内容的唯一归属位置。

扫描摘要完成后、复用阶梯开始前：执行一次全新检索。 必需的子技能：使用 load-subgraph，以功能 CODE、 需求术语和扫描得到的候选路径作为种子（根据情况选择 neighbors 或 subgraph；schema 1.1）——不要使用过时的父级软件包；全新表示当前 SSOT。有依据的声明（唯一归属位置）： 遵循 skills/execution/load-subgraph/references/grounded-claims.md——绝不要仅凭信封内容编造 Reuse:；应沿复用阶梯逐级查证真实复用。

将探索过程中确定的决策记录为编号列表。任何难以撤销、若无背景便令人意外且涉及真实权衡的决策，也必须记录为 ADR（**必需的子技能：**ADR 门槛由 define-domain 管理）。

如果存在 docs/architecture/ 架构主干，其中的 **ARCH-N** 不变量就是此设计的输入： 阅读它们，并在步骤 2 中注明此功能依赖哪些不变量（引用其编号）。如果某项决策必须违背某个不变量，则必须记录 ADR 或通过在架构主干中使用删除线标记来取代该不变量——绝不能悄然违反。若不存在架构主干，则跳过此项；这是可选的。

可选系统文档（遵循指南）

当设计涉及信任／合规性、可靠性、标准领域、架构形态或跨模块结构时，请阅读此文件同级的 system-docs.md，并严格遵循其中的要求。

**完成条件：**背景与决策部分明确说明了约束条件、因此排除的替代方案、已执行全新检索，并且——若存在架构主干——列出此功能所依赖的 **ARCH-N** 不变量。

步骤 2：架构——满足方式、深度与局部性

每个模块或区域各设一个 ### 小节。按顺序使用模板槽位；架构部分下的每个标题都是必需结构，不可自由发挥。

每节契约（填写模板指定的每一行）：

项	内容
Satisfies:	此模块旨在满足的需求 ID。没有 Satisfies 行 → 基础设施（请标注），或该章节不应存在
Reuse:	成立的最高阶梯级别 + 具体目标，或 none — new code (rung 7) + 原因
Respects:	当设计依赖主干不变量时，填写 ARCH-N（没有主干／不依赖时省略）
Surface:	当此章节会改变已有读取方的行为、值、形状或签名时，必须填写；仅当是尚无任何读取方的新代码时才省略。通过引用搜索查找读取方——grep 符号、列、路由、事件名称，绝不要凭记忆判断。列出每个受影响的读取方（仓库内调用点、测试、持久化行、发出的事件、外部订阅者、文档、配置），并为每个读取方指定且仅指定一种处置方式：replace — 在此变更中完成迁移，并删除旧路径；compat — 两种路径均保留，仅适用于此变更无法触及的读取方，并注明后续移除旧路径的事项；frozen — 此变更不得单方面修改的契约：外部订阅者、持久化行、已发布事件。解除此约束有两种方式，且该行必须说明采用哪种方式——设计围绕契约构建并保持其不变，或需求确实要求变更，且发布须以契约所有者同意为前提，该行应注明这一门槛。frozen 限定谁有权同意，而非该值是否永远不能改变；未注明变通方案或门槛的 frozen 行尚未完成
Security:	可选。当设计依赖现有安全文档时，列出可 grep 的 TB-N、THR-N 和／或 CMP-N ID，这些 ID 仅定义于已批准的 docs/security/threat-model.md（TB/THR）或 docs/security/compliance.md（CMP）。不适用时省略此字段。不要将这些 ID 填入 Respects:（Respects: 仅填写 ARCH）。
Reliability:	可选。当设计依赖现有可靠性目标时，列出可 grep 的 SLO-N ID，这些 ID 仅定义于已批准的 docs/ops/reliability.md。不适用时省略。
Interface:	调用方需要了解的内容——比实现更精简
Depth:	第 7 阶梯级（新模块）： 用一句话说明删除测试——如果此模块消失，调用方仍必须了解什么才能重建其行为？重新设计，直到答案是一个小型接口，而非完整实现。复用现有内容（第 2–5 阶梯级）： n/a — extends <target>
Locality:	此 Satisfies ID 对应的变更落在哪里，以及对第 1 步扫描已发现模块的邻近影响：leave | extend | extract，并附一条简短说明

结构质量是设计的一部分，而不是之后再做的债务扫描。追踪覆盖率（Satisfies:）和结构质量（Interface: / Depth: / Locality:）都完成后，本章节才算完整。

Locality: 记录编辑落在哪里；Surface: 记录谁会受影响。即使读取方不需要编辑，也仍须指定处置方式——设计改变了调用方收到的内容，却不改动其代码，正是此字段存在的原因。

采用全新的第三方依赖——即项目目前尚未使用的依赖——由用户决定。如果阶梯最终指向项目尚未采用的库，请停下来询问用户：它是什么、为何合适、成本如何（维护、占用、供应链）。在提及版本或 API 前，通过 Context7 MCP（或 research）基于最新事实说明理由，并等待用户同意后再将其写入设计；如果用户拒绝，则沿阶梯向下寻找替代方案。已安装的依赖（第 5 阶梯级）无需询问——只有采用新依赖才由用户决定；Reuse: 行仍须记录成立的阶梯级别。

确实复杂的接口（新增持久化、并发、插件接缝）——而非 CRUD 或新增字段：阅读 design-principles.md 并选定一个基础；嫁接不超过 2 个想法；不要折中平均。形态显而易见的工作可跳过此步骤。 在决定构建任何模块之前，先沿着复用阶梯向上攀登，并停在满足条件的最高一级——已有且可用的方案总是比新代码更省成本：

1. 它真的有存在的必要吗？ 没有需求要求它存在 → 删除它（YAGNI）。
2. 这个代码库中已经有了吗？ Step-1 扫描发现的辅助函数、工具、类型或模式 → 复用或扩展它。
3. 标准库或语言内置功能能实现吗？ 使用它。
4. 平台 / 框架 / 运行时的功能能实现吗？ 优先使用它，而不是手写代码。
5. 已安装的依赖能解决吗？ 使用它。
6. 能写成一行吗？ 写成一行。
7. 只有到这一步——才编写满足需求的最少新代码（然后填写 Depth:）。

理解问题后，再结合 Step-1 扫描摘要沿着阶梯向上攀登。阶梯绝不是忽略重要事项的借口：信任边界处的输入验证、防止数据丢失的错误处理、安全性、可访问性，以及需求中提出的所有事项。

想法	实际情况
“签名没变，所以调用方完全不需要修改”	不用修改不等于没有影响。为每个使用方填写一个 Surface: 处置项。
“我已在上文中用文字列出调用方”	文字描述不是清单。每个使用方占一行，各自填写一个处置项。

完成条件： 每个架构部分都按照表格填写 Satisfies:、Reuse:、 Interface:、Depth: 和 Locality:（若适用主干不变量，还要填写 Respects:；若该部分会影响已有使用方，还要填写 Surface:）。

Step 2b：UI 设计——可观察条件

如果任何 Satisfies: ID 是通过浏览器渲染的界面（用户可见的页面、屏幕、组件或样式）交付的 → 填写模板中的 ## UI design 部分。如果没有 → 删除该部分。

填写时，无论是基于锁定的 ui-brief.md 继续设计，还是依据仓库现有的视觉系统从头构建，都请阅读本文件旁的 ui-design-recipe.md 并严格遵循其中说明。

完成条件： 仅当条件成立时，该部分才存在；且每个界面都填写了全部五项，并为每种可到达的可见状态各写一行。

Step 3：商定测试接缝

填写“测试接缝”表格：测试将在哪些公共边界编写、每个接缝涵盖哪些需求 ID，以及测试类型（单元 / 集成 / 端到端）。优先使用现有接缝；理想情况下新增接缝数量为零或一个。test-first 技能拒绝在未于此处商定的接缝处编写测试——此表格即为约定。 完成条件： 每个需求 ID 都至少对应一行接缝记录。

第 4 步：覆盖率自查，然后进入审批关口

从头到尾检查 requirements.md：每个 ID 必须恰好出现在一条 Satisfies 行中（或列为有理由的有意未映射项）。然后检查占位符和内部矛盾（同一名称有两种用法、数据流跳过某个组件）。

• 复用覆盖率： 逐条证明每个架构章节都有一行 Reuse:，且与其声称的阶梯级别相符。
• 结构覆盖率： 逐条证明每个章节都按第 2 步包含 Interface:、Depth: 和 Locality:——每条第 7 级的 Depth: 句子都必须说明调用方仍需了解什么；任何 Depth 答案都在重述整个实现的章节，都必须重新设计。
• 表层覆盖率： 对于每个包含 Surface: 的章节，亲自重新执行引用搜索，并确认清单完整且每一行都注明了处理方式。没有后续移除步骤的 compat 行，或未标记为 frozen 的已变更外部／持久化读取方，均无法通过此项检查。
• UI 覆盖率： 根据 requirements.md 重新评估第 2b 步的判定条件——通过浏览器渲染的表层交付的 Satisfies: ID，若没有对应的 ## UI design 章节，则无法通过此项检查。若该章节存在 → 每个表层的所有槽位都必须填写；颜色必须使用令牌名称，而不是原始十六进制值；任何可达的可见状态（空、错误、加载）都必须有一行 States:。

独立设计审查——指派审查，不要自行审查。 新的上下文不会执着于你的表述（这种偏见会重新解释过时的需求，而不是发现它）。指派一个审查子 Agent，提供此设计、requirements.md、Step-1 扫描摘要（如有）以及代码库，并让其逐条证明：

1. 面向代码的声明——具名接缝和路径确实存在（file:line）。行为属性（恰好一次、原子性、幂等性）必须根据声明在其必须经受的故障情形下实际如何执行来推导，而不能依据先例或注释。三次运行中有两次把恰好一次映射到了 SKIP LOCKED 锁上，而这些锁会在本应由其保护的派发发生之前释放。
2. 结构声明——Interface: 比实现更小；第 7 级的 Depth: 不是空泛描述；Locality: 与扫描摘要相符。

审查结果写入 .skills/<CODE>/design-review.md；你必须在不在此处加载代码的情况下修复这些问题。（没有子 Agent？那就以全新的视角自行审查代码和摘要。）

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

将文件按章节呈交给用户；大型设计应分章节呈交，然后停止并等待审批。获批后，将 Status: Approved 设为已批准。

退出

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