dev-design

name	dev-design
version	2.3.2.4
description	个人开发者轻量设计。把一个需求一次性收敛为单份 dev-design.md，覆盖需求、现状、方案、契约变更、影响面、验收标准、存疑和现状附录，替代 SR 入口的功能设计、AR 澄清、模块边界与 TOBE 详设四段。设计前先读需求与架构，启动 SubAgent 委托代码探索并带回带引用的报告；主进程基于报告汇总「现状摘要」（需求与方案之间）与「现状附录」（文末全量）。取证后按设计树轮次制向用户提问：一轮抛出当前全部可问问题并各带推荐答案，逐题等用户表态后再按新前沿推进下一轮。不再分档，篇幅由需求复杂度自然决定。Use when the user asks for 轻量设计、个人项目设计、dev-design，或通过 aaw-workflow 的 dev 入口进入设计阶段。

前置操作：工作流编排检查

若本 skill 是由 aaw-workflow 的工作单调用的，跳过本节，直接执行正文。

否则，在执行正文之前，先向用户发起一次二选一确认：

是否回到 aaw-workflow 工作流中执行？

• 是，回到工作流（推荐）——进度会被跟踪和上报
• 否，单独执行本 skill——本次执行将不纳入流程跟踪

• 用户选“是” → 加载 aaw-workflow skill，按其流程执行（其入口意图判定会引导继续已有工作流或新建），不再单独执行本 skill 正文。
• 用户选“否” → 继续执行本 skill 正文，之后不再提及工作流。

本节最多询问一次，不得重复打扰。

若工作单输出已存在，仍按当前要求完整执行：先读取并评估已有成果，复用仍有效的信息和已确认答案，可局部修改或整体重写，并写回原路径。

dev-design

定位

本 skill 服务于个人开发者的轻量链路（dev 入口），位于需求确认与任务拆分之间。

它用一份文档承担设计，目标不是写得更少，而是写得刚好够开发：下游 task-split 要能据此拆出任务，task-dev 要能据此写出代码和测试。

唯一的档位就是"写得刚好够开发"这一档；篇幅随需求复杂度自然浮动。

唯一成果物：

.sdd/{SR}/dev-design.md

设计总原则

1. 取证实于提问：能不能改造、改哪里、影响多大，只有跑完代码取证才知道。
2. 事实用 SubAgent 查，决策才问用户：代码取证委托 SubAgent 独立完成（带回带引用的结论），主进程不亲手读代码专注设计；只有代码证不出来、需用户拍板的事才进入提问环节。
3. 探索先于提问：固定顺序 需求 → 架构 → 代码取证 → 写现状 → 提问 → 设计。取证结果落进文档后，再基于事实提问。
4. 提问按设计树轮次：把待定决策建模成设计树，一轮抛出当前可问的全部问题（tree frontier），各带推荐答案；等用户逐题表态后，前沿外扩再开下一轮。不做"一次问一个"，也不做"一次抛所有待解问题"。
5. 现状证据写入文档：现状摘要（几句话）放需求与方案之间作为推理起点；全量取证细节放文末「现状附录」。

具体流程

Phase 1：读需求与架构

1. 读取工作单 input 中存在的 requirement.md（用户原始需求）和 software_architecture.md（软件架构），两者都是可选，缺失不阻断。
2. 用它们确定取证的范围边界：
   • 需求给出本次要做什么、涉及什么能力；
   • 架构文档存在时，用它识别相关模块/分层/边界；
   • 架构文档缺失时，不能中断，从需求文本 + 代码结构自行推断探索边界，并在文档「现状摘要」中记录"无架构基线"。
3. 只读取与需求相关的内容，不做无关模块的全景分析。

Phase 2：代码取证（ASIS，SubAgent 委托）

整段取证委托一个只读 SubAgent，主进程不亲手读代码，只接收 SubAgent 带回的报告。

启动一个 SubAgent 进行如下探索，并要求其报告带 file:line 引用（每条关键结论都能追溯到具体代码位置）：

1. 定位需求涉及的代码位置：文件、函数、组件、调用链、数据流。
2. 读取真实实现，确认：
   • 现有行为与逻辑；
   • 关键函数、数据结构、接口的当前签名与语义；
   • 调用链与依赖关系；
   • 已存在的测试覆盖；
   • 隐藏约束、配置项、既有约定。
3. 无法从代码确认的事实，在报告中标记为待确认，不要写成既定事实。
4. 取证只覆盖与本次需求相关的范围，不做与需求无关的模块全景取证。

SubAgent 回来后，主进程核验报告是否带引用；缺引用或不一致时先让 SubAgent 补齐，不自行臆测代码事实。

Phase 3：写现状摘要与附录

主进程基于 SubAgent 报告汇总成现状内容，不脱离报告自行判断。这是后续提问与设计的共同基础。

1. 现状摘要：放在「需求」之后、「方案」之前的 ## 2. 现状摘要 章节，用几句话给出全量现状的核心结论——现有实现怎么满足（或不满足）本次需求、关键改造点在哪、有无架构基线。让不读附录的人立刻抓住现状。
2. 现状附录：放在文档末尾 ## 8. 现状附录，记录取证到的全量细节——需求映射到的代码位置、函数、调用链、数据结构、现有测试、约束。每项尽量保留 file:line 引用以便读者回溯。范围是"与本次需求相关的尽量全"，不做无关模块分析。
3. 摘要与附录必须一致：摘要是附录的提炼，不得与附录结论矛盾。
4. 若软件架构缺失，在摘要中写明"无架构基线，探索边界由需求文本与代码结构推断"。

Phase 4：基于取证结果提问（设计树轮次制）

在取证与文档现状落盘之后才向用户提问。提问按 grilling 思路组织成设计树，分轮次推进。

提问边界

• 不问：代码能回答的问题（现有行为、调用链、字段结构、接口语义）——这些已由 SubAgent 取证覆盖；
• 只问：代码证不出来、确实需要用户拍板的事，例如：
  • 需求目标或范围边界仍不清；
  • 存在多个合理方案且取舍影响较大，且无法从代码/架构推断取舍依据；
  • 涉及外部系统、数据格式、兼容性或验收口径；
  • 需要用户对外部约束、优先级做决策。

轮次机制

1. 建模设计树：把本次待定决策组织成树，理清依赖——有些决策只有等另一些定了才可问。
2. 计算当前前沿：frontier = 所有前提已满足、现在就能问的决策；依赖尚未解决的不在这个 frontier 里，留到后续轮次。
3. 一轮抛全部前沿：把当前 frontier 的每一题一次列出——每题给 ❓ 编号 + 题意，并紧跟 ➡️ 推荐答案。不逐题硬等，整轮一起抛。
4. 逐题等用户表态：每道题必须等用户明确表态后才算定案，不默认采纳推荐。推荐只用于引导和加速。
5. 据此更新前沿：用户回答后，被解锁的决策进入下一轮 frontier；重复第 2-4 步，直到无可问决策。
6. 用户明确表示“你决定”时，选择最简单可行的方案，记录该决策及理由。
7. 能自己查证的问题（通常是代码）绝不抛给用户。

用户看到的交互就是设计的树形展开——顶层一题（或少数几题）开篇，答案定下后 ❓ 题目呈树状逐层展开，每层带推荐。

Phase 5：写入设计

按合并模板 references/dev-design.md 的章节结构写入真实内容，移除占位提示。

1. 需求：目标与范围边界，含明确的不做什么。
2. 现状摘要：承接 Phase 3，几句话给出现状结论。
3. 方案：给出明确选择，不能停留在"可以 A 也可以 B"；备选方案写明选了哪个、为什么；基于现状摘要推导，避免脱离现状凭空设计。
4. 契约变更：新增/修改的接口、数据结构、配置、错误码、CLI 参数等，逐项写全名称、位置、签名/字段、类型、调用方、错误语义、兼容策略。下游 task-dev 直接照此实现，含糊即返工。
5. 影响面：列出实际要改动的文件路径；路径经 SubAgent 取证或主进程确认为准，不写猜测路径。
6. 验收标准：可执行、可判定。dev 入口没有独立测试用例设计文档，验收标准同时承担测试规格角色，每条写清验证什么、怎么验证、预期结果。
7. 存疑：仍未解决、影响实现或验证的问题；读者能据此判断或回到用户确认。
8. 现状附录：承接 Phase 3，全量取证细节。

Phase 6：自检

按「自检清单」逐项核对，不通过则补齐后再交付。

文档结构

# {需求名称} · dev 设计
## 1. 需求            —— 目标、范围边界、不做什么
## 2. 现状摘要        —— 几句话的现状核心结论（含无架构基线说明）
## 3. 方案            —— 明确方案选择与理由，承接现状摘要
## 4. 契约变更        —— 逐项写全（无则省略该节）
## 5. 影响面          —— 经取证确认的文件路径
## 6. 验收标准        —— 可执行可判定，承担测试规格
## 7. 存疑            —— 未决问题（无则省略）
## 8. 现状附录        —— 与本次需求相关的全量取证细节（含 file:line 引用）

文档边界

必须写入

• 需求目标与范围边界（含明确的不做什么）；
• 现状摘要（几句话）+ 现状附录（与本次需求相关的取证全量）；
• 选定方案及关键决策理由；
• 契约变更（接口、数据结构、配置、错误码、CLI 参数等）；
• 影响的文件或模块；
• 可执行的验收标准；
• 存疑项（如有）。

不要写入

• 逐行代码实现或完整代码块（片段示意可以，整段实现不行）；
• 与本次需求无关的模块全景分析；
• 从模板抄来的空章节；
• 未经代码确认的推测性结论（含未经 SubAgent 报告支撑的现状描述）；
• 与现状附录冲突的现状描述。

自检清单

• 只生成或更新了 .sdd/{SR}/dev-design.md，没有产出其它设计文档。
• 已启动 SubAgent 完成代码取证，且取证早于向用户提问。
• SubAgent 报告带 file:line 引用；现状附录逐项可用其回溯。
• 现状摘要已写在需求与方案之间，几句话概括现状核心结论。
• 现状附录已在文档末尾，覆盖与本次需求相关的代码位置、函数、调用链、测试。
• 摘要与附录一致，没有矛盾。
• 软件架构缺失时已在摘要中记录"无架构基线"。
• 提问按轮次制：一轮抛全部当前前沿、各带 ➡️ 推荐、逐题等用户表态，未默认采纳任何推荐。
• 方案是明确选择，不存在未决的"可选方案"。
• 契约变更逐项写全，下游可直接照此实现。
• 验收标准可执行、可判定，覆盖需求的全部目标。
• 影响文件路径经过取证确认，不是猜测。
• 没有影响实现或验证的存疑项；确实存在的已明确记录并告知用户。
• 移除了全部模板占位提示。

完成条件

• dev-design.md 存在且通过自检；
• 代码取证已完成（SubAgent 报告带引用）且现状附录充分；
• 设计树轮次已收敛：无可问决策遗漏、关键决策已确认；
• 不存在阻断实现的存疑；
• 用户已确认设计方向，或成果明确标记为草案。