Design

---
description: 阶段② 详细设计。根据 design.md 第一章补全第二章各模块设计 + 第四章 ADR。
model: opus
effort: high
---

# ② 详细设计

**输入**：`design.md` 第一章 → **产出**：第二章各模块详细设计 + 第四章 ADR
**验收**：每个模块都有明确接口定义、模块间**可独立测试**，且**骨架已落到代码根**（签名齐、`NotImplementedError` 占位、`mypy` 能过）。

## 讨论风格

教学模式见 `RULES.md`，**但骨架落地之前的每一轮都按这个来，落骨架那一轮才允许成段输出**——这是本阶段对通用教学模式的唯一例外，落骨架需要完整信息一次性写清楚。

## 怎么定（模块级关键决策）

接口 / 算法 / 技术选型这类模块级关键决策，先问用户有没有倾向：
- **用户有倾向** → 针对这个倾向评价、挑问题，不绕开它另起一套。
- **用户没倾向** → 按 `RULES.md` 教学模式的「不知道时怎么引导」走（问机制不问名词，例如「这个模块的数据从哪来、到哪去？」而不是「用观察者模式还是回调？」）。
- 真引导不动（缺的是硬知识不是思路）→ 才根据「零、背景资料」给标准做法，给完主动反驳一遍——什么场景下不成立、代价是什么——再落笔写死接口。
- **用户说过「不知道」的点，在第二章对应模块下记一行 `📖学习点：<是什么>`**，`/wf:split` 会带进任务文件，`/wf:exec` 派 agent 前先就这些点引导他。

琐碎决策（内部变量命名、文件怎么拆）不用问，按 `RULES.md` Tier1 自己定；定死之后写进第四章 ADR。

**讨论收束 = 当场落骨架。** 思路谈定了，骨架就已经有了——直接在代码根写出空壳文件：函数签名 + 类型注解 + docstring + `raise NotImplementedError`。骨架是这一阶段的验收物，不是文档描述，`design.md` 第二章只记接口约定和 ADR，签名本体以代码为准。骨架写不出来 = 设计没谈透，退回继续问。

⚠️ 反驳只挑真正影响正确性/验收标准的代价，不为了显得全面硬凑理由——追着每条自造的顾虑走会导致过度设计：多余抽象层、防御性代码、给不可能发生的场景写测试。

## 硬要求

- **模块必须解耦。** 这一步没做到，阶段④ 就并行不起来——这是整条流水线最大的返工源。
- 每个模块写清：职责、输入输出、依赖了谁、怎么单独测。
- 硬件 / IO / ROS2 接口层单独成模块，标明「需 mock」。
- **重要技术选型**在第四章追加一条 ADR：选了什么、为什么、放弃了什么、代价是什么。

## 禁止

- 只写 / 改**第二章和第四章**，禁止删改第一章内容。
- 设计与需求冲突 → 停下问用户，不许自行改需求。

## 收尾

→ 走 `/wf:wrap`，下一阶段 `/wf:split`，`建议档位：中`。