Module design gate

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

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

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

是否回到 aaw-workflow 工作流中执行？

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

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

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

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

SDD 模块设计门禁

阶段规则

本 skill 自身定义门禁阶段必须遵守的规则，可独立检查正式说明书；无论由何种入口调用，均以本 skill 的规则作为 Gate 阶段唯一执行依据。

运行方式

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

如果当前环境提供 ask_user 工具，影响门禁结论、有限准入范围、核心设计或验收阈值的待确认项必须优先用 ask_user 发起问询，并在 .context/模块设计门禁结果.md 中记录问题、回答、影响范围和处理结论；工具不可用时，才退回当前会话问询或标记为 需前置确认。

门禁不检查“章节是否写满”，而检查正式说明书和测试设计是否满足八个准入维度。Gate 的准入结论以维度化门禁结果为准；五链检查、严格探索和采样记录只用于支撑维度判断，不得绕过未达标维度直接给出通过。

八个准入维度是：

• 上游完整性。
• 证据充分性。
• 边界清晰性。
• 决策确定性。
• 契约完整性。
• 工程可执行性。
• 验证闭环性。
• 风险处置性。

五链是维度检查的证据结构，不是独立于维度的第二套准入体系：

• 证据链：需求/AR -> ASIS 证据 -> TOBE 决策。
• 边界链：模块边界 -> 职责分配 -> 交互约束。
• 执行链：TOBE 决策 -> 工程落点和开发视图 -> 后续 AICoding 可拆分。
• 验证链：TOBE 决策 -> 可测试性输入 -> 覆盖目标 -> 测试用例 -> 断言/观察点。
• 风险链：触发风险 -> 缓解设计 -> 验证/回退。

维度与五链的主要对应关系：

• 证据充分性、决策确定性主要由证据链支撑。
• 边界清晰性主要由边界链支撑。
• 契约完整性、工程可执行性主要由执行链支撑。
• 验证闭环性主要由验证链支撑。
• 风险处置性主要由风险链支撑。

成果物协作规则

• 正式成果物：.sdd/{SR}/{AR}/{模块组名}/模块详细设计说明书.md。
• 测试设计：.sdd/{SR}/{AR}/{模块组名}/模块测试用例设计.md。
• 详细设计上下文：.sdd/{SR}/{AR}/{模块组名}/.context/详细设计上下文.md。
• 门禁结果：.sdd/{SR}/{AR}/{模块组名}/.context/模块设计门禁结果.md。
• 需要综合之前的其他设计成果物进行审视
• {模块组名} 使用当前工作流确认的模块或模块组目录名；四个固定文件必须属于同一模块目录。
• 本 skill 不得创建、编辑或覆盖正式说明书中的任何章节。
• 本 skill 不得创建、编辑或覆盖测试设计成果物中的任何章节。
• 本 skill 在门禁结果文件中的写入边界是门禁结论（C1）、阻断问题（C2）、非阻断改进项（C3）、整改清单（C4）、上游设计反查（C5）、前置问询复核（C6）和遗留问题闭环复核（C7）。gate 的内部工作过程（执行 todo-list、逐维度达标判定、ASIS 采样记录、严格探索记录、大纲符合性检查、五链摘要、风险专题复核）不写入结果文件。
• 某项输入缺失会影响最终结论，但不能成为提前结束其他检查的理由；Gate 必须继续审查所有可读成果物，把能够独立发现的问题一并写入结果。
• 本 skill 可以读取 ASIS、TOBE、测试设计和风险章节，但不得直接覆盖其正文。
• 只有工作流、用户或成果物拆分规则明确要求时，门禁结果才写入独立门禁成果物，否则在当前会话返回。若由 aaw-workflow 编排调用，必须写入工作单 output 指定的 .context/模块设计门禁结果.md。
• 门禁引用的需求/AR 编号、TOBE 决策编号和契约编号必须来自正式说明书；覆盖目标、测试用例和测试缺口编号必须来自独立测试设计；ASIS 证据编号必须能在 .context/详细设计上下文.md 的证据索引中反查。
• 如果某项开发必需内容只存在于详细设计上下文，正式说明书门禁必须判定为不通过，问题类型为 EXECUTION 或对应链路问题。
• 如果某项验证必需内容只存在于详细设计上下文或会话说明，测试设计门禁必须判定为不通过，问题类型为 EXECUTION 或 RISK ，关联维度为 验证闭环性。
• 正式说明书必须是面向用户、评审和开发的标准交付件；若正式说明书包含 ASIS 检索过程、证据编号表、TOBE 推导过程、反证记录、门禁采样、追踪矩阵等过程性内容，或必须阅读详细设计上下文才能理解设计结论，门禁必须判定为不通过，问题类型为 EXECUTION。
• 测试设计必须是面向测试实现和验证执行的标准交付件；正式测试设计不要求暴露目标抽取、风险分级、用例合并等推导过程。Gate 不检查“是否写了过程”，而是从最小充分测试集、覆盖矩阵、用例可执行性和缺口回流反推测试设计质量。若测试用例只写“补充单测”“验证异常”“覆盖兼容”等概要，缺少输入、前置条件、断言、观察点或建议位置，门禁必须判定验证闭环性不通过。

强制工作步骤和 todo-list

Gate 阶段有偷懒风险，必须显式使用 todo-list 类工具跟踪检查过程，例如当前环境可用的 update_plan、TODO 工具或等价任务清单。没有可用工具时，必须在当前回复或 context 中维护“门禁待办清单”，并逐项标记状态。

开始门禁前必须创建至少包含以下项目的 todo-list（对应「工作流程」的步骤）：

1. 定位成果物与基线（说明书/测试设计/context/SR-design/AR-clarify）。
2. 执行检查：上游反查 → 八维度逐项 → 前置问询 → 遗留闭环 → 严格探索（见 gate-checklist.md 各节）。
3. 汇总未达标维度、阻断问题、整改清单，输出门禁结论和下一轮重试条件。

执行过程中必须在完成每个步骤后更新 todo-list 状态，并在维度化门禁检查表中逐项判定八个适用维度。不得在八个适用维度未逐项判定的情况下直接给出 通过、不通过 或 阻塞 结论。

门禁结论

门禁结论只能是：

• 通过：所有适用维度均达标，阻断问题为 0，可进入 AICoding。
• 不通过：存在必须整改的问题，需回到 ASIS、TOBE、测试设计或上游设计对齐。
• 阻塞：缺少必要输入、代码、上游决策，或连续返工仍因同一外部缺口无法推进。

门禁还必须给出明确的门禁建议，用于指导下一轮重试：

• 可进入 AICoding：所有适用维度达标，且阻断问题为 0。
• 回 ASIS 补证据后重试：证据充分性未达标，或 ASIS 证据不能支撑 TOBE。
• 回 TOBE 补设计后重试：决策确定性、契约完整性、工程可执行性、风险处置性未达标，或验证闭环性未达标且根因是 TOBE 可测试性输入不足。
• 回测试设计补用例后重试：验证闭环性未达标，且根因是测试设计未形成最小充分验证集、覆盖矩阵或可执行用例。
• 先做上游/用户确认：核心方案、模块边界、接口归属、数据归属、验收阈值或跨模块职责仍需外部确认。
• 拆分范围后有限进入 AICoding：未达标维度不影响某个独立子范围，且正式说明书已明确隔离该子范围的任务、边界和验证方式。
• 阻塞，缺少必要输入：无法完成门禁判断所需的正式说明书、context、代码、架构边界或上游决策。

除 拆分范围后有限进入 AICoding 的受限场景外，只要存在任一适用维度未达标，门禁结论不得为 通过。

维度化门禁建议

门禁必须在内部按以下维度判断 达标 / 未达标 / 不适用，结果文件只列未达标维度及其问题，不输出“全部达标”过程表。每个未达标维度给出发现、影响、建议返工阶段和下一轮重试通过条件；五链检查、严格探索和采样记录用于支撑或反证结论。

维度	关注点	未达标时默认建议
上游完整性	模块详设和测试设计与 SR/AR-clarify 已确认的设计决策是否冲突，有无关键性遗漏	回 TOBE 补承接后重试；必要时回 ASIS 或上游确认
证据充分性	需求、ASIS 结论、证据索引是否足以支撑 TOBE	回 ASIS 补证据后重试
边界清晰性	模块边界、职责、不承担范围、跨模块关系是否清楚	回 ASIS 或上游架构确认
决策确定性	关键方案是否已定稿并说明依据、影响和评审关注点，用户能否判断行为、边界、取舍和风险是否正确	回 TOBE 补设计后重试
契约完整性	上游已明确或跨边界稳定依赖的函数、接口、DTO、配置、错误码、路径规则等是否有完整定义；私有实现结构是否被误当成契约固定	回 TOBE 补设计后重试
工程可执行性	TOBE 是否给出工程落点、契约、流程、异常、配置和风险处理，讲清适用的核心算法与关键设计模式，同时没有用生产级实现干扰后续 AICoding	回 TOBE 补设计后重试
验证闭环性	测试设计是否覆盖每个关键设计目标、失败路径和触发风险，并给出输入、前置条件、断言、观察点和建议位置	回测试设计补用例；若 TOBE 缺可测试性输入则回 TOBE；若缺现状测试证据则回 ASIS
风险处置性	触发的安全、兼容、回滚、性能、并发、观测风险是否有缓解、验证和回退	回 TOBE 补设计后重试或上游确认

维度未达标的常见判定：

• 影响实现的“建议 / 可选 / 如有需要 / 推荐 / 尽量 / 是否需要 / 待定”没有被明确标为非阻断改进项。
• 只写“抽一个 helper”“增加校验”“优化错误文案”“实现上述方案”，但没有写清契约、调用边界或完成判定。
• 关键目标或风险缓解没有对应测试用例、断言、观察点或人工验证步骤。
• 测试设计机械枚举测试类型或一设计点一用例，导致 P2/低价值用例挤占 P0/P1，且没有说明合并覆盖或最小充分策略。
• 详细设计上下文中存在影响实现的待确认项，但正式说明书或门禁结论没有把它转成阻断问题。
• 关键开发信息只存在于详细设计上下文，正式说明书自身不能指导编码。
• 核心算法影响行为正确性，却没有说明输入输出、不变量、关键分支、结束/失败行为或规模约束。
• 关键设计模式影响职责、协作或扩展边界，却只写模式名称，没有说明参与者、协作关系、扩展点和局限。
• 正式说明书用完整函数/类实现、可运行控制流、样板代码或完整迁移脚本代替设计约束，导致后续 AICoding 被非必要实现选择误导或限制。
• 同一事实跨章节重复定义、背景或代码解释淹没关键决策，导致用户难以评审或 AICoding 难以识别权威设计。

工作流程

开始时使用 todo-list 类工具建立检查计划，按顺序完成以下步骤。每个步骤的检查项细节见 gate-checklist.md 对应节，本节不重复。

1. 定位成果物与基线

• 读取正式说明书；路径未指定或文件不存在时，门禁状态为 阻塞。
• 读取测试设计文件；路径未指定或文件不存在时，门禁状态为 不通过 或 阻塞。
• 读取 .context/详细设计上下文.md 作为证据和过程复核材料，但不得把 context 中独有的开发信息视为正式说明书已满足。
• 读取之前的其他设计成果物对正式说明书进行综合审视。
• 读取上游反查基线：SR-design.md 和本 AR 的 AR-clarify.md；两者缺失或不可读时门禁状态为 阻塞。
• 如果存在上一轮未关闭的阻断问题、整改项、待确认项或阻塞项，必须纳入本轮门禁输入。

2. 执行检查

按 gate-checklist.md 逐节执行，不得跳过：

1. 上游设计反查（checklist §1.1）：以 SR/AR-clarify 为基线，检查冲突和关键性遗漏。
2. 八个准入维度逐项检查（checklist §1-§5）：上游完整性、证据充分性、边界清晰性、决策确定性、契约完整性、工程可执行性、验证闭环性、风险处置性。每个维度给出 达标 / 未达标 / 不适用。
3. 前置问询检查（checklist §6.1）：影响核心设计的待确认项是否已问询或标记阻塞。
4. 遗留问题闭环（checklist §6）：上一轮阻断问题逐项复核，未闭环不得通过。
5. 严格探索（checklist §6.6）：主动找反例——模拟用户评审和 AICoding 拆分、检查实现细节边界、核心算法与关键设计模式、信息密度，再执行架构反证、替代方案对比、主流程追踪、失败路径追踪和契约保真追踪。

即使某个成果物缺失或已足以判定不通过，也要完成其他可执行检查；不得只报告第一个阻断项。

ASIS 倾向采样要求：至少抽查 3 个 ASIS 结论；少于 3 个则全查。高风险、大规模、跨模块、低置信度、边界冲突、规格漂移、未完成探索任务或核心链路影响时，必须风险加抽。

3. 输出门禁结果

加载 <skill-dir>/references/gate-result-template.md，输出门禁结论（C1）、阻断问题（C2）、非阻断改进项（C3）、整改清单（C4）、上游设计反查（C5）、前置问询复核（C6）和遗留问题闭环复核（C7）。门禁结果写入工作流指定的独立门禁结果文件或作为当前会话结果返回，不写入正式说明书或测试设计正文。

阻断问题分五类：

• EVIDENCE：证据不足或不确定性被伪装成事实。
• UPSTREAM：模块详设或测试设计与 SR/AR-clarify 已确认的设计决策矛盾，或存在关键性遗漏（上游明确要求的行为、约束或验收完全没有承接且无法推导）。表达载体不同或约束已隐含落实到具体设计的不属此类。
• BOUNDARY：边界、职责、交互或防腐蚀不成立。
• EXECUTION：TOBE 不足以支撑用户评审或后续 AICoding 拆分、适用的核心算法/关键设计模式未讲清、生产级实现细节替代或干扰设计约束、测试设计不可执行、验证不可追踪，或正式说明书丢失上文已经明确给出的接口契约、方法签名、入参出参、DTO/字段等开发必需信息。
• RISK：触发风险没有缓解、验证或回退。

每个阻断问题必须关联至少一个未达标维度，并写明下一轮重试通过条件。

9. 流程结束 / 工作流衔接

本 skill 产出门禁结论（通过 / 不通过 / 阻塞）、门禁建议和整改清单，写入 .context/模块设计门禁结果.md 或当前会话。门禁是 SDD 设计阶段的终点：通过 则成果物交付给后续 AICoding；不通过 或 阻塞 则回流到 $module-asis-analysis / $module-tobe-design / $module-test-design 整改后复检。

多轮复检规则

门禁不通过时：

1. 生成整改清单。
2. 判断每个整改项应回到 ASIS、TOBE、测试设计、上游设计对齐还是模块间交互设计。
3. 如果当前 agent 能补齐，回到对应阶段更新对应成果物后重新门禁：ASIS 只更新详细设计上下文，TOBE 更新正式说明书并补充 详细设计上下文中的推导过程，测试设计只更新独立测试用例设计文件。
4. 如果不能补齐，标记阻塞并说明需要的输入。
5. 复检时保留轮次记录，说明完成项、待闭合问题和整改要求。
6. 下一轮门禁必须先复核上一轮遗留问题闭环情况；未闭环的问题不得丢失、重编号后掩盖或从阻断问题中静默移除。

质量标准

结束前确认：

• 门禁结论是 通过、不通过 或 阻塞 之一。
• 已输出门禁建议，且建议与未达标维度一致。
• 已使用 todo-list 类工具或等价清单逐项执行并更新门禁检查状态。
• 已在内部按八个维度逐项判断，结果文件仅列未达标维度和最小质量取证，没有输出逐项“达标”过程表。
• 已以 SR-design.md 和 AR-clarify.md 为基线完成上游设计反查；模块详设和测试设计与上游已确认的设计决策无冲突，无关键性遗漏。
• 已检查详细设计上下文中关键 ASIS 事实（C3）的类型列——不存在未升级为"事实"/"修正后事实"的"推断"或"待确认"结论被 TOBE 当成事实引用。
• 已确认用户和评审者能从正式说明书判断关键方案、影响、取舍、风险和验收口径，不必通过阅读生产代码反推设计。
• 已检查实现细节边界、适用的核心算法和关键设计模式，以及冗余、重复、空泛和权威定义冲突等低质量特征。
• 五条链均有明确结论。
• 上一轮遗留问题、整改项、待确认项和阻塞项均有闭环状态和证据；未逐项复核时不得通过。
• 阻断问题与非阻断改进项分离。
• 每个阻断问题都有明确返工阶段和整改要求。
• 每个未达标维度都有下一轮重试通过条件。
• 通过时明确说明可进入 AICoding。
• 不通过或阻塞时明确说明不可进入 AICoding，或仅允许哪些有限范围进入 AICoding。

引用文件

• 门禁结果模板：<skill-dir>/references/gate-result-template.md
• 检查清单（工作流程依赖）：<skill-dir>/references/gate-checklist.md

完成后回调

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

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

1. 将门禁结果写入工作单 output 指定的门禁结果文件。

2. 若门禁结论为 通过，构造数据文件并执行工作单中的 commands.done。执行前先向用户输出门禁结论摘要和门禁结果文件路径；这只是告知，不要等待用户答复，也不要因此暂停推进到 task-split：

   {
     "gate_result": "pass",
     "recommendation": "可进入 AICoding",
     "report": "门禁结果文件路径或摘要"
   }
   

3. 若门禁结论为 不通过，不要推进到 task-split。保持当前 gate step 未完成，按整改清单原地修正 ASIS/TOBE/测试设计成果物后重新执行 gate。必要时可提交 {"gate_result":"fail"} 获取 CLI 拒绝提示。

4. 若门禁结论为 阻塞，不要推进到 task-split。补齐门禁结果中列出的必要输入后重新执行 gate。必要时可提交 {"gate_result":"blocked"} 获取 CLI 拒绝提示。

5. 不要自动执行 aaw rollback。只有用户明确要求重走上游节点，或已经生成了需要废弃的下游 step 时，才使用 rollback。

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