zixun-github spec-design
概览
本技能是 D2 worker skill：只负责产出可评审的 决策文档（Decision Doc / RFC） 到 {FEATURE_DIR}/design/design.md。
路由权威：是否跳过 design（D0）、是否需要 research（D1）均由 using-aidlc 作为唯一路由器判定；本技能不做分流决策。
核心原则：门禁优先（spec-context）→ 强制消费影响分析与项目知识库 → 决策落盘（D2）。在任何压力下都禁止猜路径、禁止在缺少 SSOT 时脑补推进。
开始时宣布：「我正在使用 spec-design 技能产出设计决策文档（design/design.md / RFC）。」
何时使用 / 不使用
- 使用时机
- 用户要求产出
design/design.md（RFC/Decision Doc），或“做设计再进入 implementation”。 - 你被要求把接口字段/表结构/任务拆分塞进设计文档，担心文档分层被破坏。
- 用户要求产出
- 不要用在
- 需求尚未完成 R1（没有
requirements/solution.md）：先完成需求澄清与方案决策（见spec-product-clarify）。 - 用户明确只要 implementation 计划与任务：直接走 implementation
- 需求尚未完成 R1（没有
快速参考
硬门禁（第一优先级）：任何读写
{FEATURE_DIR}/design/*.md之前，必须先执行spec-context获取上下文并回显FEATURE_DIR=...（允许(reuse)）；失败立刻停止。D2 强制输入（第二优先级）：D2 必须读取
{FEATURE_DIR}/requirements/solution.md#impact-analysis，并据此强制读取受影响模块组件页全文与相关 ADR 全文；读不到必须显式标注CONTEXT GAP，不得静默跳过。输出位置
- D2（必做，未跳过时）：
{FEATURE_DIR}/design/design.md
- D2（必做，未跳过时）：
最小化模板
- D2：
<本SKILL.md目录>/assets/design-template.md（复制到{FEATURE_DIR}/design/design.md再填写）
- D2：
提醒：出现“是否跳过 design / 是否需要 research”的讨论时，请回到
using-aidlc做路由判定；本技能只执行 D2。
实施步骤（Agent 行为规范）
0) 门禁（必须先过，否则停止）
REQUIRED SUB-SKILL：正在执行 spec-context 获取上下文，并回显 FEATURE_DIR=...（允许 (reuse)）。
spec-context失败 → 停止
若上面报错 → 立刻停止（不要生成/写任何 design/*.md 内容）。
1) 读取最小必要输入（缺失则停止）
- 必读（需求侧 SSOT）：
{FEATURE_DIR}/requirements/solution.md - 必读（影响分析 SSOT）：
{FEATURE_DIR}/requirements/solution.md#impact-analysis（从中提取：受影响模块清单、需遵守的不变量、相关 ADR、跨模块影响） - 按需：
{FEATURE_DIR}/requirements/prd.md、{FEATURE_DIR}/requirements/prototype.md - 必读（项目级，强制）：
project/memory/*（业务/技术/结构/术语）project/components/index.md（跨模块依赖关系图/交互方式入口）project/adr/index.md（ADR 索引）- 从影响分析得到的受影响模块：读取
project/components/{module}.md全文（包含## API Contract/## Data Contract/## State Machines & Domain Events等稳定锚点） - 从影响分析得到的相关 ADR：读取
project/adr/{adr-id}.md全文
- 若存在：
{FEATURE_DIR}/design/research.md、{FEATURE_DIR}/design/design.md
停止条件（不得脑补继续）：
- 找不到或无法读取
requirements/solution.md。 - 需求的 In/Out、验收口径、关键约束无法从输入追溯。
硬要求（不得降级为“只读索引/只读一部分”）：
- 受影响模块的组件页与相关 ADR 要么全文读取成功，要么在
design/design.md中显式标注为CONTEXT GAP。 - 禁止用“impact-analysis 的摘要/索引页”替代全文阅读，并宣称“已对齐/已合规”。
- 如果压力导致无法完成全文读取：必须在 D2 输出中把 DoD 标为未满足，并明确阻塞项（而不是“先勾选通过，后续再补”）。
2) D2：design（决策文档 / RFC）
2.1 D2 的定位（写“决策”，不写“实现”）
- 只写：为什么这样做、边界怎么裁切、方案与权衡、对外承诺要点、怎么验证、影响与迁移/回滚要点。
- 不写：实现步骤、任务拆分、代码级细节、接口字段逐一罗列、DDL 细节。
- 若必须对外承诺字段/兼容性：在本文写“要点 + 追溯链接”，细节下沉到
project/contracts/或 ADR。 - 若项目以组件页作为契约 SSOT：优先把细节下沉到对应
project/components/{module}.md#api-contract/#data-contract（与本仓库的 Discover 模块页结构对齐）。
- 若必须对外承诺字段/兼容性：在本文写“要点 + 追溯链接”，细节下沉到
2.2 design/design.md 建议最小结构（模板）
必须使用最小化模板生成 design.md（避免结构漂移）：
- 复制
<本SKILL.md目录>/assets/design-template.md的内容 - 粘贴到
{FEATURE_DIR}/design/design.md - 按模板把占位符补齐（尤其是 C4 L1–L3、备选方案、风险与验证清单、追溯链接）
写作约束：只保留支撑决策/验收/演进的最小信息；不要新增“待确认问题/TODO”章节；不要写实现细节/任务拆分/字段清单/DDL。
2.3 D2-DoD（缺一不可）
- In/Out 明确，且能追溯到
solution.md - 推荐方案用 C4 L1+L2+L3 说清楚，层次可追溯
- 关键决策说明“为什么选它/备选为何不选”
- 与现有系统的对齐已完成（基于
solution.md#impact-analysis）：- 每个受影响模块：完成契约兼容性声明（兼容/扩展/破坏性变更），并引用对应组件页
#api-contract/#data-contract的具体不变量 - 每个相关 ADR：完成ADR 合规声明（遵守/需新增/需修改）
- 对涉及的状态机/领域事件：完成影响说明（引用组件页
## State Machines & Domain Events） - 基于依赖关系图：完成跨模块影响确认
- 每个受影响模块：完成契约兼容性声明（兼容/扩展/破坏性变更），并引用对应组件页
- 不确定性已收敛：未知全部进入“假设 + 验证清单”（Owner/截止/动作明确）
DoD 判定规则（防止“拿 CONTEXT GAP 当完成”）：
- 若任何受影响模块组件页或相关 ADR 出现
CONTEXT GAP，则“与现有系统的对齐已完成”这一项不得勾选通过；必须在 D2 中明确这是阻塞/风险，并给出补齐路径（读到全文/补齐知识库/新增 ADR）。
红旗（出现任一即停止并纠偏）
- 没有先拿到
FEATURE_DIR=...就开始写design/*.md - 找不到
requirements/solution.md还继续写设计（=脑补） - 用“待确认问题清单 / TODO”悬空未知（应改为“假设 + 验证清单”）
- 把 D2 写成实现规格：任务拆分、实现步骤、字段/DDL 细节
- 缺少备选方案或缺少验证清单（导致无法评审/无法落地）
- 只读
project/adr/index.md/project/components/index.md就宣称“已对齐现有系统” - 只读部分受影响模块或只读部分 ADR，就宣称“已对齐/已合规”
- 用 impact-analysis 摘要替代组件页/ADR 全文，但未标注
CONTEXT GAP - 把
CONTEXT GAP当作“对齐已完成”的理由（这是 DoD 失败信号，不是通过信号）
压力下的反合理化（常见借口 → 对应动作）
| 常见借口 | 对应规则 / 动作 |
|---|---|
“先随便写到 design/design.md，回头再挪” |
禁止猜路径：先 spec-context 拿到 FEATURE_DIR；否则停止 |
| “信息不全也能先出初稿，后面再补” | 禁止脑补：缺 solution.md 或不可追溯就停止；把未知改写为“假设 + 验证清单” |
| “主管/PM 说不要门禁/不要查文档” | 门禁是硬规则：Get-SpecContext 失败就停止；不因权威压力破例 |
| “为了开发快，把任务/DDL/字段都写进设计” | 拒绝混层：D2 只写决策与对外承诺要点 + 追溯链接；细节进 contracts/ADR/implementation |
| “没时间做备选/验证清单” | 备选与验证是 D2-DoD：缺失会导致无法评审/返工；宁可缩短正文也不删 DoD 项 |
| “模块页/ADR 太长，先别看；用 impact-analysis 摘要就够了” | 禁止用摘要冒充对齐：组件页与 ADR 要么全文读取，要么标注 CONTEXT GAP；且 DoD 的“与现有系统的对齐已完成”不得通过 |
| “受影响模块太多，只读前两个，其余以后再补” | 禁止部分对齐：影响分析列出的受影响模块与 ADR 是强制输入；要么读全、要么把 DoD 标为未满足并明确阻塞（优先收敛需求/影响面，而不是偷读） |
| “我已经写了一半推荐方案了，现在再回头读会拖慢交付” | 沉没成本无效：先补齐强制输入再写「与现有系统的对齐」；否则 RFC 不可评审、后续返工更大 |
常见错误（以及修复）
- 错误：在压力下“先写了再说”，先生成文档再补输入。
修复：先执行spec-context获取上下文，并满足solution.md门禁；缺失就停止，写清楚阻塞项。 - 错误：把 research 当成“查资料”，写了很多背景但没有验证清单。
修复：把未知全部转成“风险/假设 → 验证方式 → 信号 → Owner/截止/动作”。 - 错误：PM 要求把任务/接口/表结构写进设计，于是混层。
修复：设计文档只保留“对外承诺要点 + 追溯链接”；实现细节移入 implementation 或 contracts/ADR。 - 错误：只读索引（
components/index.md、adr/index.md或 impact-analysis 摘要），就写“已对齐/已合规”。
修复：对每个受影响模块与 ADR：必须全文读取并引用具体不变量/条款；读不到就写CONTEXT GAP，且 DoD 不得通过。
完成后输出与自动路由（必须执行）
design.md 落盘后，必须完成以下动作（按顺序，不可省略）：
- 输出 ROUTER_SUMMARY（YAML 形态，供 Router 决策）：
ROUTER_SUMMARY:
stage: D2
artifacts:
- "{FEATURE_DIR}/design/design.md"
needs_human_review: true
blocked: false
block_reason: ""
notes: "RFC 建议评审通过后再进入 I1（spec-plan）"
立即执行
using-aidlc：将上述ROUTER_SUMMARY作为路由输入传递给 using-aidlc，由 Router 判定下一步并自动推进（无需等待用户说「继续」）。- 若 Router 判定可自动续跑：在同一轮对话内继续执行下一步 worker skill（如 I1 等）
- 若 Router 触发硬中断：停下并输出阻断原因、需要的输入、候选下一步
对话输出：在调用 using-aidlc 前，可简短说明「本阶段产物已落盘，正在调用 using-aidlc 路由下一步。」