AGENT SKILL

module-test-design

把已定稿的设计目标、契约、流程、异常边界、风险和可测试性输入转化为可执行的最小充分验证集,输出独立测试用例设计文档。本 skill 只输出最小充分测试用例集、覆盖矩阵、断言、建议位置和缺口;不得替设计补内容,不得拆分 AICoding 任务。支持两种模式:严格模式(完整的 SR / AR 设计链路)基于模块目录下的正式《模块详细设计说明书.md》与 `.context/详细设计上下文.md`,生成同目录《模块测试用例设计.md》;轻量模式(个人开发者轻量链路)基于单份 `dev-design.md`,在设计文档旁生成 `test-design.md`,由调用方说明。

License 许可
MIT
最近更新
2026-11-15
Stars
★ 9
Forks
6

01 前言 Front Matter

name
module-test-design
version
2.3.2.4
description
把已定稿的设计目标、契约、流程、异常边界、风险和可测试性输入转化为可执行的最小充分验证集,输出独立测试用例设计文档。本 skill 只输出最小充分测试用例集、覆盖矩阵、断言、建议位置和缺口;不得替设计补内容,不得拆分 AICoding 任务。支持两种模式:严格模式(完整的 SR / AR 设计链路)基于模块目录下的正式《模块详细设计说明书.md》与 `.context/详细设计上下文.md`,生成同目录《模块测试用例设计.md》;轻量模式(个人开发者轻量链路)基于单份 `dev-design.md`,在设计文档旁生成 `test-design.md`,由调用方说明。

02 资源文件 3

03 SKILL.md 正文

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

SDD 模块测试用例设计

模式判定

本 skill 支持两种输入模式,由调用方的说明决定:

  • 严格模式(默认):完整的 SR / AR 设计链路。权威输入是《模块详细设计说明书》与 .context/详细设计上下文.md。按下方正文执行,输入缺失时按阻塞规则处理。
  • 轻量模式:个人开发者的轻量链路。调用方会说明本次为 module-test-design 的【轻量模式】。此时权威输入只有 dev-design.md,不存在三件套,也不要求它们。按「轻量模式分支」执行,不要因为缺三件套而中止或引导用户跑 module-tobe-design / module-design-gate。

判定方法:调用方说明本次为【轻量模式】,或用户明确只给了 dev-design.md 要求做测试设计时,进入轻量模式;否则一律按严格模式。

阶段规则

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

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

运行方式

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

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

成果物协作规则

文档位置以调用方指定的为准;没有指定时使用下面的默认布局。

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

测试设计哲学

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

  • 从设计风险出发,不从测试类型出发。先判断哪些 TOBE 设计点如果错了会导致需求不成立、契约漂移、数据不一致、回退失效或关键风险失控。
  • 优先验证行为闭环,而不是覆盖表面字段。测试应证明输入进入模块后,关键决策、状态变化、副作用、异常收敛和可观察信号符合设计。
  • 合并验证目标,不机械展开用例。共享前置、执行路径和观察面的等价输入优先合并为一条参数化/表驱动用例;允许一条高质量用例覆盖多个 TOBE 决策、契约、状态变化或观察点。
  • 默认最小集,风险触发才扩展。每个需求点优先覆盖主路径、关键失败路径、关键边界/兼容路径;契约、数据、配置、观测、安全、性能、并发、迁移等只在 TOBE 触发时补充。
  • 不能验证的设计就是设计缺口。若无法写出输入、前置条件、预期结果、断言或观察点,应输出测试缺口并回流 TOBE / ASIS / 上游确认,不得硬凑用例。
  • 本集合是下限,不是上限:设计期只能看到设计面,实现期才会暴露真正的测试面(生命周期、边界行为、配置归一化等)。实现阶段发现的补充验证面由 task-dev 在实现期补测,并在 tasks-overview 执行记录的「实现期补充与残余风险」小节登记,不要求回流本文件。

输入

可以接受:

  • 正式 TOBE 说明书路径或内容。
  • .context/详细设计上下文.md 中的 ASIS 变更类型、ASIS 测试覆盖现状、证据索引和 TOBE 追踪矩阵,以及 .context/模块设计门禁结果.md 中的历史门禁问题。
  • 上游验收标准、用户补充的测试要求。
  • 代码仓中现有测试目录、测试框架、Fixture、Mock、构建命令和测试命令。

轻量模式分支

仅当调用方声明【轻量模式】时适用。

输入

输入 默认路径 要求
轻量设计文档 .sdd/{SR}/dev-design.md 必需。方案与契约变更章节是被验证设计的事实来源;验收标准章节是需求侧验收口径
轻量门禁结果 .sdd/{SR}/.context/dev-design-gate.md 可选。存在时参考其历史问题
软件架构 .sdd/software_architecture.md 可选

启动后校验:dev-design.md 真实存在且可读;其方案与契约变更足以支撑测试设计,验收标准覆盖需求的全部目标。不要校验三件套文档,不要因其缺失而中止。

dev-design.md 缺失,或验收/契约不足以写出输入、预期结果、断言时,按"不能验证的设计就是设计缺口"输出缺口并回流 dev-design;不得硬凑用例,也不得替设计补充错误码、字段语义或兼容策略。

与严格模式的差异

严格模式 轻量模式
实现设计来源 《模块详细设计说明书》 dev-design.md 的方案与契约变更章节
验收口径来源 TOBE 可测试性与验收口径 dev-design.md 的验收标准章节(需求侧口径)
输出路径 .sdd/{SR}/{AR}/{模块组名}/模块测试用例设计.md .sdd/{SR}/test-design.md
模板 references/test-design-template.md references/test-design-lite-template.md
覆盖矩阵行 TOBE 决策/契约/风险 验收标准条目 + 契约变更项
「首次可验证阶段」列 无 预留:设计时空着,由 task-split 回填

轻量模式附加要求

  • 引用而不复述:用例通过 dev-design.md 的契约项名称、章节锚点或验收标准原文引用设计,不复述设计内容——两份文档各管一头,防止漂移。
  • 覆盖矩阵必须含「首次可验证阶段」列:设计阶段留空;只有端到端才能验证的条目在该列标"端到端(末阶段)"。task-split 拆分任务时回填阶段归属,并在 tasks-overview.md 为每个任务圈定负责的用例 ID。
  • 测试层级按项目实情裁剪:依据仓库现有测试组织确定可支撑的层级;没有测试框架时提供可执行的手动验证步骤并说明原因。
  • 交付对象为下游 dev-design-gate(验收闭环检查)与 dev-task-split(阶段回填与任务圈定)。

除输入来源、输出路径、模板和覆盖矩阵形态外,其余——测试设计哲学、内部工作法、阻塞规则、质量标准——全部沿用本 skill 正文。

内部工作法

以下步骤是 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、依赖状态或环境条件。
  • 输入或触发步骤。
  • 预期结果、断言对象和精确判定条件。写清比较对象、期望值或不变量,但使用语言无关的行为表达,不输出完整断言语句、循环、fixture 构造代码或 mock 实现。
  • 断言只验证权威契约定义的排序键、优先级和状态规则;不得为了让结果“更稳定”而把未定义的次级字段写成期望行为。
  • 是否自动化;若只能人工验证,说明原因、观察步骤和通过标准。

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

测试用例按测试层级分层组织(对应模板的 ### 3.x 顶层分组),本次设计能支撑的层级才建,不强求枚举:

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

由于测试层级已体现在顶层分组标题,单条用例条目内不再重复”测试层级”字段;每条用例用列表逐项列出优先级、覆盖目标、场景、建议位置、自动化,以及四个行为字段「前置 / 输入 / 预期 / 断言」。只有行为或隔离边界不同才拆成独立 TC;章节分组或测试层级不同本身不构成拆分理由,同一验证链在最合适的层级保留一次;同一规则的多组输入写入一个参数集合,不逐输入编号。

4. 输出结论型成果物

正式测试设计必须提供:

  • 测试范围与策略摘要:说明采用最小充分验证集,优先覆盖 P0/P1 设计风险,允许一条用例覆盖多个设计目标。
  • 最小充分测试用例集:用例正文采用列表式分层呈现——顶层按测试层级分组(### 3.x,只建本次能支撑的层级)、层级下按功能点/场景分组(#### 3.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。
  • 测试设计没有发明 TOBE 未定义的私有 helper、临时类型或文件拆分作为测试契约;内部实现可通过模块行为验证时,不为其单独建立契约用例。
  • 断言条件精确但保持语言无关,没有输出可直接粘贴的断言代码、循环、fixture 或 mock 实现。
  • 主路径、关键失败路径、关键边界/兼容路径和触发风险均已覆盖,或明确说明不适用/阻塞原因。
  • 生产者/消费者兼容用例使用真实生产输出,没有用近似 fixture 替代契约验证。
  • 每条用例都有输入、前置条件、预期结果、断言方式和建议位置。
  • 纯新增场景下,已说明新增测试沿用的相邻测试组织、Fixture/Mock 风格或模块惯例。
  • 测试设计不包含 AICoding 任务拆分。
  • 测试缺口已显性化,并能指导回 TOBE、回 ASIS 或继续测试设计。

流程结束 / 工作流衔接

本 skill 产出同一模块目录下的独立《模块测试用例设计.md》(含最小充分用例集、覆盖矩阵、缺口回流),交付给 $module-design-gate。Gate 读取测试设计的覆盖目标、用例、断言、覆盖矩阵和缺口做验证闭环性判断。

引用文件

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

04 同仓库更多 Skills

pi-ixel
pi-ixel/Awesome-Agent-Workflow

task-split

基于已确认的设计与测试规格,生成单文件薄任务计划 tasks-overview.md;任务只保留目标、范围、权威设计/测试引用、依赖和状态,不复制或改写设计正文。Use when the user asks for 任务拆分、开发任务规划、有序任务计划、task split,或希望把已评审设计组织为可串行调度的 T1/T2 任务。支持两种模式:严格模式以详细设计文档、测试用例设计文档和通过的模块设计门禁结果为输入;轻量模式以 dev-design.md 与 test-design.md 两份文档为输入,由调用方说明。

★ 9
pi-ixel
pi-ixel/Awesome-Agent-Workflow

task-dev

实现一个明确的 T[N] 任务并把它做完:按已评审设计实现与测试,两路只读语义 Review,修复与重验,代码检查,写交接记录与候选提交信息。Use when the user asks to 实现当前 Task、执行 task-dev、继续或恢复 T1/T2 开发。支持严格模式(以模块详细设计与测试用例设计为事实来源)与轻量模式(以 dev-design.md 与 test-design.md 为事实来源)。每次只处理一个 Task,不执行 git add 或 git commit,也不自行开始下一个 Task。

★ 9
pi-ixel
pi-ixel/Awesome-Agent-Workflow

sr-design

帮助开发者创建功能/模块设计文档。用户描述系统整体要做什么,你负责研究代码仓库, 确定如何调整内部结构来实现目标,并通过逐题澄清消除所有不确定细节。 文档聚焦软件架构、功能设计与模块设计,而非代码实现细节。

★ 9
pi-ixel
pi-ixel/Awesome-Agent-Workflow

sr-design-gate

对 SR-design.md 进行设计质量门禁,检查需求范围、架构边界、接口与数据契约、验收闭环、风险处置、图表变更表达以及文档跨章节一致性。用于 SR 设计完成后、进入 ar-split 前判断 SR 级设计是否完整,并输出通过、不通过或阻塞结论。

★ 9
pi-ixel
pi-ixel/Awesome-Agent-Workflow

repo-init

Use when the user asks for 软件实现设计/software_architect/初始化代码仓/sdd/初始化/init/更新代码仓软件架构/更新代码仓软件实现设计.

★ 9
pi-ixel
pi-ixel/Awesome-Agent-Workflow

module-tobe-design

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

★ 9