dev-design

Files (2)

• SKILL.md
• dev-design.md · references/

SKILL.md (first lines)

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

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

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

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

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

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

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

# dev-design

## 定位

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

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

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

唯一成果物：

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

## 设计总原则

1. **问题是同一池，出口只有两个**：能从代码查证的进取证队列，代码证不出、需用户拍板的进提问队列。两类问题在循环中交替产生、互相解锁，不存在"先问完代码再问人"的固定顺序。
2. **取证按批进行，每批带问题清单**：攒够一批代码问题再取证，不零散漫游。优先整批委托只读 SubAgent（带回带 `file:line` 的结论报告）；当前环境没有 SubAgent 工具时，降级为主进程按清单只读批量取证，引用要求不变。
3. **代码论断必须可回溯**：设计正文（方案、契约变更、影响面）中每一条关于现有代码的论断都带 `file:line` 或等价的明确定位，写在用到它的位置，不集中堆放附录。
4. **提问按设计树轮次**：把待人拍板的决策建模成设计树，一轮抛出当前可问的全部问题（tree frontier），各带推荐答案；等用户逐题表态后，前沿外扩再开下一轮。不做"一次问一个"，也不做"一次抛所有待解问题"。
5. **验收标准写需求口径**：每条可判定（验证什么、怎么验证、预期结果）；工程侧用例由下游 `dev-test-design` 承接，本文档不展开测试设计。

## 具体流程

### Phase 1：读需求与架构，形成初始问题池

1. 读取工作单 `input` 中存在的 `requirement.md`（用户原始需求）和 `software_architecture.md`（软件架构），两者都是可选，缺失不阻断。
2. 基于需求与架构（架构缺失时从需求文本 + 代码结构自行推断探索边界，并在现状摘要中记录"无架构基线"）列出初始问题：
   - **代码问题**：需求映射到哪些代码位置？现有行为、签名、调用链、测试覆盖是什么？有哪些隐藏约束与既有约定？
   - **用户问题**：范围边界、方案取舍、外部依赖、验收口径中需要用户拍板的事。
3. 初始问题池不求全——循环会持续补充；但需求直接映射到的代码位置必须进入第一批取证。

### Phase 2：问题池循环（取证 ⇄ 提问）

循环执行直到收敛。每一轮：

1. **先处理取证队列**：把当前积累的代码问题作为清单，整批取证——
   - 有 SubAgent 工具：委托一个只读 SubAgent 按清单探索，要求每条关键结论带 `file:line`；无法从代码确认的事实在报告中标记"待确认"，不写成既定事实。
   - 无 SubAgent 工具：主进程按清单只读批量取证，引用要求相同；不偏离清单做无关漫游。
   - 取证只覆盖问题清单与本次需求相关的范围，不做无关模块全景取证。
2. **消化取证结果**：新事实可能解答旧的用户问题（从池中移除）、确认设计可行，也可能引出新问题（按能否自答分流进两个队列）。
3. **抛出提问前沿**：把提问队列按设计树整理——理清依赖，有些决策只有等另一些定了才可问；计算 frontier（所有前提已满足、现在就能问的决策），一轮全部抛出。每题给 `❓ 编号 + 题意`，紧跟 `➡️ 推荐答案`；推荐尽量踩在已取得的代码事实上。不逐题硬等，整轮一起抛。
4. **逐题等用户表态**：每道题必须等用户明确表态后才算定案，**不默认采纳推荐**；用户明确表示"你决定"时，选择最简单可行的方案并记录该决策及理由。
5. **消化用户回答**：回答可能解锁新的决策（进入下轮 frontier），也可能引出新的代码问题（回流取证队列）。

**收敛判据**：取证队列为空（没有待查的代码问题）**且**提问队列无可问决策（frontier 为空、无遗漏存疑）。某一队列暂时为空不算收敛——必须是循环稳定后两者同时为空。

用户看到的交互是树形展开的问答与穿插其间的取证汇报：顶层问题开篇，答案与取证结论交替推进，直到无可再问。

### Phase 3：写入设计

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

1. 需求：目标与范围边界，含明确的不做什么。
2. 现状摘要（可选短节）：几句话给出现状核心结论——现有实现怎么满足（或不满足）本次需求、关键改造点在哪、有无架构基线；作为方案推理的起点。改动完全不涉及现有代码时可省略本节。
3. 方案：**明确选择**，不能停留在"可以 A 也可以 B"；备选方案写明选了哪个、为什么；基于现状与取证结论推导，其中的代码论断带 `file:line`。
4. 契约变更：新增/修改的接口、数据结构、配置、错误码、CLI 参数等，逐项写全名称、位置、签名/字段、类型、调用方、错误语义、兼容策略；"位置""调用方"等现状论断带引用。下游 `task-dev` 直接照此实现，含糊即返工。
5. 影响面：列出实际要改动的文件路径，逐项标注改动性质；路径必须经取证确认，不写猜测路径。
6. 验收标准：需求侧验收口径，每条可执行、可判定（验证什么、怎么验证、预期结果），覆盖需求的全部目标。工程用例由 `dev-test-design` 基于本章承接，这里不展开测试设计。
7. 存疑：仍未解决、影响实现或验证的问题；没有则省略。

### Phase 4：自检

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

## 文档结构

```text
# {需求名称} · dev 设计
## 1. 需求            —— 目标、范围边界、不做什么
## 2. 现状摘要        —— 可选短节：几句话现状结论（含无架构基线说明）
## 3. 方案            —— 明确方案选择与理由，代码论断内联 file:line
## 4. 契约变更        —— 逐项写全（无则省略该节）
## 5. 影响面          —— 经取证确认的文件路径
## 6. 验收标准        —— 需求侧验收口径，可执行可判定
## 7. 存疑            —— 未决问题（无则省略）
```

## 文档边界

### 必须写入

- 需求目标与范围边界（含明确的不做什么）；
- 涉及现有代码时的现状结论（内联于方案、契约变更、影响面，带 `file:line`）；
- 选定方案及关键决策理由；
- 契约变更（接口、数据结构、配置、错误码、CLI 参数等）；
- 影响的文件或模块；
- 可判定的验收标准（需求口径）；
- 存疑项（如有）。

### 不要写入

- 逐行代码实现或完整代码块（片段示意可以，整段实现不行）；
- 集中堆放的全量取证附录——引用写在用到它的位置；
- 与本次需求无关的模块全景分析；
- 从模板抄来的空章节；
- 未经代码确认的推测性结论。

## 自检清单

From pi-ixel/Awesome-Agent-Workflow, MIT.

More from pi-ixel/Awesome-Agent-Workflow