pdlc-tdd

name	pdlc-tdd
description	TDD 测试先行（按设计文档生成失败的测试用例）
argument-hint	<功能ID | 功能描述>
allowed-tools	Read, Write, Edit, Glob, Grep, Bash
layer	2
stage	tdd
produces	["<测试代码 · 项目既有布局>","docs/04_testing/unit-tests/**"]
requires	["docs/02_design/"]
next_step	pdlc-implement
terminal_state	tdd_done
recommended_model	sonnet
recommended_effort	medium

TDD 测试先行

根据设计文档，先编写测试用例，再实现代码。严格遵循 TDD 工作流。

PDLC 前置检查（必须执行，不可跳过）

1. 从用户输入中提取功能名称关键词
2. 在 docs/02_design/ 的子目录（api/、architecture/、database/、ui-ux/）下搜索包含该关键词的设计文档
   • 匹配新格式：F<日期>-<编号>-*<关键词>*-<类型>.md
   • 匹配旧格式：YYYYMMDD-*<关键词>*-<类型>.md
   • 同时检查文件内容中是否包含该关键词
3. 未找到任何设计文档 → 输出以下信息后立即停止，不继续执行：

   ⛔ PDLC 守卫：未找到与「<功能名>」相关的设计文档（API/架构/数据库/UI 任一）。
   测试用例必须基于已有的设计文档。请先运行：
   👉 /pdlc-design <设计目标>
   

4. 找到 → 提取功能ID（如 F20260326-090000），读取设计文档内容，继续执行

工作流程

1. 阅读设计文档: 阅读找到的设计文档，全面理解接口/架构/数据模型
2. 阅读编码规范: 阅读 docs/00_standards/coding/ 目录了解编码规范（未命中 → 提示 consider /pdlc-standard add coding/<topic>）
3. 编写测试计划: 在 docs/04_testing/unit-tests/ 下创建测试计划文档
   • 使用模板: templates/test-plan-template.md
   • 文件名格式: <功能ID>-<功能名>-test-plan.md（如 F20260326-090000-user-auth-test-plan.md）
   • 文档顶部必须包含 PDLC 追溯头：

     <!-- PDLC-TRACE -->
     <!-- 功能ID: F20260326-090000 -->
     <!-- 功能名称: user-auth -->
     <!-- 阶段: 测试 -->
     <!-- 前置文档: docs/02_design/api/F20260326-090000-user-auth-api.md -->
     

4. 编写测试代码: 写到项目既有的测试布局里，按下面的规则定位； 不要为迎合某种预设结构新造一套平行的测试目录。

5. 测试计划自审与自动修复（编写完成后、运行前执行，不可跳过）：

   • 重新阅读测试计划和测试代码，对照设计文档和 PRD 逐项检查以下质量门禁：

   验收标准覆盖度：

   • PRD 中每条验收标准是否至少有一个对应的测试用例
   • 设计文档中每个接口是否至少有正常流程 + 异常流程的测试

   场景完备性：

   • 正常流程：核心业务路径是否全部覆盖
   • 边界条件：空值/null、空字符串、最大值/最小值、零值、超长输入
   • 异常场景：无权限、资源不存在（404）、重复操作（409）、参数校验失败（400）
   • 并发场景：是否考虑了同时操作的冲突（如适用）
   • 幂等性：重复提交同一请求是否有对应测试（如适用）

   测试质量：

   • 测试方法命名是否清晰描述场景（如 should_return_404_when_user_not_found）
   • 每个测试是否只验证一个行为（单一断言原则）
   • 测试数据是否有意义（非 test1、abc123 等无意义数据）

   自动修复：

   • 缺失的验收标准测试：自动补充对应的测试用例骨架
   • 缺失的边界条件测试：自动添加空值、超长输入、类型错误等测试
   • 缺失的异常场景测试：根据 API 错误码自动补充 401/403/404/409 等场景测试
   • 命名不规范的测试方法：自动重命名为描述性命名
   • 修复后在测试计划文档末尾追加审查记录：

     ## 自审记录
     - 审查时间：<ISO 8601>
     - 对照 PRD 验收标准：X 条，已覆盖：X 条
     - 对照 API 接口：X 个，已覆盖：X 个
     - 发现问题：X 项
     - 自动修复：X 项
     - 修复明细：
       - [已修复] <问题描述>
     

6. 确认测试失败: 运行测试确认全部失败（红灯）。运行命令取自 docs/00_standards/test-commands.yml 的 unit（不存在则回退项目约定）。收尾写 last_phase_result.checks = { "red_verified": true }（红灯已由真跑退出码验证，非模型自评）

7. 实现代码: 编写最少量的代码使测试通过

8. 重构: 在测试通过的前提下优化代码

要求

• 测试用例必须覆盖：正常流程、边界条件、异常场景
• 测试方法命名清晰描述测试场景
• 单元测试覆盖率：覆盖率达标线以项目配置为准：优先取 docs/00_standards/test-commands.yml 的 coverage 命令阈值参数（那才是强制点，退出码即判定），其次 quality-targets.yml；两者都没有时按 >= 80% 兜底。

目标功能: $ARGUMENTS