module-test-design

name	module-test-design
description	基于正式《{AR编号}-{需求短名}-{模块名}模块详细设计说明书.md》、同名前缀 `.context.md` 的 ASIS 测试覆盖现状和 TOBE 可测试性输入，生成独立《{AR编号}-{需求短名}-{模块名}模块测试用例设计.md》。本 skill 只输出最小充分测试用例集、覆盖矩阵、断言、建议位置和缺口；不得替 TOBE 补设计，不得拆分 AICoding 任务。

SDD 模块测试用例设计

阶段规则

本 skill 自身定义测试用例设计阶段必须遵守的规则。它位于 $module-tobe-design 之后、$module-design-gate 之前，用于把 TOBE 中已经定稿的设计目标、契约、流程、异常边界、风险和可测试性输入转化为可执行的最小充分验证集。

本 skill 不编辑正式模块详细设计说明书正文，不覆盖 ASIS 事实，不拆分 AICoding 任务。若发现 TOBE 设计不足以支撑测试设计，必须输出阻塞或待补设计问题，要求回到 TOBE；不得自行补充错误码、字段语义、状态流转、兼容策略或验收阈值。

运行方式

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

如果当前环境提供 ask_user 工具，影响测试范围、验收阈值、人工验证边界或回流阶段的待确认项必须优先用 ask_user 发起问询，并在 .context.md 中记录问题、回答、影响范围和处理结论；测试设计只承接已确认的测试结论、缺口或回流建议。工具不可用时，才退回当前会话问询或标记为 需前置确认。

成果物协作规则

• 输入正式说明书：{AR编号}-{需求短名}-{模块名}模块详细设计说明书.md。
• 输入过程上下文：{AR编号}-{需求短名}-{模块名}模块详细设计说明书.context.md。
• 输出测试设计：{AR编号}-{需求短名}-{模块名}模块测试用例设计.md。
• 测试设计是独立成果物，供 Gate 统一审查；不得把测试用例写回 TOBE 正式说明书。
• .context.md 只用于读取 ASIS 测试覆盖、证据索引、TOBE 推导和历史门禁记录；测试设计正文必须自洽可读，不能要求后续执行者阅读 .context.md 才理解用例。
• 正式测试设计只输出验证结论，不输出目标抽取、风险分级、用例合并、候选用例淘汰等推导过程。需要过程审计时，由 Gate 在 .context.md 中反查和记录。

测试设计哲学

测试设计的目标不是生成测试用例大全，而是形成“最小充分验证集”：用尽量少但足够有代表性的测试，证明 TOBE 的关键设计可实现、可观察、可回归保护。

• 从设计风险出发，不从测试类型出发。先判断哪些 TOBE 设计点如果错了会导致需求不成立、契约漂移、数据不一致、回退失效或关键风险失控。
• 优先验证行为闭环，而不是覆盖表面字段。测试应证明输入进入模块后，关键决策、状态变化、副作用、异常收敛和可观察信号符合设计。
• 合并验证目标，不机械展开用例。允许一条高质量用例覆盖多个 TOBE 决策、契约、状态变化或观察点。
• 默认最小集，风险触发才扩展。每个需求点优先覆盖主路径、关键失败路径、关键边界/兼容路径；契约、数据、配置、观测、安全、性能、并发、迁移等只在 TOBE 触发时补充。
• 不能验证的设计就是设计缺口。若无法写出输入、前置条件、预期结果、断言或观察点，应输出测试缺口并回流 TOBE / ASIS / 上游确认，不得硬凑用例。

输入

可以接受：

• 正式 TOBE 说明书路径或内容。
• 同名前缀 .context.md 中的 ASIS 变更类型、ASIS 测试覆盖现状、证据索引、TOBE 追踪矩阵和历史门禁问题。
• 上游验收标准、用户补充的测试要求。
• 代码仓中现有测试目录、测试框架、Fixture、Mock、构建命令和测试命令。

内部工作法

以下步骤是 LLM 的内部工作法，用于生成高质量测试设计；不得把这些步骤、候选目标、评分过程或合并推导原样写入正式《模块测试用例设计.md》。

1. 定位输入与输出

• 定位正式说明书、同名前缀 .context.md 和目标测试设计文件。
• 读取 TOBE 中的需求/AR、设计决策、契约清单、接口/数据/流程/异常/配置/日志/风险和 可测试性与验收口径。
• 读取 ASIS 测试覆盖现状，识别可复用测试文件、测试框架、Fixture、Mock、历史回归测试和测试缺口。
• 读取 ASIS 变更类型；纯新增场景下，“新增对象当前不存在”不视为测试覆盖缺失，但必须参考相邻测试组织、Fixture/Mock 风格和模块惯例确定新增测试位置与断言方式。
• 如果正式说明书缺少支撑测试设计的关键行为、错误语义、状态变化、兼容策略、可观察信号或验收阈值，标记 回 TOBE 补设计，不得继续编造用例。

2. 黑盒形成最小充分验证集

内部完成以下判断，但正式成果物只输出结论：

• 抽取验证目标：行为、契约、状态/副作用、异常/回退、兼容/回归和触发风险。
• 判断目标优先级：P0 为不验证不能进入 AICoding；P1 为应自动化验证；P2 为可后续补充或人工验证；N/A 为被其他目标覆盖或不适用。
• 合成最小用例集：优先选择能覆盖多个 P0/P1 目标的单元测试、模块内功能集成测试、契约测试、兼容/回归测试、数据/配置/观测或风险专项验证。
• 记录覆盖解释：正式成果物中只写每条用例覆盖哪些目标、覆盖状态和缺口，不写内部排序和候选淘汰过程。

3. 设计测试用例

每条用例必须能独立指导后续测试实现，至少包含：

• 用例编号、关联需求/AR、关联 TOBE 决策或契约。
• 覆盖目标和优先级。
• 建议测试位置或套件；无法定位时写明原因和需要补充的代码信息。
• 前置数据、Fixture、Mock、依赖状态或环境条件。
• 输入或触发步骤。
• 预期结果、断言方式和可观察信号。
• 是否自动化；若只能人工验证，说明原因、观察步骤和通过标准。

不得只写“补充单测”“覆盖异常场景”“验证兼容性”等不可执行概要。

测试用例按测试层级分层组织（对应模板的 ### 2.x 顶层分组），本次设计能支撑的层级才建，不强求枚举：

• 单元测试：覆盖单个函数、类、方法、规则、转换、校验和边界分支。
• 模块内功能集成测试：覆盖同一代码模块或包内的业务流程，串联紧密相关类/服务/处理器/领域对象；模块外依赖使用 fake / mock / stub / in-memory 实现。
• 契约测试：覆盖 REST/RPC/MQ/内部接口、DTO、JSON 字段、错误码、Topic、Path 或方法签名。
• 兼容/回归测试：覆盖 ASIS 行为保持、旧接口、旧数据、旧配置和开关关闭行为。
• 数据/迁移测试：覆盖表结构、字段、索引、迁移、回填、默认值和回滚。
• 配置/开关测试：覆盖配置项、灰度、环境差异和回退行为。
• 观测性验证：覆盖日志、指标、告警和 trace 字段。
• 风险专项验证：覆盖安全、性能、并发、幂等、事务、重试、补偿等被 TOBE 触发的风险。
• 端到端 / 人工验证：当单元或模块内集成无法闭合业务闭环时，按需建立。

由于测试层级已体现在顶层分组标题，单条用例条目内不再重复“测试层级”字段；每条用例用列表平铺优先级、覆盖目标、场景、建议位置、自动化，以及四个行为字段「前置 / 输入 / 预期 / 断言」（两两对仗：前置—输入描述怎么跑，预期—断言描述怎么验）。

4. 输出结论型成果物

正式测试设计必须提供：

• 测试范围与策略摘要：说明采用最小充分验证集，优先覆盖 P0/P1 设计风险，允许一条用例覆盖多个设计目标。
• 最小充分测试用例集：以列表式分层呈现——顶层按测试层级分组（### 2.x，只建本次能支撑的层级）、层级下按功能点/场景分组（#### 2.x.y）、每个用例一个条目（##### TCn）用列表平铺字段。单条用例写清优先级、覆盖目标、场景、建议位置、自动化，以及前置 / 输入 / 预期 / 断言四个行为字段。用例集必须用列表式分层，不得用宽表平铺；测试层级不作为单条用例的字段，只作为顶层分组标题。
• 覆盖矩阵：TOBE 决策/契约/风险 -> 优先级 -> 覆盖用例 -> 覆盖状态 -> 未覆盖原因。
• 缺口与回流建议：只记录影响 Gate 判断的缺口和补齐条件。

如果某个关键 TOBE 决策、契约、失败路径或触发风险没有用例覆盖，必须写入测试缺口，并说明是回 TOBE 补设计、回 ASIS 补测试证据、还是测试设计继续补齐。

5. 更新测试设计成果物

加载 <skill-dir>/references/test-design-template.md 创建或更新测试设计文件。返工时只更新受影响章节，并保留变更记录。

阻塞规则

出现以下情况时标记测试设计阻塞或部分完成：

• 正式 TOBE 说明书不存在，或缺少关键需求点、契约、流程、异常边界、验收口径。
• TOBE 中存在影响测试设计的待确认项或阻塞项。
• ASIS 测试覆盖现状缺失，且无法判断现有测试框架、测试目录或复用方式；纯新增场景下，仅“新增对象没有既有测试”不构成阻塞。
• 关键风险没有 TOBE 缓解设计或可观察信号，导致无法设计有效验证。
• 用户或上游验收标准互相矛盾。

阻塞输出必须包含：阻塞原因、受影响的覆盖目标、需要回补的 TOBE/ASIS/上游输入、当前可继续设计的独立范围、不得定稿的测试用例、对 Gate 的影响。

质量标准

结束前确认：

• 未替 TOBE 补设计，所有覆盖目标都能反查正式说明书中的需求、契约、流程、异常、风险或可测试性输入。
• 输出的是最小充分验证集，不是测试类型枚举或测试用例大全；可合并目标已合并，P0/P1 优先于 P2。
• 主路径、关键失败路径、关键边界/兼容路径和触发风险均已覆盖，或明确说明不适用/阻塞原因。
• 每条用例都有输入、前置条件、预期结果、断言方式和建议位置。
• 纯新增场景下，已说明新增测试沿用的相邻测试组织、Fixture/Mock 风格或模块惯例。
• 测试设计不包含 AICoding 任务拆分。
• 测试缺口已显性化，并能指导回 TOBE、回 ASIS 或继续测试设计。

流程结束 / 工作流衔接

本 skill 产出独立《{AR编号}-{需求短名}-{模块名}模块测试用例设计.md》（含最小充分用例集、覆盖矩阵、缺口回流），交付给 $module-design-gate。Gate 读取测试设计的覆盖目标、用例、断言、覆盖矩阵和缺口做验证闭环性判断。

引用文件

• 测试设计模板：<skill-dir>/references/test-design-template.md

完成后回调

若不处于 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