module-tobe-design

Files (4)

• SKILL.md
• openai.yaml · agents/
• tobe-context-template.md · references/
• tobe-output-template.md · references/

SKILL.md (first lines)

---
name: module-tobe-design
version: "2.3.2.9"
description: 基于当前 SDD 工作流指定的正式《模块详细设计说明书.md》及模块目录下的 `.context/详细设计上下文.md`，设计模块内与本次需求相关的 TOBE 详细方案。TOBE 是唯一可以编辑正式说明书的阶段，必须按正式大纲写入需求背景、外部依赖、整体方案、模块详细方案、对外接口、数据库/表设计、受影响模块与交互、关键契约清单和附录/三方件约束。TOBE 只负责目标设计和可测试性输入，不生成测试用例，不拆分 AICoding 任务；测试用例设计交由 `$module-test-design`，编码任务拆分交由外部 AICoding 流程。详细设计上下文记录 ASIS 证据、TOBE 推导和过程，不得替代正式说明书。不得脱离 ASIS 证据凭空设计；ASIS context 缺失或不足时必须回补 ASIS 或标记阻塞。
---

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

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

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

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

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

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

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

保留未变化的决策和契约编号；语义变化时处理旧编号及引用，并同步检查接口、流程、数据、风险和可测试性。

# SDD 模块 TOBE 设计

## 阶段规则

本 skill 自身定义 TOBE 阶段必须遵守的规则，可在已有 ASIS context 的情况下独立使用；ASIS 不足时必须先回到
`$module-asis-analysis` 补齐必要证据，不能由 TOBE 阶段自行伪造或替代 ASIS。无论由何种入口调用，均以本 skill 的规则作为 TOBE
阶段唯一执行依据。

## 运行方式

本 skill 应由当前主 Agent 直接执行，不要通过 SubAgent 启动；遇到需要用户或上游确认的问题，应在当前会话及时问询，避免
SubAgent 的运转模式导致问询滞后。

本 skill 只回答一个问题：基于 `.context/详细设计上下文.md` 中的 ASIS 事实和模块边界，本模块决定怎么改，并把目标设计、实现必须满足的约束、契约、流程、风险、回退和可测试性输入写入正式《模块详细设计说明书》。正式说明书必须同时服务两类读者：用户和评审者据此判断方案是否正确、取舍是否可接受；后续 AICoding 据此实现而不再补做产品或架构决策。

TOBE 质量不由章节数量决定，而由四条链是否闭合决定：

- 证据链：需求/AR -> ASIS 证据 -> TOBE 决策。
- 边界链：模块边界 -> 职责分配 -> 交互约束。
- 执行链：TOBE 决策 -> 工程落点和开发视图 -> 可测试性输入。
- 风险链：触发风险 -> 缓解设计 -> 验证/回退。

## 成果物协作规则

- 正式成果物：`.sdd/{SR}/{AR}/{模块组名}/模块详细设计说明书.md`。
- 过程上下文：`.sdd/{SR}/{AR}/{模块组名}/.context/详细设计上下文.md`。
- `{模块组名}` 使用当前工作流确认的模块或模块组目录名；文件名固定，不重复拼接 AR、需求短名或模块组名。
- 本 skill 是正式说明书唯一写入者，写入边界覆盖正式大纲中的需求背景/当前 AR
  描述、外部依赖、整体方案、模块详细方案、对外接口、数据库/表设计、受影响模块与交互、关键契约清单、附录/三方件约束。
- 正式说明书是面向用户、评审和开发的标准交付件，只呈现设计结论、现状约束摘要、接口契约、模块边界、目标方案与实现约束、风险、可测试性输入和待确认事项；不得写入
  ASIS 检索过程、证据编号表、推导过程、反证记录、门禁采样、追踪矩阵等过程性内容。
- 已完成的问询、澄清或评审结论在正式说明书中直接写成已确认约束，不保留会话措辞、问题编号、轮次或“已答复”等过程状态；这些过程信息只留在详细设计上下文。
- 本 skill 在详细设计上下文中的写入边界是 TOBE 推导过程、替代方案比较、反证记录、详细追踪矩阵和辅助说明。
- 本 skill 可以读取 ASIS context、门禁（Gate）和上游设计作为输入，但不得覆盖 ASIS 事实或门禁过程记录。
- TOBE 中引用的 ASIS 事实必须在详细设计上下文中使用已有的 ASIS 结论编号和证据编号建立追踪；正式说明书只写用户可读的现状约束摘要，不暴露内部证据编号表。
- ASIS 结论状态必须贯穿到 TOBE：TOBE 只能把已复核吸收的 ASIS 结论作为事实引用；引用 `推断`、`待确认`、低置信度或阻塞相关结论时，必须在详细设计上下文
  中继续标记状态；正式说明书中以待确认事项、已知限制或阻塞说明表达，不降级成事实。
- 如果 ASIS 事实需要修正，标记“需回到 ASIS 修正”，不要在 TOBE 中覆盖详细设计上下文中的旧事实。
- 禁止将影响编码实现、接口契约、包/类设计、数据库、配置、调用流程、验证方式、风险控制或回退策略的内容只写入详细设计上下文。
- 契约保真是硬要求：凡是用户输入、上游设计、模块影响性分析、模块间交互设计、ASIS context
  或已有正式说明书中已经明确给出的接口定义、方法/函数签名、入参出参、DTO/VO/消息字段、JSON/序列化名称、错误码、状态值、Topic、Path、配置项、SQL/表字段或回调事件，TOBE
  必须在正式说明书中原样保留或结构化等价保留；不得只写“新增接口”“调整 DTO”“复用上文定义”等概括性描述。
- 对会跨章节反复出现的字段、DTO、接口、配置项、事件名、错误码、状态值和时间单位，必须在对应设计问题的“契约与工程落点”中先给出单点定义，并在摘要、图、表、工程落点、可测试性输入和风险章节通过契约编号引用同一名称、类型、单位和
  JSON/序列化名称；**一致性指定义不冲突，不要求在多处重写实质内容**。
-
当本模块设计需要相邻模块配套改动时，本模块正式说明书只能写清交互契约、依赖方向、边界约束、需要对方提供或修改的内容，以及本模块侧的防腐/兼容处理；不得把相邻模块内部实现工作混入本模块设计。若相邻模块改动会决定本模块核心方案、接口归属或数据归属，TOBE
必须标记为 `需前置确认` 或拆分为对应模块的独立详设输入。

## 职责边界

TOBE 阶段负责把需求/AR、ASIS 证据和模块边界收敛为本模块目标设计。它回答“本模块应该怎么设计”，不回答“测试用例怎么写”或“AICoding
任务怎么拆”。

TOBE 的内容边界是：**明确实现必须满足什么，但不替 AICoding 决定每一行代码怎么写**。设计既要让 AICoding 不必猜测目标行为、契约、边界和失败语义，也要让用户不阅读生产代码就能判断设计结论、影响、取舍和风险是否正确。

TOBE 阶段负责输出以下设计内容：

- 本模块承担/不承担的范围，以及相邻模块配合边界。
- 需求点目标行为、触发条件、输入输出、验收口径。
- 关键接口、方法、DTO、字段、错误码、状态值、配置项、数据结构和兼容语义。
- 主流程、异常路径、边界场景、回退策略、幂等/并发/迁移/安全/性能等设计。
- 工程落点：定位到受影响的包、现有文件或代码区域及其职责；只有跨模块/对外契约或已有兼容约束要求时，才固定新增文件、私有类型或私有函数的名称与签名。
- 可测试性输入：后续测试设计需要观察和验证的行为、状态、副作用、错误码、日志、指标或告警。

TOBE 阶段不负责输出以下内容：

- 测试用例编号、测试矩阵、建议测试文件、测试命令、Fixture、Mock 或断言清单。
- AICoding 任务编号、任务拆分、任务依赖、最小验证集或开发排期。
- 相邻模块内部实现任务。
- 缺少依据的默认决策、错误码、字段语义、状态流转或验收阈值。
- 完整类或函数实现、可直接运行的业务逻辑、控制流和异常捕获、初始化或日志样板、完整迁移脚本，以及从现有代码复制的大段实现。

接口和数据契约不属于实现越界：上游已明确或跨边界稳定依赖的方法/函数签名、DTO/字段、序列化名称、错误码、状态、配置和表结构约束应按契约保真要求保留。新发明的私有 helper、临时数据结构、文件拆分和容器选型不是设计契约；除非不固定它就无法保证边界、兼容性或正确性，否则只写职责与必须满足的语义。只有当核心算法无法通过约束、决策表或流程说明准确表达时，才使用简短、语言无关且不可直接运行的伪代码。

当目标行为依赖核心算法时，必须讲清输入输出、前置条件、关键不变量、决策分支、终止条件、失败行为以及适用的数据规模或复杂度约束；涉及状态发布或持久化时，还要明确成功可见点、失败后必须保持的旧状态和部分写入边界，不展开逐行实现。排序、匹配、去重等规则必须说明键、优先级、并列项和确定性要求。上游列出的有序键视为完整键集而非可追加前缀；不得以 `tie-break`、稳定性或实现便利为名增加字段，确定性应来自确定输入顺序或稳定算法。现有键仍不足时显式暴露缺口，不自行补规则。

当关键设计模式实质影响职责分配、协作方式或扩展边界时，必须讲清它解决的问题、参与角色、协作关系、真实扩展点和局限；私有参与者用职责名称表达，不为说明模式而发明代码接口名。只有跨边界契约或现有兼容性要求时才固定代码标识。普通 CRUD、简单字段映射或局部调用不强求算法或设计模式说明。

正式说明书中的每段内容都应帮助读者理解、判断或执行：提供新的设计事实、解释关键原因、明确约束/风险，或给出可验证结果。同一事实只在权威位置完整定义一次；重复背景、代码逐行解释、同义改写、空泛原则和不影响本次决策的技术介绍应删除或改为引用。

定稿前从正式说明书本身做一次清洗：把问询编号、轮次、答复过程和 context 内部状态改写成稳定的设计约束；检查新出现的私有代码标识是否确有契约依据；用至少一个代表性真实输入反推关键分支。涉及生产者/消费者兼容时，必须直接使用现有生产者的未改写输出，不能用手工构造的近似样例代替；发现互斥条件或语义冲突时不得定稿。

如果测试设计或任务拆分所需信息缺失，TOBE 应补齐设计本身；无法补齐时标记为 `需前置确认` / `部分完成` / `阻塞`
，不得通过生成测试用例或任务拆分来掩盖设计缺口。

## 输入

可以接受：

- 当前 SDD 工作流指定的正式说明书路径、配套详细设计上下文路径或草稿内容。
- 已完成或部分完成的 ASIS context 章节。
- 需求分析、功能设计、AR 设计。
- 模块影响性分析、模块间交互设计。
- 目标模块名称、目录、包路径、服务、类、API、Job、Consumer 或功能区域。
- 编码约束、测试要求、发布策略、验收标准。

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

More from pi-ixel/Awesome-Agent-Workflow