Back to Details

tdd

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

TDD Enforcement Skill

TDD强制执行技能

Priorities

优先级

Correctness > Test Coverage > Implementation Speed
正确性 > 测试覆盖率 > 实现速度

Goal

目标

Enforce Test-Driven Development as a process, not just a presence check. Agents left unconstrained write all tests first, then all code (horizontal slicing). This produces tests coupled to implementation that break on refactor. The 4-phase workflow below enforces vertical TDD cycles where each test drives one slice of implementation.
将测试驱动开发（TDD）作为一个流程来强制执行，而不仅仅是检查测试是否存在。不受约束的Agent会先编写所有测试，再编写所有代码（横向切片）。这会产生与实现细节耦合的测试，在重构时很容易失效。以下的四阶段工作流强制执行纵向TDD循环，即每个测试驱动一小部分实现。

Configuration

配置

Read 
tdd:
from CLAUDE.md:
yaml
tdd: strict  # strict | soft | off
Check both 
CLAUDE.md
and 
.claude/CLAUDE.md
. Default: 
off
.
从CLAUDE.md读取
tdd:
配置项：
yaml
tdd: strict  # strict | soft | off
同时检查
CLAUDE.md
和
.claude/CLAUDE.md
文件。默认值：
off
。

Modes

模式

Strict (
tdd: strict
)

严格模式 (
tdd: strict
)

Full 4-phase workflow with blocking gates. Planning phase requires user confirmation via AskUserQuestion before coding. Each phase has explicit entry/exit criteria.
Escape when: Markdown-only changes, config changes, or when mocking exceeds the change's complexity. Present AskUserQuestion with: (1) Write test first, (2) Prototype escape with justification. Log escapes.
完整的四阶段工作流，带有阻塞性检查点。规划阶段在编码前需要通过AskUserQuestion获取用户确认。每个阶段都有明确的进入/退出标准。
允许逃逸的场景：仅修改Markdown文件、修改配置项，或者当模拟逻辑的复杂度超过代码变更本身时。通过AskUserQuestion向用户提供两个选项：(1) 先编写测试；(2) 申请逃逸并说明理由。所有逃逸操作需记录日志。

Soft (
tdd: soft
)

宽松模式 (
tdd: soft
)

Full 4-phase workflow guidance but no blocking gates. Planning phase generates and presents the plan but proceeds immediately. Warns on deviations (no test, horizontal slicing) but does not stop. Summarize untested items after completion.
提供完整的四阶段工作流指导，但无阻塞性检查点。规划阶段会生成并展示计划，但会直接继续执行。当出现偏离TDD流程的情况（未编写测试、横向切片）时会发出警告，但不会终止执行。完成后会汇总未测试的内容。

Off (
tdd: off
)

关闭模式 (
tdd: off
)

No TDD checks. Standard implementation flow.
不进行任何TDD检查。使用标准的实现流程。

Anti-Pattern: Horizontal Slicing

反模式：横向切片

WRONG (horizontal):               RIGHT (vertical):
┌──────────────────────┐           ┌──────────────────────┐
│ Write ALL tests      │           │ Test 1 → Impl 1      │
│ test1, test2, test3  │           │ ✓ GREEN               │
├──────────────────────┤           ├──────────────────────┤
│ Write ALL code       │           │ Test 2 → Impl 2      │
│ impl1, impl2, impl3 │           │ ✓ GREEN               │
├──────────────────────┤           ├──────────────────────┤
│ Hope they match      │           │ Test 3 → Impl 3      │
│ ✗ Tests are brittle  │           │ ✓ GREEN               │
└──────────────────────┘           └──────────────────────┘
Horizontal slicing fails because tests written without implementation are based on imagined APIs. They couple to guessed method signatures, mock internal modules, and break on any structural change.
错误示范（横向切片）:               正确示范（纵向切片）:
┌──────────────────────┐           ┌──────────────────────┐
│ 编写所有测试         │           │ 测试1 → 实现1        │
│ test1, test2, test3  │           │ ✓ 测试通过           │
├──────────────────────┤           ├──────────────────────┤
│ 编写所有代码         │           │ 测试2 → 实现2        │
│ impl1, impl2, impl3 │           │ ✓ 测试通过           │
├──────────────────────┤           ├──────────────────────┤
│ 寄希望于测试匹配     │           │ 测试3 → 实现3        │
│ ✗ 测试脆弱易失效     │           │ ✓ 测试通过           │
└──────────────────────┘           └──────────────────────┘
横向切片的问题在于，在未编写实现的情况下编写的测试是基于想象的API。这类测试与猜测的方法签名耦合，需要模拟内部模块，并且在任何结构变更时都会失效。

4-Phase Workflow

四阶段工作流

Phase 1: Planning

阶段1：规划

Entry: Task received with TDD mode strict or soft.
  1. Identify the public interface changes needed
  2. List behaviors to test, ordered by priority (core path first, edge cases later)
  3. Strict mode: Present interface and behavior list via AskUserQuestion for user confirmation before proceeding
  4. Soft mode: Present the plan, proceed immediately
Load reference: 
Glob("**/tdd/references/interface-design.md", path: "~/.claude/plugins")
Exit: Confirmed behavior list. Proceed to Tracer Bullet.
Non-interactive: If no user response within the current turn, proceed with best judgment and log skipped confirmation.
进入条件：收到任务且TDD模式为严格或宽松。
  1. 确定所需的公共接口变更
  2. 列出需要测试的行为，按优先级排序（先核心路径，后边缘场景）
  3. 严格模式：通过AskUserQuestion向用户展示接口和行为列表，获取确认后再继续编码
  4. 宽松模式：展示计划后直接继续执行
加载参考文档：
Glob("**/tdd/references/interface-design.md", path: "~/.claude/plugins")
退出条件：行为列表已确认。进入追踪验证阶段。
无交互场景：如果当前轮次内未收到用户回复，则基于最佳判断继续执行，并记录跳过确认的操作。

Phase 2: Tracer Bullet

阶段2：追踪验证

Prove one end-to-end path using Red-Green-Refactor:
  1. Write ONE test for the highest-priority behavior
  2. Verify it FAILS (RED) — a passing test before implementation is a false positive
  3. Write minimal implementation to make it pass (GREEN)
  4. Run per-cycle checklist (below)
  5. Strict mode: Pause after tracer bullet passes. Present results via AskUserQuestion to confirm before incremental loop.
Load references: 
Glob("**/tdd/references/mocking.md", path: "~/.claude/plugins")
, 
Glob("**/tdd/references/test-quality.md", path: "~/.claude/plugins")
Exit: One test passing, end-to-end path proven.
通过红-绿-重构流程验证一条端到端路径：
  1. 为最高优先级的行为编写一个测试
  2. 验证测试失败（红态）——实现前测试通过属于假阳性
  3. 编写最小化的实现代码使测试通过（绿态）
  4. 执行每轮循环检查清单（见下文）
  5. 严格模式：追踪验证通过后暂停，通过AskUserQuestion向用户展示结果，获取确认后再进入增量循环阶段。
加载参考文档：
Glob("**/tdd/references/mocking.md", path: "~/.claude/plugins")
, 
Glob("**/tdd/references/test-quality.md", path: "~/.claude/plugins")
退出条件：一个测试通过，端到端路径已验证。

Phase 3: Incremental Loop

阶段3：增量循环

For each remaining behavior from the plan:
  1. Write ONE test (RED)
  2. Write minimal code to pass (GREEN)
  3. Run per-cycle checklist
  4. Repeat
Do NOT write the next test until the current cycle is GREEN and the checklist passes.
针对计划中剩余的每个行为：
  1. 编写一个测试（红态）
  2. 编写最小化的代码使测试通过（绿态）
  3. 执行每轮循环检查清单
  4. 重复上述步骤
在当前循环达到绿态且检查清单全部通过前，不得编写下一个测试。

Phase 4: Refactor

阶段4：重构

Only enter when ALL tests are GREEN.
  1. Look for refactoring candidates (duplication, long methods, shallow modules)
  2. Make ONE structural change at a time
  3. Run tests after each change — must stay GREEN
  4. If tests break, revert the refactor
Load reference: 
Glob("**/tdd/references/refactoring.md", path: "~/.claude/plugins")
Exit: Clean code, all tests GREEN. Commit test and implementation together.
仅当所有测试都处于绿态时才能进入此阶段。
  1. 寻找重构候选点（重复代码、过长方法、职责单一性不足的模块）
  2. 每次只做一项结构性变更
  3. 每次变更后运行测试——必须保持绿态
  4. 如果测试失败，回滚本次重构
加载参考文档：
Glob("**/tdd/references/refactoring.md", path: "~/.claude/plugins")
退出条件：代码整洁，所有测试保持绿态。将测试与实现代码一起提交。

Per-Cycle Checklist

每轮循环检查清单

After every RED-GREEN pair, verify:
  • Behavior, not implementation: Test describes WHAT the system does, not HOW
  • Public interface only: Test uses the same API as production callers
  • Survives refactor: Would this test break if internals changed but behavior stayed the same?
  • Minimal code: Implementation is the simplest thing that passes — no speculative features
  • No horizontal drift: Did you write only ONE test before implementing? If you wrote multiple, STOP and revert to one.
在每次红-绿循环后，验证以下内容：
  • 测试行为而非实现：测试描述系统做什么，而非怎么做
  • 仅针对公共接口：测试使用与生产环境调用者相同的API
  • 可承受重构：如果内部实现变更但行为保持不变，测试是否会失效？
  • 代码最小化：实现代码是满足测试要求的最简版本——无冗余特性
  • 无横向漂移：是否在实现前只编写了一个测试？如果编写了多个，立即停止并回滚到单个测试。

Pre-Existing RED State

初始失败状态

If existing tests are already failing when you start: note them and proceed with new behavior only. Do not attempt to fix pre-existing failures unless that is the task.
如果开始任务时已有测试处于失败状态：记录这些失败，仅针对新需求进行开发。除非任务明确要求，否则不要尝试修复已有的失败测试。

Test Discovery

测试文件发现

Search patterns: 
__tests__/[filename].test.ts
, 
[filename].test.ts
, 
[filename].spec.ts
, 
test/[filename].test.ts
, 
tests/[filename].test.ts
.
搜索模式：
__tests__/[filename].test.ts
, 
[filename].test.ts
, 
[filename].spec.ts
, 
test/[filename].test.ts
, 
tests/[filename].test.ts
。

Arguments

参数

$ARGUMENTS
$ARGUMENTS