spec-design-research

概览

本技能用于执行 Spec 级设计阶段的 D1 research（可选）：为 design 决策补足上下文与证据，并把未知收敛为可执行的验证清单，使 D2 可以直接引用结论而无需重复解释。
本技能既可独立使用（只做 D1），也可作为 spec-design 的子技能被调用（当 D0 判定“不跳过”且命中 D1 触发信号时）。

开始时宣布：「我正在使用 spec-design-research 技能进行设计调研并落盘 research.md。」

何时使用 / 不使用

• 使用时机（命中任一）
  • 方案正确性依赖未知事实（若 X 不成立，方案会推倒重来）
  • 存在多个可行方向，但缺少证据支撑取舍
  • 对外契约/迁移/安全/性能/一致性等存在高风险点，需要先验证
  • 你发现自己要写“待确认问题清单 / TODO”，但无法给出验证方式与下一步动作
• 不要用在
  • 需求侧 SSOT 还没落盘（缺 requirements/solution.md）：先完成 R1（见 spec-product-clarify）
  • 不存在关键不确定性，且 solution.md 已经把关键约束与验收口径证据化：可跳过 D1 直接进入 D2

快速参考

• 唯一落盘位置：{FEATURE_DIR}/design/research.md
• 最小化模板：skills/spec-design-research/research-template.md（复制到上面路径再填写）
• D1-DoD（缺一不可）
  • 未知项不以“待确认问题”形式悬空：全部进入“风险与验证清单”
  • 研究结论可追溯，并能被 D2 直接引用（结论短、证据清、可复用）
• 禁止事项
  • 禁止猜 FEATURE_DIR / 手写 .aisdlc/specs/... 路径
  • 禁止在 research.md 写实现规格（任务拆分/字段清单/DDL/脚本步骤）
  • 禁止输出“TODO 列表”替代验证清单
  • 禁止在 D1 擅自新建契约/ADR/实现规格文件或目录：D1 只产出 design/research.md；若需要更新 project/contracts/ 或 project/adr/，在 research 里写“需要更新的入口 + 要点”，把实际落盘留给 D2（或用户明确要求的操作）

实施步骤（Agent 行为规范）

0) 门禁：定位 {FEATURE_DIR}（必须）

任何读写 {FEATURE_DIR}/design/*.md 之前，必须先执行 spec-context；失败立刻停止。

$repoRoot = (git rev-parse --show-toplevel)
. (Join-Path $repoRoot "skills\spec-context\spec-common.ps1")
$context = Get-SpecContext
$FEATURE_DIR = $context.FEATURE_DIR
Write-Host "FEATURE_DIR=$FEATURE_DIR"

1) 读取最小必要输入（缺失则停止）

• 必读：{FEATURE_DIR}/requirements/solution.md
• 按需：{FEATURE_DIR}/requirements/prd.md、{FEATURE_DIR}/requirements/prototype.md
• 按需（项目级）：project/memory/*、相关 project/contracts/、project/adr/ 索引

停止条件（不得脑补继续）：

• 找不到或无法读取 requirements/solution.md
• solution.md 中的 In/Out、验收口径、关键约束不可追溯/不可测试（需要先回到 R1 补齐）

2) D1 是否需要执行（自检；避免“为调研而调研”）

若同时满足以下条件，可 跳过 D1（转入 D2）：

• 关键不确定性已在 solution.md 或既有 design/research.md 中被证据化
• 风险与验证清单已完整且可执行

否则进入步骤 3 编写/更新 design/research.md。

3) 把“未知项”转成“假设 + 验证清单”（核心机制）

硬规则：research.md 不出现“待确认问题清单 / TODO”。未知一律转成验证清单条目。

转译模板（每条未知都必须落到表格里）：

• 风险/假设：一句话描述不确定性（可含前提）
• 验证方式：如何在最小成本下验证（调研/访谈/实验/压测/PoC/演练/数据回放）
• 成功/失败信号：观测到什么算通过/不通过
• Owner / 截止：谁负责、何时前必须得到信号（避免无限期悬空）
• 下一步动作：通过做什么/不通过做什么（分支动作）

4) 编写 {FEATURE_DIR}/design/research.md（最小结构）

必须使用最小化模板生成 research.md（避免结构漂移）：

1. 复制 skills/spec-design-research/research-template.md 的内容
2. 粘贴到 {FEATURE_DIR}/design/research.md
3. 按模板把占位符补齐（尤其是“验证清单”必须可执行）

写作约束：只保留支撑 D2 决策的最小信息；未知统一进入“验证清单”；不要新增“待确认问题/TODO”章节。

5) D1 输出后的衔接（给 D2 可直接引用的输入）

在 research.md 里确保以下内容可被 D2 直接引用：

• TL;DR 中的推荐方向是“机制级一句话”，而非实现步骤
• 每个关键结论都能追溯到：solution.md、contracts/ADR 索引或验证清单条目编号
• 验证清单可直接映射到 D2 的“风险与验证清单”（Owner/截止/动作不丢失）

红旗（出现任一即停止并纠偏）

• 没有 FEATURE_DIR=... 就开始写/改 design/research.md
• 缺 requirements/solution.md 仍继续写 research（=脑补）
• 出现“待确认问题清单 / TODO”，但没有验证方式/Owner/截止/动作
• research.md 变成实现文档：字段/DDL/迁移脚本/任务拆分
• TL;DR 超过 7 行或全是背景，没有“最大风险 + 推荐方向”

压力下的反合理化（常见借口 → 对应动作）

常见错误（以及修复）

• 错误：research 写成百科背景，缺少可执行验证。
  修复：压缩背景到“决策所需最小信息”，把未知全部转为验证清单。
• 错误：把未知留成“待确认问题清单”。
  修复：用“风险/假设 → 验证方式 → 信号 → Owner/截止 → 动作”改写，并编号。
• 错误：把接口字段/表结构写进 research，导致 D2 难以维护。
  修复：research 仅写“对外承诺要点 + 追溯链接（project/contracts/ / project/adr/ 入口）”，字段/DDL/脚本留给 D2 或 implementation。