用 CLI Agent 跑 TDD 工作流

用 CLI Agent 跑 TDD 工作流

基础概念

TDD（Test-Driven Development，测试驱动开发）的"红 - 绿 - 重构"循环已经存在二十多年，但 2025 年之前它在工业界一直推不动——写测试是体力活，先写测试再写实现感觉像在倒着走路。CLI Agent（Claude Code、Codex CLI 等）的出现把这件事彻底翻转了过来：测试是 Agent 写得最好的部分（结构化、有明确输入输出），实现也由 Agent 写，人只负责定义"我想要什么行为"以及最后的把关。

Anthropic 在官方《Claude Code Best Practices》里把这个判断写得非常直白：

Test-driven development is the single strongest pattern for working with agentic coding tools, as each red-to-green cycle gives Claude unambiguous feedback. （TDD 是和 Agent 协作的最强模式，因为每一轮"红到绿"都给模型提供了无歧义的反馈信号。）

为什么 CLI Agent 比 IDE 插件更适合跑 TDD？三个本质原因：

1. CLI Agent 能自己执行命令。它能跑 npm test、pytest、go test，把失败输出读回来当作下一轮的输入。IDE 插件大多只能"建议代码"，跑测试还得人手点按钮，循环就断了。
2. Hook 机制能强制每次 edit 后自动跑测试。PostToolUse 钩子在 Claude 写完文件那一刻就触发，Agent 没有"忘记跑测试"的可能——这件事在 IDE 里要靠纪律，在 CLI 里靠配置。
3. 失败的测试输出 = 下一轮 prompt。这是 CLI Agent TDD 最关键的一条：测试失败信息（断言、行号、stack trace）会自动进入 Agent 上下文，Agent 看到了就会自己修，不需要人复制粘贴。

核心要素

红 - 绿 - 重构 loop

注意图里有两个关键约束：测试 commit 后不再改，hook 在每次 edit 后强制跑测试。这两条共同保证了 Agent 不能用"改测试让它绿"这种偷懒手段——这是 Anthropic 文档反复强调的反模式。

基础用法

下面用 Claude Code 完整跑一次 TDD 循环：给一个简单功能"邮箱地址校验函数"，从写测试到通过，再到重构，全过程都由 Agent 完成。代码示例用 Python + pytest，但同一套模式在 JS / Go / Rust 上都通用。

第一步：在 CLAUDE.md 里写入 TDD 约定

把 TDD 的基线规则放进项目根目录的 CLAUDE.md，这样每次会话开始 Agent 都会读到：

# TDD 约定（强制）

- 当我说"做一个 X 功能"时，**先写测试**，让我看完测试再开始写实现。
- 测试遵循 AAA 模式（Arrange / Act / Assert），一个 it/test 一个断言。
- 测试名描述行为：`should_return_false_when_email_missing_at_sign`，不要叫 `test_1`。
- **不要为了让测试通过而修改测试本身**。如果你觉得测试错了，停下来问我。
- 实现遵循"刚刚够"原则：只写让当前红测试变绿所需的最少代码，不要预测未来需求。
- 重构阶段在所有测试绿之后才允许做，重构后必须重跑测试确认仍然绿。
- 优先跑单测，不跑全量测试套件（性能考虑）。

第二步：配置 PostToolUse 钩子自动跑测试

在 .claude/settings.json 里挂一个 PostToolUse hook，每次 Agent 写文件都自动跑测试，把结果回灌给 Agent：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "pytest -x --tb=short -q 2>&1 | tail -30",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

几个关键参数说明：

• matcher: "Edit|Write|MultiEdit"：只在写文件类工具调用后触发，避免读文件也跑测试。
• pytest -x：第一个失败就停，不等全跑完——给 Agent 的反馈延迟越短越好。
• --tb=short：精简 traceback，避免一次往 context 里灌几千 token。
• tail -30：截断长输出，绿的时候只回灌"X passed"，红的时候只回灌关键报错。
• timeout: 60：钩子超时上限，避免某次跑挂了卡死整个 session。

第三步：跑一遍完整循环

# 启动 Claude Code
claude

# 在对话里依次发出三条 prompt（每一条都是 TDD 一个阶段）

# 🔴 RED：让 Agent 写失败的测试
> 用 TDD 的方式给 src/email.py 加一个 validate_email(email: str) -> bool 函数。
> 这一步只写 tests/test_email.py，覆盖 5 个用例：
>   1. '[email protected]' -> True
>   2. 空字符串 -> False
>   3. 没有 @ 的字符串 -> False
>   4. @ 在开头 -> False
>   5. @ 后面没有点 -> False
> 不要写实现，运行 pytest 确认 5 个测试全失败（NameError）。

预期输出（Agent 的回复 + hook 自动跑测试的结果）：

✓ Wrote tests/test_email.py
[hook output]
ImportError while importing test module 'tests/test_email.py'.
ModuleNotFoundError: No module named 'src.email'
✓ 5 个测试全部失败（spec 已锁定，建议你 git commit 后再让我写实现）

继续：

# 🟢 GREEN：让 Agent 写最小实现
> git add tests/ && git commit -m 'red: validate_email spec'
> 现在写 src/email.py，最小实现让 5 个测试全过。不要改测试。

# ♻️ REFACTOR：让 Agent 重构
> 5 个测试都绿了。重构 src/email.py：把校验拆成 has_at / has_dot_after_at 两个内部函数；
> 测试必须保持绿，重构后 hook 会自动重跑确认。

整个过程中你写了 3 句 prompt，Agent 写了所有代码、跑了 N 次测试、看到失败自己改、重构后自己验证——这就是 CLI Agent TDD 比纯人工 TDD 快 3-5 倍的核心原因。

同类工具对比

把 TDD 在不同协作模式下放在一起对比，能看出 CLI Agent TDD 究竟新在哪里：

核心区别一句话：CLI Agent 把 TDD 从"靠纪律的工程实践"变成了"靠工具链强制执行的默认工作流"。Hook 让"忘记跑测试"在物理上不可能发生，prompt 里的"先写测试不要写实现"让 Agent 没机会跳步——纪律外包给了配置。

常见误区

优劣势分析

思考题

参考资料

1. Claude Code 官方 Best Practices（含 TDD 推荐）：https://code.claude.com/docs/en/best-practices（查询日期 2026-04-22）
2. Anthropic 早期博客《Claude Code: Best Practices for Agentic Coding》：https://www.anthropic.com/engineering/claude-code-best-practices（查询日期 2026-04-22）
3. The New Stack《Claude Code and the Art of Test-Driven Development》：https://thenewstack.io/claude-code-and-the-art-of-test-driven-development/（查询日期 2026-04-22）
4. Steve Kinney《Test-Driven Development with Claude Code》课程：https://stevekinney.com/courses/ai-development/test-driven-development-with-claude（查询日期 2026-04-22）
5. Alex Op 博客《Forcing Claude Code to TDD: An Agentic Red-Green-Refactor Loop》：https://alexop.dev/posts/custom-tdd-workflow-claude-code-vue/（查询日期 2026-04-22）
6. CircleCI 博客《What are test hooks in AI-native development?》：https://circleci.com/blog/test-hooks-ai-development/（查询日期 2026-04-22）
7. Tweag《Agentic Coding Handbook · Test-Driven Development》：https://tweag.github.io/agentic-coding-handbook/WORKFLOW_TDD/（查询日期 2026-04-22）
8. Latent Space《AI Agents, meet Test Driven Development》：https://www.latent.space/p/anita-tdd（查询日期 2026-04-22）
9. Builder.io《Test-Driven Development with AI》：https://www.builder.io/blog/test-driven-development-ai（查询日期 2026-04-22）
10. FlorianBruniaux《Claude Code Ultimate Guide · TDD with Claude》：https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/tdd-with-claude.md（查询日期 2026-04-22）