module-tobe-design

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

SDD 模块 TOBE 设计

阶段规则

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

运行方式

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

本 skill 只回答一个问题：基于 .context.md 中的 ASIS 事实和模块边界，本模块决定怎么改，并把目标设计、契约、流程、风险、回退和可测试性输入写入正式《模块详细设计说明书》。

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

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

成果物协作规则

• 正式成果物命名为 {AR编号}-{需求短名}-{模块名}模块详细设计说明书.md，例如 AR07758-支持快速退款接口相关功能-支付审计模块详细设计说明书.md。
• 过程上下文命名为 {AR编号}-{需求短名}-{模块名}模块详细设计说明书.context.md。
• xxx模块详细设计说明书 只是占位名；同一轮 SDD 工作流中必须解析为同一个正式说明书和同名前缀 context 文件。
• 本 skill 是正式说明书唯一写入者，写入边界覆盖正式大纲中的需求背景/当前 AR 描述、外部依赖、对外接口、整体方案、数据库/表设计、受影响模块、模块交互设计、模块详细方案、附录/三方件约束。
• 正式说明书是面向用户、评审和开发的标准交付件，只呈现设计结论、现状约束摘要、接口契约、模块边界、实现方案、风险、可测试性输入和待确认事项；不得写入 ASIS 检索过程、证据编号表、推导过程、反证记录、门禁采样、追踪矩阵等过程性内容。
• 本 skill 在 .context.md 中的写入边界是 TOBE 推导过程、替代方案比较、反证记录、详细追踪矩阵和辅助说明。
• 本 skill 可以读取 ASIS context、门禁（Gate）和上游设计作为输入，但不得覆盖 ASIS 事实或门禁过程记录。
• TOBE 中引用的 ASIS 事实必须在 .context.md 中使用已有的 ASIS 结论编号和证据编号建立追踪；正式说明书只写用户可读的现状约束摘要，不暴露内部证据编号表。
• ASIS 结论状态必须贯穿到 TOBE：TOBE 只能把已复核吸收的 ASIS 结论作为事实引用；引用 推断、待确认、低置信度或阻塞相关结论时，必须在 .context.md 中继续标记状态；正式说明书中以待确认事项、已知限制或阻塞说明表达，不降级成事实。
• 如果 ASIS 事实需要修正，标记“需回到 ASIS 修正”，不要在 TOBE 中覆盖 .context.md 中的旧事实。
• 禁止将影响编码实现、接口契约、包/类设计、数据库、配置、调用流程、验证方式、风险控制或回退策略的内容只写入 .context.md。
• 契约保真是硬要求：凡是用户输入、上游设计、模块影响性分析、模块间交互设计、ASIS context 或已有正式说明书中已经明确给出的接口定义、方法/函数签名、入参出参、DTO/VO/消息字段、JSON/序列化名称、错误码、状态值、Topic、Path、配置项、SQL/表字段或回调事件，TOBE 必须在正式说明书中原样保留或结构化等价保留；不得只写“新增接口”“调整 DTO”“复用上文定义”等概括性描述。
• 对会跨章节反复出现的字段、DTO、接口、配置项、事件名、错误码、状态值和时间单位，必须在正式说明书中先给出单点定义，并在摘要、图、表、工程落点、可测试性输入和风险章节复用同一名称、类型、单位和 JSON/序列化名称。

当本模块设计需要相邻模块配套改动时，本模块正式说明书只能写清交互契约、依赖方向、边界约束、需要对方提供或修改的内容，以及本模块侧的防腐/兼容处理；不得把相邻模块内部实现工作混入本模块设计。若相邻模块改动会决定本模块核心方案、接口归属或数据归属，TOBE 必须标记为 需前置确认 或拆分为对应模块的独立详设输入。

职责边界

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

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

• 本模块承担/不承担的范围，以及相邻模块配合边界。
• 需求点目标行为、触发条件、输入输出、验收口径。
• 关键接口、方法、DTO、字段、错误码、状态值、配置项、数据结构和兼容语义。
• 主流程、异常路径、边界场景、回退策略、幂等/并发/迁移/安全/性能等设计。
• 工程落点：涉及哪些文件、包、类、函数、API、数据、配置或开关，作为后续任务拆分输入。
• 可测试性输入：后续测试设计需要观察和验证的行为、状态、副作用、错误码、日志、指标或告警。

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

• 测试用例编号、测试矩阵、建议测试文件、测试命令、Fixture、Mock 或断言清单。
• AICoding 任务编号、任务拆分、任务依赖、最小验证集或开发排期。
• 相邻模块内部实现任务。
• 缺少依据的默认决策、错误码、字段语义、状态流转或验收阈值。

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

输入

可以接受：

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

如果 .context.md 中 ASIS 证据缺失或不足，先判断能否回到 ASIS 阶段补齐必要 ASIS；不能回补时按阻塞规则处理。正式说明书缺失时由 TOBE 阶段按模板创建。

输出模式

根据本 skill 内置规则选择 轻量 / 标准 / 增强 输出模式。

轻量模式适用于小范围变更、helper/adapter/parser 小改、配置/文案/测试补齐、单入口低风险 bug 修复。轻量模式只减少空表和重复章节，不降低质量门禁。

轻量模式至少保留：

• TOBE 状态、输出模式和关键结论。
• 模块边界与本模块承担/不承担内容。
• 影响本次设计的现状约束摘要；对应 ASIS context 结论编号、证据编号和结论状态写入 .context.md 追踪矩阵。
• TOBE 设计决策和工程落点。
• 工程落点、验收口径和可测试性输入。
• 风险专题的不适用说明或触发专题的简要分析。
• 被触发的开发视图，例如接口变化、类变化或数据库变化；轻量模式不能省略开发必需内容。

出现跨模块、数据迁移、权限/隐私/支付/密钥、高频/批处理/核心链路、明确 SLA、门禁返工、ASIS 低置信度、规格漂移严重等情况时，升级为标准或增强模式。

工作流程

TOBE 是一条「读 ASIS → 定范围 → 查覆盖 → 做设计 → 展风险 → 更新成果物」的收敛流水线，核心是把 ASIS 证据收敛成可交给 AICoding 的目标设计，全程围绕四条链闭合（证据链 / 边界链 / 执行链 / 风险链）。

flowchart TD
    S1["§1 读取正式说明书 + .context.md<br/>ASIS结论/证据/变更类型"] --> S2["§2 初步对齐设计范围<br/>本模块承担/不承担/相邻配套 + 输出模式"]
    S2 --> S3{"§3 ASIS 覆盖充分?"}
    S3 -->|"关键事实缺证据/低置信/待确认"| BL["阻塞: 标记需前置确认<br/>回 ASIS 或问询, 只设计无依赖部分"]
    S3 -->|"充分"| S4["§4 形成 TOBE 决策<br/>围绕四条链最小充分设计"]
    BL --> S4
    S4 --> S41["§4.1 变化触发表<br/>8 类变化逐项 是/否"]
    S41 --> S42["§4.2 关键开发视图<br/>包图/类图/流程/接口/DB/配置"]
    S42 --> S43["§4.3 跨章节一致性约束<br/>字段/接口/契约保真"]
    S43 --> S5["§5 展开被触发的风险专题<br/>防腐/安全/性能/观测/兼容/并发"]
    S5 --> S6["§6 更新成果物<br/>正式说明书 + .context.md"]
    S6 --> Q{"质量标准达标?"}
    Q -->|"否"| S4
    Q -->|"是"| DONE["交付: 进入测试设计 / Gate"]

关键脉络：

• §3 是收敛闸口：ASIS 覆盖不足时只能标记阻塞、问询或回 ASIS，不能凭空设计；只有无依赖的独立部分可继续。
• §4 是核心：四条链的闭合都在这里落地——决策（证据链+边界链）、变化触发表+开发视图（执行链）、一致性约束（契约保真）。
• §4.1 触发表驱动 §4.2 视图：触发表标记"是"的变化类型才在开发视图展开，"否"的写一句不涉及原因，不生成空表。
• §5 风险只展开被触发的：未触发专题写不适用说明，不强求填满。
• 质量标准是自闭环：§6 更新后回看质量标准，未达标回到 §4 收敛，达标才交付。

下文 §1–§6 是每个环节的操作细节（怎么做）；本流程图是整体骨架（在做什么）。

1. 读取正式说明书和 context

• 定位当前 SDD 工作流指定的正式说明书和同名前缀 .context.md；未指定时使用同一轮流程内统一的 {AR编号}-{需求短名}-{模块名}模块详细设计说明书.md 占位。
• 读取 .context.md 中的 ASIS 结论、需求/AR 与 ASIS 证据映射、ASIS 探索任务清单、探索任务结果汇总、复核与吸收记录、证据索引、待确认问题、ASIS 阻塞项。
• 读取 ASIS 变更类型；当变更类型为 纯新增行为 时，将“新增对象当前不存在”视为可承接的 ASIS 事实，而不是既有实现证据缺失。
• 读取上游设计、模块影响性分析、模块间交互设计和已有门禁整改项。
• 提取“关键契约清单”：从用户输入、上游设计、模块交互、ASIS context 和已有正式说明书中收集已经明确给出的接口、签名、DTO/字段、JSON 名称、错误码、Topic/Path、配置项和数据结构，在正式说明书中逐项承接；来源位置和内部追踪写入 .context.md。
• 如果正式说明书不存在，由 TOBE 阶段按 <skill-dir>/references/tobe-output-template.md 创建；如果存在，先读取当前内容，只更新 TOBE 负责的正式大纲章节。

2. 初步对齐设计范围

先粗略回答：

• 本次需求/AR 中哪些由本模块承担。
• 哪些明确不由本模块承担。
• 哪些属于相邻模块配套改动；这些改动只作为外部依赖、模块交互或前置确认项记录，不能直接纳入本模块实现任务。
• 本次可能影响哪些入口、组件、接口、数据、配置或测试。
• 上文显式给出的接口定义、方法签名、DTO/字段、JSON 示例、错误码、Topic/Path 等契约是否已逐项映射到正式说明书章节；缺失时必须先补齐，再定稿 TOBE。
• 需求中的模糊质量词或事件词如何落成可测定义，例如“及时”“稳定”“目录变更”“高频”“安全”等。
• 当前应使用轻量、标准还是增强输出。

这一步只用于确定范围和输出强度，不定稿 TOBE 决策。

3. 检查 ASIS 覆盖和阻塞

确认 ASIS 是否覆盖初步范围中的关键事实：

• 关键入口、流程、数据、配置、测试和外部交互是否有证据。
• 关键 ASIS 探索任务是否已完成，或已明确未完成原因、影响范围和下一步输入。
• TOBE 要引用的 ASIS 事实是否已在复核与吸收记录中标记为已吸收或修正后吸收。
• 关键结论是否为事实，还是推断/待确认/阻塞相关。
• 规格漂移、低置信度或测试缺口是否影响 TOBE 定稿。
• 纯新增场景下，ASIS 是否已确认模块边界，并提供新增对象不存在的检索证据、相邻同类实现或不存在相邻实现时可替代的模块惯例。

依赖 ASIS 阻塞项、低置信度结论、待确认关键事实、未完成关键探索任务或未经复核吸收的查证结果的 TOBE 决策不得定稿。只能继续设计与该阻塞无依赖的独立部分。

如果待确认项会影响模块边界、核心方案、数据/权限/兼容策略、性能目标、验收阈值、测试设计输入或后续任务拆分，必须立即向用户或上游负责人问询；若当前执行环境不能直接问询，则在成果物中标记为 需前置确认，并阻止依赖该问题的决策定稿。

4. 形成 TOBE 决策

围绕四条链输出最小充分设计：

• 边界与职责：本模块承担什么，不承担什么，是否需要更新上游设计或 software_architecture.md。
• 相邻模块配套：如果存在目标模块内改动 + 相邻模块配套改动，必须区分 本模块实现范围、相邻模块需配合事项、跨模块契约 和 需独立详设/前置确认项。
• 设计决策：新增、修改、复用、废弃、迁移或不做什么，为什么。
• 设计变量：字段、DTO、接口、配置、事件、状态值、错误码、时间单位、默认值和兼容语义，必须定义一次并全篇引用。
• 契约保真：对已明确给出的接口/签名/DTO/JSON/错误码/Topic/Path，不重新命名、不丢字段、不省略入参出参、不把精确签名改写成自然语言概要；如果需要变更，必须说明变更前、变更后、兼容策略和 ASIS/需求依据。
• 工程落点：涉及哪些文件、包、类、函数、API、数据、配置或开关，作为后续编码任务拆分输入。
• 可测定义：将影响验收的模糊质量词、事件触发条件和时效要求写成可测试的输入、阈值、观察点或断言。
• 流程/时序图：涉及多组件协作、跨模块交互、状态变化、写后读、异常路径或回滚时，至少输出一个 Mermaid 流程图或时序图，指导 AICoding 理解调用顺序与责任边界。

不要复制 ASIS 大段事实；正式说明书只保留影响设计的现状约束摘要，ASIS 结论编号和证据编号只写入 .context.md。

4.1 输出 TOBE 变化触发表

正式说明书必须按 <skill-dir>/references/tobe-output-template.md 的 9 个一级章节组织。第 8 章按需求点展开，是后续 AICoding 拆分的核心设计依据，不能只用一个总表替代正文。

可以在正式说明书中输出变化触发表或设计决策表，用来约束后续章节是否展开。

变化类型	是否涉及	若涉及，正式说明书必须输出
包/模块结构变化	是 / 否	包图、结构变化表、依赖方向和边界说明
类/接口变化	是 / 否	类图、类/接口/抽象类清单、关键方法签名、职责和约束
业务流程变化	是 / 否	主流程图；异常、回滚、异步、状态变化按需展开
REST 接口变化	是 / 否	Method、Path、认证/权限、请求、响应、错误码、兼容性
Kafka/MQ 接口变化	是 / 否	Topic、Producer/Consumer、消息结构、Key、幂等、重试、死信、兼容策略
内部 Java 接口/抽象变化	是 / 否	调用方、实现方、方法签名、入参出参、异常语义、扩展约束
数据库变化	是 / 否	表/字段/索引、约束、默认值、迁移/回填、兼容策略、回滚策略
配置/开关变化	是 / 否	配置项、默认值、环境差异、灰度策略、关闭后的 ASIS 行为

标记为“是”的变化类型必须在正式说明书中展开。标记为“否”的变化类型写一句不涉及原因即可，不生成空表。

4.2 输出关键开发视图

根据正式大纲和变化触发表在正式说明书中输出：

• 包/模块结构设计：只画本次变化相关包图，必须体现依赖方向、模块边界和防腐位置。
• 类与接口设计：只画关键类图，列出 Class、Interface、AbstractClass、Enum、DTO、Adapter 等职责、关键方法、完整方法/函数签名、入参、出参、异常和设计约束。若上文已有明确签名，必须保留该签名并标注来源。
• 业务流程设计：输出主流程；涉及失败路径、回滚、事务、异步、状态变化时，补充异常与回退流程。
• 对外接口设计：REST 必须写 method、path、权限、请求体字段、响应体字段、错误码、示例和兼容性；Kafka/MQ 必须写 topic、producer/consumer、消息结构字段、key、幂等、重试、死信和兼容策略。若上文已有明确接口契约，正式说明书不得省略任何字段。
• 内部接口与调用设计：写清调用方、实现方、方法/函数完整签名、每个入参和出参的类型与语义、异常语义和依赖方向；新增抽象必须说明扩展目的，禁止无真实扩展点的过度抽象。
• 数据库设计变化：写清表、字段、索引、可空性、默认值、约束、迁移/回填、兼容和回滚。
• 配置与开关：写清配置项、默认值、环境差异、灰度和关闭后的 ASIS 行为。

这些视图是正式说明书的开发指导内容，不能只写入 .context.md。

4.3 跨章节一致性约束

TOBE 定稿前，检查正式说明书中的关键设计变量是否一致：

• 同一字段在前端类型、后端模型、JSON 示例、接口表、配置表、工程落点、可测试性输入和风险章节中使用同一类型、单位、默认值和兼容语义。
• 同一接口在类图、内部接口表、流程图、工程落点和可测试性输入中使用同一方法名、入参、出参和异常语义。
• 关键契约清单中的每个接口、签名、DTO 字段、JSON 名称、错误码、Topic/Path 都能在正式说明书中反查到对应章节；如果不能反查，TOBE 状态必须标记为 部分完成 或 阻塞。
• 同一状态值、枚举、错误码、topic、path、配置项在摘要、设计决策、风险和验证章节中不得出现不同拼写或不同含义。
• 时间字段必须明确单位和时区语义，例如 Unix epoch milliseconds、UTC ISO-8601 或数据库时间类型；不能在同一说明书中混用。
• 如果在推导过程中替换了设计方案，必须同步更新摘要、图、表、JSON 示例、工程落点、可测试性输入和风险章节；无法同步时，TOBE 状态标记为 部分完成 或 阻塞。

5. 展开被触发的风险专题

只展开被触发的风险专题；未触发时写明不适用原因。

• 架构防腐化：跨模块、跨层、依赖方向、外部模型、公共接口、共享状态变化。
• 安全增强：支付、隐私、凭证/密钥、权限边界、跨租户数据、外部输入、文件路径、命令执行、审计合规、AI/LLM 上下文污染。
• 性能增强：高频调用、批处理、大数据量、同步核心链路、启动路径、核心交易链路、明确 SLA、资源瓶颈、缓存/降级策略变化。
• 日志可观测性：主流程追踪、错误路径定位、日志密度、敏感信息脱敏、指标/告警。
• 兼容/迁移/回滚：接口签名、数据结构、配置默认值、迁移回填、灰度和回退。
• 并发/事务/幂等：状态变更、重复请求、重试、超时、补偿、数据一致性。

安全和性能采用两档强度：

• 普通分析：默认强度，说明输入边界、权限/敏感信息、复杂度、I/O、内存、日志密度和验证方式；不适用项写明原因。
• 增强分析：风险触发时启用。安全补攻击面、数据分级、信任边界、滥用场景、缓解措施和验证方式；性能补 ASIS 基线或现状估计、目标指标或 SLA、负载估算、瓶颈风险、验证方法和回退策略。

6. 更新成果物

加载 <skill-dir>/references/tobe-output-template.md，按输出模式创建或更新正式说明书；加载 <skill-dir>/references/tobe-context-template.md，把 TOBE 推导、替代方案、反证记录和完整追踪矩阵写入同名前缀 .context.md。

• 轻量输出：合并章节，保留最小充分信息，空表用“不适用，原因...”替代。
• 标准输出：保留核心骨架，展开与本次需求相关的设计点和风险专题。
• 增强输出：补齐触发风险专题的专项分析和更严格验证设计。
• 第 8 章必须按需求点展开 需求描述 / 现状约束摘要 / TOBE 设计说明 / 类接口数据结构变化 / 处理流程 / 异常回退边界场景 / 配置开关环境差异 / 日志可观测性 / 可测试性与验收口径。

返工时只更新受影响章节，并在 TOBE 变更记录中说明变更内容。

阻塞规则

出现以下情况时标记 TOBE 阻塞或部分完成：

• ASIS context 中的阻塞项直接影响本次 TOBE 决策。
• .context.md 中需求/AR 与 ASIS 证据映射存在关键未覆盖项。
• 上文或上游产物已经明确给出的接口定义、方法签名、DTO/字段、JSON 示例、错误码、Topic/Path、配置项或数据结构无法在正式说明书中完整承接。
• 上游设计互相矛盾，导致无法判断本模块职责。
• 模块间交互设计缺失或冲突，导致接口、事件或数据归属无法确定。
• 相邻模块配套改动的接口、数据、时序或职责未确认，且会影响本模块核心设计、测试设计输入、后续 AICoding 任务拆分或验收边界。
• 关键兼容、迁移、权限、数据一致性、安全或性能策略无法从现有材料判断。

阻塞输出必须包含：阻塞原因、受影响的 TOBE 决策、需要回补的 ASIS 或上游输入、当前可继续设计的独立范围、不得定稿的设计决策、对 AICoding 的影响。

质量标准

结束前确认：

• 输出遵循本 skill 阶段规则和当前输出模式。
• 证据链、边界链、执行链、风险链已闭合，或阻塞项已显性化。
• 每条重要 TOBE 决策在正式说明书中有用户可读的设计依据摘要，并能在 .context.md 中反查需求/AR 来源、ASIS 探索任务、复核吸收记录和 ASIS 证据编号。
• 未完成、低置信度或未经复核吸收的 ASIS 探索结果没有被降级成 TOBE 事实。
• 设计没有越过模块职责边界。
• 字段、DTO、接口、配置项、事件名、错误码、状态值和时间单位在正式说明书内前后一致。
• 工程落点能定位到具体文件或代码区域，并包含后续测试设计需要的可测试性输入。
• 触发的风险专题已展开；未触发的专题有不适用说明。
• 安全和性能按普通/增强两档选择了合适强度。
• 未决问题和阻塞项没有被伪装成设计结论。

流程结束 / 工作流衔接

本 skill 产出正式《{AR编号}-{需求短名}-{模块名}模块详细设计说明书.md》和同名前缀 .context.md（含 TOBE 推导、追踪矩阵、待确认项），交付给 $module-test-design 和 $module-design-gate。测试设计读取正式说明书的 TOBE 决策、契约、流程、异常边界、风险和可测试性输入；Gate 读取正式说明书和测试设计做准入判断。

引用文件

• TOBE 输出模板：<skill-dir>/references/tobe-output-template.md
• TOBE context 模板：<skill-dir>/references/tobe-context-template.md

你可以通过字体颜色突出你觉得重要的部分内容 (使用 HTML 标签)

Markdown 本身不支持直接修改颜色，但你可以完美内嵌 HTML：

• 这是红色字体
• 这是绿色字体

完成后回调

若不处于 aaw-workflow 编排中，请忽略此节。

本 skill 由 aaw-workflow 编排调用。交付件生成后：

1. 返回 aaw-workflow 流程
2. 执行 aaw next --sr <SR号> --json 查看进度
3. 若返回 deliverables_exist: true → 直接 aaw done --sr <SR> <id>
4. 否则 → 停止；是否放行下一步由 aaw-workflow 的 user_confirm 策略控制

不记得 SR 号 → 先 aaw status --json