sc-tdd

测试驱动开发（TDD）技能

严格执行 Red-Green-Refactor 工作流，并通过自动化验证。

此技能充当 TDD 工作流状态机，通过验证器强制执行规范。它能防止常见的 TDD 反模式，并确保正确地先编写测试再开发。

快速开始

# Start TDD for a new feature
/sc:tdd "add user password validation"

# TDD with specific framework
/sc:tdd payment-module --framework pytest

# Fast mode (skip full suite after green, run at end)
/sc:tdd api-endpoint --fast

# Allow snapshot tests
/sc:tdd ui-component --allow-snapshots

行为流程

此技能强制执行 7 步 Red-Green-Refactor 循环：

1. 初始化 - 检测范围、框架并创建状态
2. RED：编写失败的测试 - 为缺失的功能编写测试
3. RED：验证失败 - 运行验证器，确认是语义失败（断言失败，而非编译错误）
4. GREEN：最小化实现 - 编写能通过测试的最精简代码
5. GREEN：验证通过 - 运行验证器，确认测试通过且没有回归
6. REFACTOR：改进设计 - 在测试的安全保障下清理代码
7. REFACTOR：验证稳定性 - 重新运行测试套件，确认仍然全部通过

状态机

IDLE → RED_PENDING → RED_CONFIRMED → GREEN_PENDING →
GREEN_CONFIRMED → REFACTOR_PENDING → REFACTOR_COMPLETE → [cycle repeats]

关键规则：

• 验证器输出是事实依据 - 如果验证器表示受阻，你必须停止
• 退出代码至关重要：0 = 允许，2 = 受阻，3 = 出错（向用户寻求帮助）
• 不得绕过 - 每次阶段转换都必须获得验证器批准

阶段 1：初始化（IDLE → RED_PENDING）

时机：用户请求使用 TDD 工作流

你的操作：

1. 检测范围根目录：

python .claude/skills/sc-tdd/scripts/framework_detector.py \
  --detect-scope $(pwd) \
  --json

2. 初始化状态：

python .claude/skills/sc-tdd/scripts/tdd_state_machine.py \
  --scope-root <detected_scope> \
  --init \
  --json

3. 转换到 RED_PENDING：

python .claude/skills/sc-tdd/scripts/tdd_state_machine.py \
  --scope-root <scope> \
  --phase RED_PENDING \
  --evidence "User requested: <feature_description>" \
  --json

输出：确认初始化，并向用户说明 RED 阶段规则

阶段 2：编写失败的测试（RED_PENDING）

规则：

• 用户先编写测试
• 你可以协助编写测试
• 你可以添加空桩/接口以使测试能够编译（例如，pass、raise NotImplementedError、空函数）
• 你此时不得编写生产实现代码

你的操作：

1. 协助用户编写测试文件
2. 说明测试必须因断言而失败（而非编译错误）
3. 编写完测试后，继续进行验证

阶段 3：验证 Red（RED_PENDING → RED_CONFIRMED）

重要：继续之前，你必须运行此验证器。

命令：

python .claude/skills/sc-tdd/scripts/validate_red.py \
  --scope-root <scope> \
  --json

解读：

• 退出代码为 0 且 "allowed": true → 继续转换到 RED_CONFIRMED
• 退出代码为 2 且 "allowed": false → 停止，向用户显示 reasons，并要求他们修复

常见阻止原因：

• "Test failed but NOT with semantic assertion" - 编译错误，需要修复测试
• "Test PASSED (expected failure)" - 测试实际上并未测试该功能
• "No changed test files found" - 忘记编写测试

如果受阻：向用户显示 reasons 数组、artifacts.test_output，并要求他们解决问题。在验证器允许之前，不要提出生产代码方案。

如果获准：保存 artifacts.intent_test 信息，转换状态并进入 GREEN 阶段。

阶段 4：最小化实现（RED_CONFIRMED → GREEN_PENDING）

规则：

• 编写能通过测试的最精简实现
• 专注于通过测试，而非追求完美
• 不要过早优化
• 不要添加测试要求之外的功能

你的操作：

1. 确认当前状态为 RED_CONFIRMED
2. 编写最小化的生产代码
3. 说明你的实现思路
4. 转换到 GREEN_PENDING：

python .claude/skills/sc-tdd/scripts/tdd_state_machine.py \
  --scope-root <scope> \
  --phase GREEN_PENDING \
  --evidence "Implemented: <description>" \
  --json

5. 继续进行验证

阶段 5：验证 Green（GREEN_PENDING → GREEN_CONFIRMED）

重要：在宣称成功之前，你必须运行此验证器。

命令（标准模式）：

python .claude/skills/sc-tdd/scripts/validate_green.py \
  --scope-root <scope> \
  --json

命令（快速模式，跳过完整测试套件）：

python .claude/skills/sc-tdd/scripts/validate_green.py \
  --scope-root <scope> \
  --skip-full-suite \
  --json

解读：

• 退出代码为 0 且 "allowed": true → 转换到 GREEN_CONFIRMED，并进入重构阶段
• 退出代码为 2 且 "allowed": false → 停止，实现不充分

常见阻止原因：

• "Intent test still FAILING" - 实现未能让测试通过
• "Full test suite FAILED - REGRESSION DETECTED" - 导致现有测试失败

如果受阻：向用户显示失败详情，修复实现并重新验证。

如果获准：太好了！测试已通过，且没有回归。询问用户是否要进行重构或完成本轮循环。

阶段 6：重构（可选，GREEN_CONFIRMED → REFACTOR_PENDING）

规则：

• 提高代码质量，但不改变行为
• 测试必须持续通过
• 允许的更改：提取方法、重命名变量、提高清晰度、消除重复
• 不允许：添加功能、更改测试预期、削弱测试

你的操作：

1. 询问用户是否要重构
2. 如果是，则转入 REFACTOR_PENDING
3. 提出重构方案
4. 应用更改
5. 重新运行测试以确认稳定性

阶段 7：验证重构（REFACTOR_PENDING → REFACTOR_COMPLETE）

命令：

python .claude/skills/sc-tdd/scripts/validate_green.py \
  --scope-root <scope> \
  --json

（同一验证器，确保测试仍然通过）

如果允许：周期完成！询问用户：

• 继续下一个测试？（开始新的 RED 周期）
• 功能已完成？

标志

标志	类型	默认值	描述
--framework	字符串	auto	测试框架：auto、pytest、jest、vitest、go、cargo
--fast	布尔值	false	在 GREEN 阶段跳过完整测试套件，仅在功能完成时运行
--allow-snapshots	布尔值	false	允许将快照测试视为语义失败
--strict	布尔值	false	RED 阶段不允许使用存根（必须纯粹采用测试优先）

已启用的角色

• agent-test-automator - 测试设计专业知识
• guardian - 测试质量验证
• agent-python-pro / agent-typescript-react-expert - 特定语言的实现
• architect - 架构指导

MCP 集成

• PAL MCP
  • mcp__pal__codereview - 审查测试质量和实现
  • mcp__pal__debug - 调查意外的测试失败

检测并阻止的反模式

验证器会阻止：

• 在失败测试之前编写生产代码
• 将编译错误计作“红”（必须是运行时断言）
• 测试本应失败时却通过
• 在 GREEN 阶段削弱断言
• 完整测试套件中的回归

验证器会警告：

• 快照测试（除非使用 --allow-snapshots，否则会被阻止）
• 不稳定模式：sleep、网络、未模拟的随机行为
• 没有断言的测试
• 总是通过的测试

工具协作

• Read - 读取现有测试文件、实现代码和框架配置
• Write - 创建新的测试文件和状态文件
• Edit - 逐步修改测试和实现
• Bash - 执行验证器脚本（不可妥协，始终运行验证器）
• Glob - 查找测试文件、清单文件和 CI 配置
• Grep - 搜索测试模式和框架用法

质量维度

评估维度：

• 正确性（30%）- 测试通过，且实现符合规格
• 完整性（20%）- 覆盖所有测试场景，并处理边缘情况
• 可测试性（20%）- 测试清晰、易维护、快速且确定
• 可维护性（15%）- 代码整洁、结构良好、没有重复
• 规范性（15%）- 遵循 TDD 流程，不走捷径，正确执行 Red-Green-Refactor

门槛：分数必须达到 70+ 才能标记为功能完成

示例

示例 1：功能开发

/sc:tdd "add password validation: minimum 8 characters"

# Workflow enforced:
# 1. Initialize state for current directory scope
# 2. User/Claude writes test_password_validation.py:
#    def test_password_min_length():
#        assert validate_password("short") == False
#        assert validate_password("longenough") == True
# 3. Run validate_red.py → confirms test FAILS with AssertionError (no validate_password function)
# 4. Claude implements:
#    def validate_password(password: str) -> bool:
#        return len(password) >= 8
# 5. Run validate_green.py → confirms test PASSES, full suite GREEN
# 6. Ask user about refactoring
# 7. Feature complete or next cycle

示例 2：使用 TDD 修复 Bug

/sc:tdd "fix: user deletion doesn't cascade to posts" --framework pytest

# Workflow:
# 1. Write test exposing bug (test fails showing cascade doesn't work)
# 2. Validate RED (confirms bug exists)
# 3. Fix cascade behavior
# 4. Validate GREEN (confirms bug fixed, no regressions)

示例 3：Monorepo 软件包

cd backend/user-service
/sc:tdd "add email validation"

# Auto-detects:
# - scope_root: backend/user-service (nearest package.json)
# - framework: jest (from package.json devDependencies)
# - Runs tests only in this package scope

故障排除

“未检测到测试框架”

解决方案：

1. 检查是否已安装测试框架
2. 手动指定：--framework pytest
3. 确保存在框架配置（pytest.ini、jest.config.js 等）

“测试失败，但不是由语义断言导致”

原因：编译错误、导入错误、语法错误

解决方案：

1. 修复测试，使其能够编译并运行
2. 如有需要，添加空存根：def my_function(): raise NotImplementedError
3. 重新运行 validate_red.py

“完整测试套件超时”

解决方案：

1. 使用 --fast 模式加快周期
2. 仅在功能完成时运行完整测试套件
3. 调查运行缓慢的测试

“多个测试文件发生更改”

原因：修改了多个测试文件（TDD 要求专注于单个测试）

解决方案：

1. 提交或暂存其他更改
2. 一次处理一个测试
3. 使用多个微周期

状态恢复

如果状态文件丢失或损坏：

1. 验证器会尝试根据 git diff + 当前测试结果进行恢复
2. 你可以手动重新初始化：python tdd_state_machine.py --init --scope-root <path>
3. 状态按作用域划分，因此多个软件包可以拥有独立的 TDD 状态

重要提醒

1. 阶段转换前务必运行验证器——这是不可妥协的要求
2. 以验证器的输出为准，而非主观假设——如果验证器表示已阻止，就停止
3. 退出代码很重要：同时检查退出代码和 JSON 中的 "allowed" 字段
4. 一次只编写一个测试——TDD 注重最小增量
5. 只接受语义层面的失败——编译错误不算真正的“红”
6. 完整测试套件很重要——除非明确使用 --fast 模式，否则不要跳过

---

版本：1.0.0 最后更新：2025-01-09 维护者：SuperClaude Framework