module-tobe-design

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 或功能区域。
• 编码约束、测试要求、发布策略、验收标准。

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

输出模式

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

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

轻量模式至少保留：

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

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

工作流程

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

flowchart TD
    S1["§1 读取正式说明书 + 详细设计上下文<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/>正式说明书 + 详细设计上下文"]
    S6 --> Q{"质量标准达标?"}
    Q -->|"否"| S4
    Q -->|"是"| DONE["交付: 进入测试设计 / Gate"]

关键脉络：

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

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

1. 读取正式说明书和详细设计上下文

• 定位当前 SDD 工作流指定的 .sdd/{SR}/{AR}/{模块组名}/模块详细设计说明书.md 和同一模块目录下的 .context/详细设计上下文.md。
• 读取详细设计上下文中的关键 ASIS 事实（C3）、证据索引（C7）、模块边界（C2）、调用链与数据流（C4）、规格漂移与待确认（C6）和需求/AR 追溯矩阵（C8）。
• 读取 ASIS 变更类型；当变更类型为 纯新增行为 时，将“新增对象当前不存在”视为可承接的 ASIS 事实，而不是既有实现证据缺失。
• 读取上游设计、模块影响性分析、模块间交互设计和已有门禁整改项。
• 提取“关键契约清单”：从用户输入、上游设计、模块交互、ASIS context 和已有正式说明书中收集已经明确给出的接口、签名、DTO/字段、JSON 名称、错误码、Topic/Path、配置项和数据结构。契约的实质内容（字段、签名、入参出参等）写入对应设计问题的“契约与工程落点”，第 8 章关键契约清单只登记编号、类型、名称和权威定义位置；来源位置和内部追踪写入详细设计上下文。
• 如果正式说明书不存在，由 TOBE 阶段按 <skill-dir>/references/tobe-output-template.md 创建；如果存在，先读取当前内容，只更新 TOBE 负责的正式大纲章节。

2. 初步对齐设计范围

先粗略回答：

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

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

外部依赖的信息边界

第 2 章只记录与本次变更相关，且会影响设计决策、实现约束或风险处理的外部依赖，不复述项目技术栈。每项必须写清对本次设计的具体影响；删除该项不影响开发或评审判断时，应省略或引用已有文档。没有相关依赖时写明“不涉及”及原因。

3. 检查 ASIS 覆盖和阻塞

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

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

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

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

4. 形成 TOBE 决策

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

• 边界与职责：本模块承担什么，不承担什么，是否需要更新上游设计或 software_architecture.md。
• 相邻模块配套：如果存在目标模块内改动 + 相邻模块配套改动，必须区分 本模块实现范围、相邻模块需配合事项、跨模块契约 和 需独立详设/前置确认项。
• 设计决策：新增、修改、复用、废弃、迁移或不做什么，为什么。
• 评审信息：关键决策写清影响范围、重要取舍和需要用户确认的判断点，使读者能评估方案正确性与代价；没有真实备选方案时不机械编造方案对比。
• 设计变量：字段、DTO、接口、配置、事件、状态值、错误码、时间单位、默认值和兼容语义，必须定义一次并全篇引用。
• 契约保真：对已明确给出的接口/签名/DTO/JSON/错误码/Topic/Path，不重新命名、不丢字段、不省略入参出参、不把精确签名改写成自然语言概要；如果需要变更，必须说明变更前、变更后、兼容策略和 ASIS/需求依据。
• 工程落点：定位到受影响的包、现有文件或代码区域及职责。不得为了让任务“看起来可拆分”而发明私有文件、helper、临时类型或完整内部签名。
• 兼容不等于顺手治理历史债：现状中与本需求无关的不一致、旧格式或技术债应保持既有语义并记录风险；只有上游要求或本需求正确性必需时，才把统一、迁移或清理纳入目标设计。
• 可测定义：将影响验收的模糊质量词、事件触发条件和时效要求写成可测试的输入、阈值、观察点或断言。
• 核心算法与关键设计模式：仅在它们决定行为正确性、职责协作或扩展边界时展开，说明实现必须保持的语义、约束和取舍，不输出生产级实现代码。
• 图示：当读者需要同时追踪三个及以上参与者、步骤或状态，且存在跨边界协作、关键分支/失败回退、状态转换或非显然依赖时，在“目标设计”中输出一张最小必要 Mermaid 流程图、时序图、状态图或关系图；简单线性流程、字段映射或表格更清楚时不画。图须让主路径和关键失败/回退路径可完整走通，与权威契约一致，不发明私有实现，正文不逐项复述；同一关系只画一次，只有另一张图回答不同评审问题时才增加。

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

4.1 输出 TOBE 变化触发表

正式说明书必须按 <skill-dir>/references/tobe-output-template.md 的 9 个一级章节组织。第 4 章按相互独立的设计问题展开；同一流程中的增量、失败、报告等强相关行为应合并说明，不为每个需求条目机械复制固定小节。

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

变化类型	是否涉及	若涉及，正式说明书必须输出（权威位置）
包/模块结构变化	是 / 否	依赖变更视图、边界与架构依据 → 对应设计问题
类/接口变化	是 / 否	跨边界契约、职责和约束；涉及依赖变化时纳入依赖变更视图 → 契约与工程落点
业务流程变化	是 / 否	主流程；异常、回滚、异步、状态变化按需展开 → 目标设计 / 失败语义
REST 接口变化	是 / 否	Method、Path、认证/权限、请求、响应、错误码、兼容性 → 契约与工程落点（第 5 章只放索引）
Kafka/MQ 接口变化	是 / 否	Topic、Producer/Consumer、消息结构、Key、幂等、重试、死信、兼容策略 → 契约与工程落点（第 5 章只放索引）
内部 Java 接口/抽象变化	是 / 否	调用角色、输入输出语义、异常边界和扩展约束 → 契约与工程落点（第 7 章只放概览）
数据库变化	是 / 否	表/字段/索引、约束、默认值、迁移/回填、兼容策略、回滚策略 → 第 6 章
配置/开关变化	是 / 否	配置项、默认值、环境差异、灰度策略、关闭后的 ASIS 行为 → 3.1 决策表 / 第 2 章外部依赖

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

4.2 输出关键开发视图

根据正式大纲和变化触发表在正式说明书中输出。契约在对应设计问题的“契约与工程落点”单点定义，流程在“目标设计”单点说明；第 5 章对外接口、第 7 章受影响模块与交互、第 8 章关键契约清单均为索引/概览，只引用权威位置，不复述字段细节、签名或图。

• 依赖关系设计：新增、移除、反转或跨越模块/分层边界的依赖，必须用最小图或表展示变化前后方向、职责归属、允许/禁止关系及架构依据；关系需要同时比较三个以上对象时优先画关系图。模块内部只呈现影响职责评审的稳定关系，不展开私有实现。
• 类与接口设计：说明决定边界或协作方式的职责、依赖和设计约束。只有上文已有明确签名，或该接口会被跨模块/对外调用时，才保留完整签名、入参、出参和异常语义；私有实现结构留给 AICoding。关系复杂且图能降低理解成本时再画类图。
• 业务流程设计：说明主流程；涉及失败路径、回滚、事务、异步、状态变化时，补充异常与回退语义。
• 对外接口设计：REST 必须写 method、path、权限、请求体字段、响应体字段、错误码、示例和兼容性；Kafka/MQ 必须写 topic、producer/consumer、消息结构字段、key、幂等、重试、死信和兼容策略。若上文已有明确接口契约，正式说明书不得省略任何字段。字段细节写入“契约与工程落点”；第 5 章对外接口只放索引。
• 内部接口与调用设计：写清调用角色、依赖方向、输入输出语义和异常边界；只有既有兼容契约要求时才固定内部完整签名。新增抽象必须说明扩展目的、协作方式和局限，禁止无真实扩展点的过度抽象。第 7 章受影响模块与交互只放概览表。
• 数据库设计变化：写清表、字段、索引、可空性、默认值、约束、迁移/回填、兼容和回滚。→ 第 6 章
• 配置与开关：写清配置项、默认值、环境差异、灰度和关闭后的 ASIS 行为。→ 3.1 决策表 / 第 2 章外部依赖

这些视图是正式说明书的开发指导内容，不能只写入详细设计上下文。

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 推导、替代方案、反证记录和完整追踪矩阵写入同名前缀 详细设计上下文。

• 轻量输出：合并章节，保留最小充分信息，空表用“不适用，原因...”替代。概览章（第 5/7/8 章）不展开实质内容，只保留索引和引用。
• 标准输出：保留核心骨架，展开与本次需求相关的设计点和风险专题。实质内容集中在各设计问题的权威位置，概览章只引用。
• 增强输出：补齐触发风险专题的专项分析和更严格验证设计。同样遵循权威位置约定，概览章不重复实质内容。
• 第 4 章按独立设计问题展开 目标与约束 / 目标设计 / 契约与工程落点 / 失败语义、风险与验收；强相关内容合并，未触发内容省略。
• 定稿前按读者视角删减：用户无法据此判断方案的段落、AICoding 不需要的实现细节、与权威位置重复的事实和不影响本次设计的背景不进入正式说明书。

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

阻塞规则

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

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

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

质量标准

结束前确认：

• 输出遵循本 skill 阶段规则和当前输出模式。
• 证据链、边界链、执行链、风险链已闭合，或阻塞项已显性化。
• 每条重要 TOBE 决策在正式说明书中有用户可读的设计依据摘要，并能在详细设计上下文中反查需求/AR 来源（C8 追溯矩阵）、关键 ASIS 事实（C3）和 ASIS 证据编号（C7）。
• 未完成、低置信度或未经复核吸收的 ASIS 探索结果没有被降级成 TOBE 事实。
• 设计没有越过模块职责边界。
• 每项依赖变化都能从最小图或表直接判断变化前后方向、职责归属、允许/禁止关系及架构依据。
• 字段、DTO、接口、配置项、事件名、错误码、状态值和时间单位在正式说明书内前后一致。
• 工程落点能定位到具体文件或代码区域，并包含后续测试设计需要的可测试性输入。
• 用户和评审者无需阅读生产代码即可判断关键设计结论、影响、取舍、风险和验收口径是否正确。
• AICoding 能从正式说明书确定目标行为、契约、边界和失败语义，同时仍可自主选择满足约束的具体代码结构；正式说明书没有用完整实现替代设计说明。
• 影响正确性的核心算法和影响职责或扩展边界的关键设计模式已讲清；不适用时没有为了填充章节牵强引入算法或模式。
• 正式说明书不存在大段重复背景、跨章节重复定义、逐行代码解释、同义改写或空泛原则；每段均提供新的设计事实、依据、约束、风险或验证信息。
• 触发的风险专题已展开；未触发的专题有不适用说明。
• 安全和性能按普通/增强两档选择了合适强度。
• 未决问题和阻塞项没有被伪装成设计结论。

流程结束 / 工作流衔接

本 skill 产出正式《模块详细设计说明书.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