zixun-github spec-design-research
概览
本技能用于执行 Spec 级设计阶段的 D1 research（可选）：从 requirements/solution.md 的技术背景中系统提取未知项，把“NEEDS CLARIFICATION / 依赖 / 集成”转成可分发的研究任务并完成调研，在 design/research.md 中以 Decision / Rationale / Alternatives considered 的结构沉淀结论，使 D2 可以直接引用而无需重复解释。
本技能既可独立使用（只做 D1），也可在 using-aidlc 的路由判定为“需要 D1”时被调用（本技能不做 D0/D1/D2 分流判断）。
开始时宣布：「我正在使用 spec-design-research 技能进行设计调研并落盘 research.md。」
何时使用 / 不使用
- 使用时机（命中任一）
- 方案正确性依赖未知事实（若 X 不成立，方案会推倒重来）
- 存在多个可行方向，但缺少证据支撑取舍
- 对外契约/迁移/安全/性能/一致性等存在高风险点，需要先验证
- 你发现自己要写“待确认问题清单 / TODO”，但无法给出验证方式与下一步动作
- 不要用在
- 需求侧 SSOT 还没落盘（缺
requirements/solution.md）：先完成 R1（见spec-product-clarify） - 不存在关键不确定性，且
solution.md已经把关键约束与验收口径证据化：可跳过 D1 直接进入 D2
- 需求侧 SSOT 还没落盘（缺
快速参考
- 唯一落盘位置：
{FEATURE_DIR}/design/research.md - 最小化模板：
<本SKILL.md目录>/assets/research-template.md - D1-DoD（缺一不可）
- 技术背景中的 所有
NEEDS CLARIFICATION都有对应研究任务，并在 research.md 内给出结论（以 Decision/Rationale/Alternatives 结构） - 对每个 依赖项 有对应“最佳实践”任务结论（或明确“不适用”的理由与证据入口）
- 对每个 集成点 有对应“模式/对接方式”任务结论（含关键约束、失败模式与替代方案）
- 未知项不悬空：要么被研究结论关闭，要么进入“风险与验证清单”（含信号/Owner/截止/动作）
- 研究结论可追溯，并能被 D2 直接引用（结论短、证据清、可复用）
- 技术背景中的 所有
- 禁止事项
- 禁止猜
FEATURE_DIR/ 手写.aidlc/specs/...路径 - 禁止在 research.md 写实现规格（任务拆分/字段清单/DDL/脚本步骤）
- 禁止输出“TODO/待确认问题”替代研究任务与结论（未知要么转任务并产出结论，要么进入可执行验证清单）
- 禁止在 D1 擅自新建契约/ADR/实现规格文件或目录：D1 只产出
design/research.md；若需要更新project/contracts/或project/adr/，在 research 里写“需要更新的入口 + 要点”，把实际落盘留给 D2（或用户明确要求的操作）
- 禁止猜
实施步骤（Agent 行为规范）
0) 门禁：定位 {FEATURE_DIR}（必须）
REQUIRED SUB-SKILL：正在执行 spec-context 获取上下文，并在对话中回显 FEATURE_DIR=...（允许 (reuse)）。
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 worker skill：进入本技能即表示“路由已判定需要 D1”，因此本技能不再做“要不要做 D1”的判断。
若你在执行中发现：关键不确定性已经被证据化且无需继续 research，则应 停止并回到 using-aidlc 重新路由，而不是在本技能内部改写路由结论。
3) 从“技术背景”抽取未知项 → 生成研究任务（核心机制）
硬规则：research.md 不出现“待确认问题清单 / TODO”。未知一律转成研究任务并给出结论；无法在本轮关闭的，再进入“验证清单”。
从 requirements/solution.md 中（尤其是“技术背景/现状/架构/依赖/集成/约束/风险”相关段落）提取三类条目，并为每条生成研究任务：
- NEEDS CLARIFICATION → 研究任务
目标：把“未知事实/不确定性”研究成可被 D2 引用的结论（含取舍与替代方案）。 - 依赖项（组件/服务/库/平台/组织依赖） → 最佳实践任务
目标：查明该依赖在本领域的最佳实践/常见坑/约束（并结合本项目约束给出结论）。 - 集成点（对接外部系统/协议/消息/鉴权/回调等） → 模式任务
目标：明确集成模式（同步/异步、幂等/重试、鉴权/签名、数据契约/版本、错误处理与降级）并给出替代方案。
研究任务生成规则（写入 research.md 的“任务清单”并编号）：
对于技术背景中的每个未知项：
任务："针对 {feature context} 研究 {unknown}"
对于每个技术选择/依赖项：
任务："查找 {domain} 中 {tech} 的最佳实践"
对于每个集成点：
任务："梳理 {systemA} ↔ {systemB} 的集成模式与失败处理"
建议在 research.md 里保留“未知项 → 研究任务编号”的映射表，避免漏项与重复。
4) 分发研究 Agent 并行调研（强烈建议）
把第 3 步生成的任务按“可并行、低耦合”原则分发给多个研究 Agent（每个 Agent 对应 1 个任务或 1 组强相关任务），产出可引用的结论要点与证据入口。
分发时要给足上下文：feature 背景、约束、现状证据入口（solution.md 的段落/链接）、以及需要回答的明确问题清单。
每个研究任务的最小产出要求：
- Decision：最终选择了什么（或“暂不决策/不适用”的明确结论）
- Rationale：为什么这么选（结合项目约束/证据/权衡）
- Alternatives considered：还评估了什么、为什么不选
- Evidence / References：证据入口（文档、代码、标准、历史事故、压测/PoC 结果等）
5) 编写 {FEATURE_DIR}/design/research.md（最小结构）
必须使用最小化模板生成 research.md（避免结构漂移）：
- 复制
<本SKILL.md目录>/assets/research-template.md的内容 - 粘贴到
{FEATURE_DIR}/design/research.md - 按模板把占位符补齐（尤其是“研究任务 → 结论（Decision/Rationale/Alternatives）”必须完整）
写作约束：
- 只保留支撑 D2 决策的最小信息
- 所有
NEEDS CLARIFICATION必须在“研究任务”中出现，并在对应小节被关闭（或进入验证清单并解释原因） - 每个研究任务小节必须包含 Decision / Rationale / Alternatives considered
- 不要新增“待确认问题/TODO”章节
6) 把“未关闭项”落到“风险与验证清单”（必要兜底）
对仍无法在本轮关闭的未知项（例如需要 PoC、访问权限、外部确认、压测窗口等），必须转入“风险与验证清单”，并明确：
- 验证信号：看到什么算成立/不成立
- 方法：怎么验证（调研/访谈/实验/压测/PoC/演练/数据回放）
- Owner / 截止：谁负责，什么时候前必须拿到信号
- 触发动作：成立/不成立分别怎么做（分支动作）
7) D1 输出后的衔接（给 D2 可直接引用的输入）
在 research.md 里确保以下内容可被 D2 直接引用：
- TL;DR 中的推荐方向是“机制级一句话”，而非实现步骤
- 每个关键结论都能追溯到：
solution.md、contracts/ADR 索引、研究任务编号或验证清单条目编号 - 研究任务结论可直接映射到 D2 的决策章节（Decision/Rationale/Alternatives 结构可复用）
- 验证清单可直接映射到 D2 的“风险与验证清单”（Owner/截止/动作不丢失）
完成后：立即调用 using-aidlc 路由下一步（通常进入 D2：spec-design）。
完成后输出与自动路由（必须执行）
research.md 落盘后，必须完成以下动作（按顺序，不可省略）：
- 输出 ROUTER_SUMMARY（YAML 形态，供 Router 决策）：
ROUTER_SUMMARY:
stage: D1
artifacts:
- "{FEATURE_DIR}/design/research.md"
needs_human_review: true
blocked: false
block_reason: ""
notes: "research 结论建议评审；通常下一步进入 D2（spec-design）"
立即执行
using-aidlc：将上述ROUTER_SUMMARY作为路由输入传递给 using-aidlc，由 Router 判定下一步并自动推进（无需等待用户说「继续」）。- 若 Router 判定可自动续跑：在同一轮对话内继续执行下一步 worker skill（如 D2 等）
- 若 Router 触发硬中断：停下并输出阻断原因、需要的输入、候选下一步
对话输出：在调用 using-aidlc 前，可简短说明「本阶段产物已落盘，正在调用 using-aidlc 路由下一步。」
红旗（出现任一即停止并纠偏）
- 没有
FEATURE_DIR=...就开始写/改design/research.md - 缺
requirements/solution.md仍继续写 research（=脑补） - 出现“待确认问题清单 / TODO”，但没有研究任务与 Decision/Rationale/Alternatives（或没有验证方式/Owner/截止/动作）
- research.md 变成实现文档：字段/DDL/迁移脚本/任务拆分
- TL;DR 超过 7 行或全是背景，没有“最大风险 + 推荐方向”
压力下的反合理化（常见借口 → 对应动作）
| 常见借口 | 对应规则 / 动作 |
|---|---|
| “先写到仓库根目录，回头再挪到 spec 里” | 禁止猜路径：先 spec-context 拿到 FEATURE_DIR，否则停止 |
| “没有 solution.md 也能先 research，缺的后补” | 禁止脑补：缺 solution.md 直接停止，先回到 R1 补齐 SSOT |
| “来不及写验证清单，先列 TODO” | TODO 违规：把每条 TODO 改写为验证清单（含 Owner/截止/信号/动作） |
| “PM 要求写细（字段/DDL/脚本）给开发” | 拒绝混层：research 只写结论/证据/验证；在 research 里写“需要更新的 project/contracts/ / project/adr/ 入口 + 要点”，不在 D1 写字段/DDL/脚本 |
| “我已经写了很多实现草稿，不想浪费” | 沉没成本无效：把草稿迁出 research；research 正文只保留可引用结论与取舍依据 |
常见错误（以及修复）
- 错误：research 写成百科背景，缺少可执行验证。
修复：压缩背景到“决策所需最小信息”，把未知全部转为验证清单。 - 错误：把未知留成“待确认问题清单”。
修复：用“风险/假设 → 验证方式 → 信号 → Owner/截止 → 动作”改写，并编号。 - 错误：把接口字段/表结构写进 research，导致 D2 难以维护。
修复：research 仅写“对外承诺要点 + 追溯链接（project/contracts//project/adr/入口）”，字段/DDL/脚本留给 D2 或 implementation。