Claude Code 测试驱动开发全实战：从 Red-Green-Refactor 到自动化质量守门

用户：帮我写一个用户注册功能

Claude Code（默认行为）：
  ✅ 立即创建 UserService.java
  ✅ 立即实现 register() 方法
  ✅ 顺手写个 Controller
  ❌ 没有先写测试
  ❌ 边界条件未覆盖
  ❌ 错误路径未验证

graph TB
    subgraph "三层TDD防线"
        A["第一层：CLAUDE.md<br/>测试规则与质量标准"]
        B["第二层：Custom TDD Skill<br/>强制 Red-Green-Refactor 流程"]
        C["第三层：Hooks<br/>自动运行测试守门"]
    end
    A --> B --> C
    C -->|"测试失败则阻断"| D["阻止低质量代码合入"]
    style A fill:#f9f,stroke:#333
    style B fill:#bbf,stroke:#333
    style C fill:#bfb,stroke:#333
    style D fill:#fbb,stroke:#333

# 安装 Claude Code（如果尚未安装）
npm install -g @anthropic-ai/claude-code

# 验证版本
claude --version
# 期望输出：2.1.x 或更高

# 进入你的项目目录
mkdir tdd-demo && cd tdd-demo
git init

# 初始化 Claude Code 项目配置
claude /init

# Testing Standards

## TDD Discipline (MANDATORY)
- ALWAYS write tests BEFORE implementation code
- Follow strict Red-Green-Refactor cycle:
  1. RED: Write a failing test that defines expected behavior
  2. GREEN: Write the MINIMUM code to make the test pass
  3. REFACTOR: Improve code while keeping all tests green
- NEVER skip the RED phase — tests must fail first to prove they test something

## Test Quality Rules
- Test behavior, NOT implementation details
- Use descriptive test names: `should [expected behavior] when [condition]`
- Each test must have exactly ONE assertion focus
- Cover: happy path, edge cases, error paths
- Minimum coverage target: 80% for new code
- NEVER mock what you don't own — wrap external dependencies behind interfaces

## Test Commands
- Run all tests: `npx vitest run`
- Run single file: `npx vitest run path/to/test.ts`
- Watch mode: `npx vitest`
- Coverage: `npx vitest run --coverage`

## File Naming Conventions
- Test files: `*.test.ts` or `*.spec.ts`
- Test directory mirrors source: `src/auth/login.ts` → `src/auth/login.test.ts`
- Test utilities: `test/helpers/` or `test/fixtures/`

## Forbidden Patterns
- ❌ DO NOT write `expect(true).toBe(true)` placeholder tests
- ❌ DO NOT test private methods directly
- ❌ DO NOT use `any` types in test code
- ❌ DO NOT skip failing tests with `.skip()` without a linked issue

claude "帮我创建一个计算器模块，支持加减乘除"

---
name: tdd
description: >
  Enforce strict Test-Driven Development. Use when implementing new features,
  fixing bugs, or refactoring code. Orchestrates the Red-Green-Refactor cycle
  through subagents, ensuring tests are written and verified BEFORE implementation.
---

You are a TDD discipline enforcer. When the user asks you to implement or modify
any functionality, you MUST follow this exact sequence:

## Phase 1: RED (Write Failing Test)

1. Analyze the user's requirement and identify the expected behavior
2. Create a test file following project conventions (*.test.ts)
3. Write test cases that cover:
   - Happy path (normal input → expected output)
   - Edge cases (boundary values, empty input, null/undefined)
   - Error paths (invalid input → expected error)
4. Run the test command: `npx vitest run <test-file>`
5. VERIFY the test FAILS — if it passes, the test is wrong
6. Report: "🔴 RED: <number> tests failing as expected"

## Phase 2: GREEN (Minimum Implementation)

1. Write the MINIMUM code required to make failing tests pass
2. Do NOT add extra features, optimizations, or "nice-to-haves"
3. Run the test command again: `npx vitest run <test-file>`
4. VERIFY ALL tests pass — if any still fail, fix implementation
5. Report: "🟢 GREEN: All tests passing"

## Phase 3: REFACTOR (Improve Code Quality)

1. Review the implementation for:
   - Code duplication
   - Poor naming
   - Violations of SOLID principles
   - Performance bottlenecks
2. Make improvements while keeping tests green
3. Run tests after EACH refactor step
4. Report: "♻️ REFACTOR: <list of improvements made>"

## Rules
- NEVER skip Phase 1 (RED)
- NEVER implement more than what tests require in Phase 2 (GREEN)
- NEVER break tests during Phase 3 (REFACTOR)
- If user asks to skip tests, respond: "TDD is mandatory in this project. I'll proceed with the full Red-Green-Refactor cycle."

sequenceDiagram
    participant U as 用户
    participant CC as Claude Code
    participant T as 测试框架(Vitest)
    participant S as 源代码

    U->>CC: /tdd 实现 XXX 功能

    rect rgb(255, 200, 200)
        Note over CC,T: Phase 1: RED
        CC->>T: 编写测试用例
        CC->>T: 运行 npx vitest run
        T-->>CC: ❌ 测试失败(预期)
        CC->>U: 🔴 RED: 3 tests failing
    end

    rect rgb(200, 255, 200)
        Note over CC,S: Phase 2: GREEN
        CC->>S: 编写最小实现
        CC->>T: 运行 npx vitest run
        T-->>CC: ✅ 测试全部通过
        CC->>U: 🟢 GREEN: All tests passing
    end

    rect rgb(200, 220, 255)
        Note over CC,S: Phase 3: REFACTOR
        CC->>S: 重构改进代码
        CC->>T: 每次重构后运行测试
        T-->>CC: ✅ 测试仍然通过
        CC->>U: ♻️ REFACTOR: 提取公共方法+优化命名
    end

# 方式一：直接调用
claude "/tdd 实现一个用户认证模块，支持邮箱密码注册和登录"

# 方式二：在对话中触发
claude
> 用TDD方式帮我实现购物车的计算总价功能
# Claude Code 会自动检测到 "实现" 关键词，按照 TDD 流程执行

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "cd \"$PROJECT_DIR\" && npx vitest run --reporter=verbose 2>&1 | tail -20"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "sh -c 'FILE=\"$CLAUDE_FILE_PATH\"; if echo \"$FILE\" | grep -qv \"\\.test\\.\"; then echo \"⚠️ Source file modified — ensure corresponding tests exist\"; fi'"
          }
        ]
      }
    ]
  }
}

flowchart LR
    A["Claude Code<br/>修改文件"] --> B{"PreToolUse Hook<br/>源文件变更?"}
    B -->|"是"| C["提示: 确认测试存在"]
    B -->|"否(测试文件)"| D["正常执行"]
    C --> D
    D --> E["文件写入完成"]
    E --> F["PostToolUse Hook<br/>自动运行测试"]
    F --> G{"测试通过?"}
    G -->|"✅ 通过"| H["继续下一个任务"]
    G -->|"❌ 失败"| I["输出失败详情<br/>Claude Code 自动修复"]
    I --> A

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "sh -c 'FILE=\"$CLAUDE_FILE_PATH\"; if echo \"$FILE\" | grep -q \"\\.test\\.\\|\\.spec\\.\"; then echo \"🧪 Test file modified, running related tests...\"; npx vitest run \"$FILE\" 2>&1 | tail -15; else SRC=\"${FILE%.ts}.test.ts\"; if [ -f \"$SRC\" ]; then echo \"📦 Source modified, running its tests...\"; npx vitest run \"$SRC\" 2>&1 | tail -15; fi; fi'"
          }
        ]
      }
    ]
  }
}

mkdir task-manager-api && cd task-manager-api
git init
npm init -y
npm install express zod uuid
npm install -D vitest typescript @types/express @types/uuid tsx

# 创建 Claude Code 配置
claude /init

# Project: Task Manager API

## Architecture
- Language: TypeScript
- Framework: Express.js
- Validation: Zod schemas
- Testing: Vitest
- Source structure:
  ```
  src/
    models/       # Data models and types
    services/     # Business logic
    routes/       # Express route handlers
    validators/   # Zod schemas
    errors/       # Custom error classes
  ```

## Test Strategy
- Unit tests: services, validators, models
- Integration tests: routes (using supertest-like approach)
- Each service method gets its own describe block
- Use dependency injection for testability

claude "/tdd 实现创建任务功能：POST /api/tasks，接受 title(必填)、description(可选)、priority(low/medium/high, 默认medium)、dueDate(可选ISO日期)，返回创建的task对象"

import { describe, it, expect, beforeEach } from 'vitest';
import { TaskService } from './task.service';
import { TaskRepository } from '../repositories/task.repository';

describe('TaskService - createTask', () => {
  let taskService: TaskService;
  let mockRepository: TaskRepository;

  beforeEach(() => {
    mockRepository = {
      save: vi.fn(),
      findById: vi.fn(),
      findAll: vi.fn(),
      delete: vi.fn(),
    } as unknown as TaskRepository;
    taskService = new TaskService(mockRepository);
  });

  it('should create a task with required fields only', async () => {
    const input = { title: 'Buy groceries' };
    mockRepository.save = vi.fn().mockResolvedValue({
      id: 'task-1',
      title: 'Buy groceries',
      description: null,
      priority: 'medium',
      status: 'todo',
      dueDate: null,
      createdAt: new Date(),
    });

    const result = await taskService.createTask(input);

    expect(result.title).toBe('Buy groceries');
    expect(result.priority).toBe('medium');
    expect(result.status).toBe('todo');
    expect(mockRepository.save).toHaveBeenCalledOnce();
  });

  it('should create a task with all fields', async () => {
    const input = {
      title: 'Write report',
      description: 'Q4 financial report',
      priority: 'high' as const,
      dueDate: '2026-07-15',
    };
    mockRepository.save = vi.fn().mockResolvedValue({
      id: 'task-2',
      ...input,
      status: 'todo',
      createdAt: new Date(),
    });

    const result = await taskService.createTask(input);

    expect(result.title).toBe('Write report');
    expect(result.priority).toBe('high');
    expect(result.dueDate).toBe('2026-07-15');
  });

  it('should reject empty title', async () => {
    const input = { title: '' };

    await expect(taskService.createTask(input)).rejects.toThrow(
      'Title is required'
    );
  });

  it('should reject invalid priority value', async () => {
    const input = { title: 'Test', priority: 'urgent' };

    await expect(taskService.createTask(input)).rejects.toThrow();
  });

  it('should reject past due dates', async () => {
    const input = { title: 'Test', dueDate: '2020-01-01' };

    await expect(taskService.createTask(input)).rejects.toThrow(
      'Due date must be in the future'
    );
  });
});

npx vitest run src/services/task.service.test.ts

❯ npx vitest run src/services/task.service.test.ts

 FAIL  src/services/task.service.test.ts
  TaskService - createTask
    ✗ should create a task with required fields only
    ✗ should create a task with all fields
    ✗ should reject empty title
    ✗ should reject invalid priority value
    ✗ should reject past due dates

🔴 RED: 5 tests failing as expected (module not found)

export type Priority = 'low' | 'medium' | 'high';
export type Status = 'todo' | 'in_progress' | 'done';

export interface Task {
  id: string;
  title: string;
  description: string | null;
  priority: Priority;
  status: Status;
  dueDate: string | null;
  createdAt: Date;
}

export interface CreateTaskInput {
  title: string;
  description?: string;
  priority?: Priority;
  dueDate?: string;
}

import { Task } from '../models/task.types';

export interface TaskRepository {
  save(task: Omit<Task, 'id' | 'createdAt'>): Promise<Task>;
  findById(id: string): Promise<Task | null>;
  findAll(filter?: Record<string, unknown>): Promise<Task[]>;
  delete(id: string): Promise<boolean>;
}

import { v4 as uuidv4 } from 'uuid';
import { TaskRepository } from '../repositories/task.repository';
import { CreateTaskInput, Priority, Task } from '../models/task.types';

export class TaskService {
  constructor(private repo: TaskRepository) {}

  async createTask(input: CreateTaskInput): Promise<Task> {
    // Validate title
    if (!input.title || input.title.trim() === '') {
      throw new Error('Title is required');
    }

    // Validate priority
    const validPriorities: Priority[] = ['low', 'medium', 'high'];
    const priority = input.priority ?? 'medium';
    if (!validPriorities.includes(priority)) {
      throw new Error(`Invalid priority: ${input.priority}`);
    }

    // Validate due date
    if (input.dueDate) {
      const dueDate = new Date(input.dueDate);
      if (dueDate <= new Date()) {
        throw new Error('Due date must be in the future');
      }
    }

    const task: Task = {
      id: uuidv4(),
      title: input.title,
      description: input.description ?? null,
      priority,
      status: 'todo',
      dueDate: input.dueDate ?? null,
      createdAt: new Date(),
    };

    return this.repo.save(task);
  }
}

✅ GREEN: All 5 tests passing

// 重构：提取验证逻辑到独立模块
// src/validators/task.validator.ts
import { Priority } from '../models/task.types';

const VALID_PRIORITIES: Priority[] = ['low', 'medium', 'high'];

export function validateTitle(title: string): void {
  if (!title || title.trim() === '') {
    throw new Error('Title is required');
  }
}

export function validatePriority(priority: string): Priority {
  if (!VALID_PRIORITIES.includes(priority as Priority)) {
    throw new Error(`Invalid priority: ${priority}`);
  }
  return priority as Priority;
}

export function validateDueDate(dateStr: string): void {
  const dueDate = new Date(dateStr);
  if (dueDate <= new Date()) {
    throw new Error('Due date must be in the future');
  }
}

export class TaskService {
  constructor(private repo: TaskRepository) {}

  async createTask(input: CreateTaskInput): Promise<Task> {
    validateTitle(input.title);
    const priority = input.priority
      ? validatePriority(input.priority)
      : 'medium';
    if (input.dueDate) validateDueDate(input.dueDate);

    const task: Task = {
      id: uuidv4(),
      title: input.title,
      description: input.description ?? null,
      priority,
      status: 'todo',
      dueDate: input.dueDate ?? null,
      createdAt: new Date(),
    };

    return this.repo.save(task);
  }
}

# 查询功能
claude "/tdd 实现查询任务列表：GET /api/tasks，支持 status 过滤和 page/limit 分页"

# 状态更新
claude "/tdd 实现任务状态流转：PATCH /api/tasks/:id/status，只允许 todo→in_progress→done 的正向流转"

# 删除功能
claude "/tdd 实现删除任务：DELETE /api/tasks/:id，返回204，任务不存在返回404"

# 过期检测
claude "/tdd 实现过期自动标记：系统检查到期日已过的任务，将其标记为expired状态"

task-manager-api/
├── CLAUDE.md                    # TDD规则 + 项目约定
├── .claude/
│   ├── settings.json            # Hooks配置
│   └── skills/
│       └── tdd.md               # 自定义TDD Skill
├── src/
│   ├── models/
│   │   ├── task.types.ts
│   │   └── task.types.test.ts
│   ├── services/
│   │   ├── task.service.ts
│   │   └── task.service.test.ts
│   ├── validators/
│   │   ├── task.validator.ts
│   │   └── task.validator.test.ts
│   ├── routes/
│   │   ├── task.routes.ts
│   │   └── task.routes.test.ts
│   └── errors/
│       └── app-error.ts
├── package.json
├── vitest.config.ts
└── tsconfig.json

<!-- .claude/skills/tdd-feature.md -->
---
name: tdd-feature
description: Start TDD for a new feature with structured requirements
---

Implement the following feature using strict TDD:

## Feature: {{FEATURE_NAME}}

### Acceptance Criteria:
{{ACCEPTANCE_CRITERIA}}

### Test Cases to Cover:
1. Happy path: {{HAPPY_PATH}}
2. Edge cases: {{EDGE_CASES}}
3. Error paths: {{ERROR_PATHS}}

### Technical Notes:
- Follow existing patterns in the codebase
- Run `npx vitest run` after each phase
- Use dependency injection for testability

claude "/tdd-feature FEATURE_NAME='用户密码重置' ACCEPTANCE_CRITERIA='输入邮箱发送重置链接，链接24小时有效' HAPPY_PATH='已注册邮箱收到重置邮件' EDGE_CASES='未注册邮箱返回相同响应防止枚举' ERROR_PATHS='无效邮箱格式, 请求频率超限'"

# /review：对当前 git diff 做代码审查
claude "/review"

# /verify：运行应用并实际验证功能是否正常
claude "/verify"

# 组合使用：TDD 完成一个功能后
claude "我刚用TDD完成了密码重置功能，请先 /review 我的代码变更，然后 /verify 确认功能正常"

# 先检查当前覆盖率
claude "运行 npx vitest run --coverage 并分析覆盖率报告，找出覆盖率低于80%的模块"

# 针对性补充测试
claude "/tdd 为覆盖率不足的模块补充测试，优先覆盖未测试的分支"

claude "/tdd 修复以下bug：当用户创建任务时不填priority字段，返回500错误而不是使用默认值medium。

复现步骤：
1. POST /api/tasks body: {title: 'test'}
2. 期望返回 priority: 'medium'
3. 实际返回 500 Internal Server Error

先写一个能复现该bug的测试（RED），然后修复代码（GREEN），最后确认没有引入回归（REFACTOR）。"

# 使用 TaskCreate 创建任务列表
claude "分析以下需求文档(requirements.md)，用 /tdd 逐个实现每个功能点，每完成一个就运行测试确认，然后标记完成并继续下一个"

flowchart TD
    A["需求文档"] --> B["Claude Code 拆分功能点"]
    B --> C["功能1: TDD循环"]
    C --> D["功能2: TDD循环"]
    D --> E["功能3: TDD循环"]
    E --> F["功能N: TDD循环"]
    F --> G["全量测试"]
    G --> H{"覆盖率 ≥ 80%?"}
    H -->|"是"| I["✅ 完成"]
    H -->|"否"| J["补充测试"]
    J --> G

    subgraph "每个TDD循环"
        C1["🔴 RED"] --> C2["🟢 GREEN"] --> C3["♻️ REFACTOR"]
    end

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [{
          "type": "command",
          "command": "sh -c 'FILE=\"$CLAUDE_FILE_PATH\"; if echo \"$FILE\" | grep -qv \"\\.test\\.\\|\\.spec\\.\\|CLAUDE\\|settings\"; then TESTFILE=$(echo \"$FILE\" | sed \"s/\\.ts$/.test.ts/\"); if [ ! -f \"$TESTFILE\" ]; then echo \"⛔ BLOCKED: No test file found for $FILE. Create $TESTFILE first.\"; exit 1; fi; fi'"
        }]
      }
    ]
  }
}

## Test Quality Checklist (Claude MUST verify before submitting)
- [ ] Test name describes expected behavior, not implementation
- [ ] Arrange-Act-Assert pattern is clear
- [ ] No hardcoded dates or IDs — use factories/fixtures
- [ ] Mocks only for external dependencies, not for domain logic
- [ ] Edge cases covered: empty input, null, undefined, boundary values
- [ ] Error messages are asserted, not just error types

## TDD Enforcement Levels
- **Level 3 (Strict)**: Business logic, payment, auth, data transformation → Full Red-Green-Refactor
- **Level 2 (Standard)**: API routes, middleware, data access → Test + Implement together
- **Level 1 (Light)**: Config files, types, constants → No test required

# 第一步：只为新增代码强制 TDD
claude "分析当前代码库中哪些模块有测试、哪些没有。为新功能开发制定 TDD 规则，存量代码暂不要求。"

# 第二步：逐步为高风险模块补测试
claude "/tdd 为 src/services/payment.service.ts 补充测试，它处理支付逻辑但目前0测试覆盖"

# 第三步：设置覆盖率基线，只升不降
# 在 vitest.config.ts 中配置：
# coverage: { thresholds: { lines: 60, branches: 50, functions: 60 } }

graph TB
    subgraph "用户输入"
        REQ["功能需求 / Bug描述"]
    end

    subgraph "Claude Code TDD 引擎"
        SKILL["/tdd Skill<br/>流程编排"]
        RED["🔴 RED Phase<br/>生成测试代码"]
        GREEN["🟢 GREEN Phase<br/>最小实现"]
        REFACTOR["♻️ REFACTOR Phase<br/>代码改进"]
    end

    subgraph "三层防线"
        CMD["CLAUDE.md<br/>测试规则"]
        HOOK["Hooks<br/>自动守门"]
        REVIEW["/review + /verify<br/>质量审查"]
    end

    subgraph "测试基础设施"
        VITEST["Vitest<br/>测试运行器"]
        COV["Coverage<br/>覆盖率报告"]
        CI["CI Pipeline<br/>持续集成"]
    end

    REQ --> SKILL
    CMD --> SKILL
    SKILL --> RED
    RED -->|"测试失败"| GREEN
    GREEN -->|"测试通过"| REFACTOR
    REFACTOR -->|"测试仍通过"| REVIEW
    HOOK -->|"每次文件变更触发"| VITEST
    REVIEW --> VITEST
    VITEST --> COV
    COV --> CI

    style RED fill:#ffcccc,stroke:#cc0000
    style GREEN fill:#ccffcc,stroke:#00cc00
    style REFACTOR fill:#ccccff,stroke:#0000cc
    style CMD fill:#fff3cd,stroke:#856404
    style HOOK fill:#d4edda,stroke:#155724
    style REVIEW fill:#cce5ff,stroke:#004085

# CLAUDE.md testing section (Python version)
## Test Commands
- Run all: `pytest`
- Run single: `pytest tests/test_feature.py -v`
- Coverage: `pytest --cov=src --cov-report=term-missing`

## Conventions
- Test files: `tests/test_*.py`
- Fixtures in `tests/conftest.py`
- Use `pytest.raises` for exception testing
- Factory pattern with `factory_boy` for test data

# CLAUDE.md testing section (Go version)
## Test Commands
- Run all: `go test ./...`
- Run single: `go test ./pkg/service -v`
- Coverage: `go test -cover ./...`
- Race detection: `go test -race ./...`

## Conventions
- Test files: `*_test.go` in same package
- Table-driven tests using `t.Run`
- Use `testify/assert` for readable assertions
- Interfaces for dependency injection