TDD in the AI Era: Codex Practical Manual

Behavior: 这一轮实现哪个行为
Test: 测试文件和测试名
Command: 跑了什么命令
RED: 失败原因是否符合预期
GREEN: 通过结果是什么
REFACTOR: 是否重构，为什么

RED: test1, test2, test3, test4, test5
GREEN: 一次写一个大实现

RED test1 -> GREEN impl1 -> REFACTOR
RED test2 -> GREEN impl2 -> REFACTOR
RED test3 -> GREEN impl3 -> REFACTOR

# TDD Rules

- For new behavior and bug fixes, use red/green TDD.
- RED: write exactly one failing behavior test first.
- Run the smallest relevant test command and confirm the failure is expected.
- Do not edit production implementation during RED.
- GREEN: write the minimum production code required to pass the current failing test.
- Never modify, delete, skip, or weaken tests to make implementation pass.
- REFACTOR only after tests are green.
- Keep structural changes and behavior changes separate.
- Report Behavior, Test, Command, RED, GREEN, and REFACTOR for each cycle.

# Verification

- Use `pytest` or the smallest relevant pytest command for Python behavior tests.
- Use `npm run types:check` only when this blog site's MDX or TypeScript changes.
- Use the smallest targeted command during RED/GREEN loops.
- If a command is slow, explain what targeted command was used first and what full command remains.

.agents/
  skills/
    tdd-codex/
      SKILL.md

---
name: tdd-codex
description: Implementing or fixing maintainable code with Codex using strict red-green-refactor TDD. Use for new behavior, bug reproduction, behavior tests, or safe AI coding.
---

# TDD Codex Workflow

Use one behavior slice per cycle.

## Phase 0: Scope

Identify one observable behavior.
Name the public API, user flow, or integration boundary under test.
Do not edit production code.

## Phase 1: RED

Write exactly one failing behavior test.
Prefer public behavior over implementation details.
Run the smallest relevant test command.
Confirm the failure is expected.
Stop and report:
- Behavior
- Test file
- Command
- Failure reason

## Phase 2: GREEN

Write the minimum production code to pass the current failing test.
Never modify, delete, skip, or weaken tests to pass.
Do not add speculative features or abstractions.
Run the same test command.
Report the passing result.

## Phase 3: REFACTOR

Only refactor after tests are green.
If the code is already simple, skip.
If refactoring, make one structural change at a time.
Run tests after each refactor.
Do not change behavior.

## Cycle Report

Return:
- Behavior:
- Test:
- Command:
- RED:
- GREEN:
- REFACTOR:
- Next slice:

用 tdd-codex skill 做这个需求。
每轮只处理一个行为。
先 RED，确认失败后停下来，不要直接写实现。

用 tdd-codex。先写红灯，等我说 go。

# .codex/agents/tdd-test-writer.toml
name = "tdd_test_writer"
description = "RED phase agent. Writes one failing behavior test and stops before implementation."
sandbox_mode = "workspace-write"

developer_instructions = """
You own only the RED phase.
Write exactly one behavior-focused test for the requested slice.
Prefer public APIs and user-visible behavior over implementation details.
Run the smallest relevant test command.
Confirm the test fails for the expected reason.
Do not edit production implementation.
Do not add multiple tests at once.
Return Behavior, Test, Command, and RED failure reason.
"""

# .codex/agents/tdd-implementer.toml
name = "tdd_implementer"
description = "GREEN phase agent. Implements the minimum production code to pass the current failing test."
sandbox_mode = "workspace-write"

developer_instructions = """
You own only the GREEN phase.
Read the failing test and relevant production code.
Write the minimum implementation required to pass the current test.
Never modify, delete, skip, or weaken tests to make them pass.
Do not add speculative features, helpers, configuration, or abstractions.
Run the relevant tests and return the command plus passing output.
"""

# .codex/agents/tdd-refactorer.toml
name = "tdd_refactorer"
description = "REFACTOR phase agent. Improves structure only after tests are green."
sandbox_mode = "workspace-write"

developer_instructions = """
You own only the REFACTOR phase.
Start by running the relevant tests to confirm the code is green.
Look for duplication, unclear names, needless branching, or misplaced responsibility.
Skip refactoring when the code is already simple.
If you refactor, make one structural change at a time.
Run tests after each refactor.
Never change behavior in this phase.
"""

按三阶段 TDD 做这个 slice：
1. tdd_test_writer 只写一个失败测试，并确认 RED。
2. 等我确认后，tdd_implementer 写最小实现，并确认 GREEN。
3. tdd_refactorer 判断是否需要结构重构。
不要批量铺测试。
不要在 GREEN 阶段修改测试。

# ~/.codex/config.toml 或 <repo>/.codex/config.toml
[features]
codex_hooks = true

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "apply_patch|Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$(git rev-parse --show-toplevel)/.codex/hooks/watch-test-edits.sh\"",
            "timeout": 10,
            "statusMessage": "Checking test file edits"
          }
        ]
      },
      {
        "matcher": "Bash|apply_patch|Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$(git rev-parse --show-toplevel)/.codex/hooks/run-fast-check.sh\"",
            "timeout": 120,
            "statusMessage": "Running fast checks"
          }
        ]
      }
    ]
  }
}

# .codex/hooks/watch-test-edits.sh
#!/usr/bin/env bash
set -euo pipefail

changed_tests="$(
  git diff --name-only |
    grep -E '(^|/)(__tests__|tests?)/|\.(test|spec)\.[cm]?[jt]sx?$|_test\.go$|test_.*\.py$' || true
)"

if [ -n "$changed_tests" ]; then
  cat <<EOF
{
  "continue": false,
  "stopReason": "Test files changed. Review before continuing.",
  "systemMessage": "检测到测试文件被修改：\n$changed_tests\n\n测试文件可以改，但必须说明为什么改。先停下来确认：这是补充规格，还是为了凑绿而改测试？"
}
EOF
fi

# .codex/hooks/run-fast-check.sh
#!/usr/bin/env bash
set -euo pipefail

root="$(git rev-parse --show-toplevel)"
cd "$root"

if [ -f pyproject.toml ] || [ -f pytest.ini ] || [ -d tests ]; then
  pytest
elif [ -f package.json ]; then
  if npm run | grep -q "types:check"; then
    npm run types:check
  elif npm run | grep -q "check"; then
    npm run check
  fi
elif [ -f go.mod ]; then
  go test ./...
fi

为什么要改测试？
这是新需求、新边界，还是旧测试写错？
生产实现有没有被同步验证？

AGENTS.md 写纪律
skill 固化流程
subagents 隔离角色
hooks 检查测试 diff
CI 做最后兜底

实现 slugify(text: string): string。
把英文标题转成 URL slug。

我想实现 slugify(text: string): string。
先不要写代码。
请先问我 5 个边界问题，覆盖大小写、空格、标点、unicode、空字符串。
然后把确认后的规格写成 SPEC.md。

# slugify SPEC

- "Hello World" -> "hello-world"
- trim leading/trailing spaces
- collapse repeated spaces into one hyphen
- remove punctuation
- normalize "Café" -> "cafe"
- empty input returns empty string

读取 SPEC.md。
只实现第一条行为："Hello World" -> "hello-world"。
先 RED：只写一个失败测试，运行它，确认失败。
不要写生产实现。

Behavior: basic title becomes lowercase hyphenated slug
Test: tests/test_slugify.py
Command: pytest tests/test_slugify.py -q
RED: failed because slugify is not defined

go

def slugify(text: str) -> str:
    return text.lower().replace(" ", "-")

GREEN: pytest tests/test_slugify.py -q passed
REFACTOR: skipped, implementation is still simple
Next slice: trim leading/trailing spaces

继续下一条：去掉首尾空格。
先 RED，只写一个测试。

def test_slugify_trims_spaces():
    assert slugify("  Hello World  ") == "hello-world"

def slugify(text: str) -> str:
    return text.strip().lower().replace(" ", "-")

用 TDD 实现这个需求。
每轮只处理一个行为。
先写一个失败测试并运行确认 RED。
不要写生产实现，直到我说 go。

先写一个能复现这个 bug 的失败测试。
确认它因为这个 bug 失败后，再写最小修复。
不要改测试来适配当前实现。

先不要写代码。
请给出 TDD 分解计划：
- 外圈集成测试是什么
- 内圈每个行为 slice 是什么
- 每轮用什么命令验证
- 哪些地方不能 mock
等我确认后再开始 RED。

Review 这次改动，重点看：
- 是否先有失败测试
- 测试是否测行为而不是实现
- 是否存在为了通过而弱化测试
- 结构改动和行为改动是否混在一起
- 是否缺少外圈集成测试