tdd-workflow

TDD Workflow

Purpose

Guide feature implementation through strict red-green-refactor cycles, writing a failing test first, making it pass with minimal code, then refactoring.

Instructions

When the user describes a feature or behavior to implement, follow the TDD cycle below. Repeat the cycle for each discrete behavior until the feature is complete.

Step 0: Detect the Testing Framework

Before starting, identify the project's test setup:

1. Look at existing test files using Glob to find patterns like **/*.test.*, **/*.spec.*, **/test_*.py
2. Check for config files: jest.config.*, vitest.config.*, pytest.ini, playwright.config.*
3. Read one existing test file to match the project's style (imports, assertion patterns, describe/it structure)
4. Determine the test run command from the project's package.json, CLAUDE.md, or Makefile

Announce to the user: the framework detected, the test command you'll use, and which file you'll add tests to (or create).

Step 1: RED — Write a Failing Test

Write one test that describes the next behavior to implement.

Test writing rules:

• Test exactly one behavior per test
• Use a descriptive name that states expected behavior (e.g., test_returns_empty_list_when_no_products_match not test_filter)
• Follow Arrange-Act-Assert:
  • Arrange: Set up preconditions and inputs
  • Act: Call the function or perform the action under test
  • Assert: Verify the expected outcome
• Tests must be independent — no shared mutable state, no reliance on test execution order
• Import or reference the production code path where the implementation will live, even though it doesn't exist yet

Run the test using Bash to confirm it fails. Verify the failure is for the right reason:

• Expected: import error, function not found, assertion failed because feature doesn't exist
• Not expected: syntax error in the test, wrong test framework, unrelated crash

If the test fails for the wrong reason, fix the test and re-run before proceeding.

Tell the user: RED: Test fails — [reason]

Step 2: GREEN — Write Minimum Code to Pass

Write the minimum production code needed to make the failing test pass.

Green phase rules:

• Only write code that is directly required by the failing test
• Hard-coded return values are acceptable if the test only checks one case
• Do not add error handling, validation, or features that no test demands yet
• Do not refactor yet — that's the next step
• Do not write additional tests — stay focused on making this one pass

Run the test to confirm it passes.

If it fails, fix the production code (not the test) and re-run. The test from the RED phase defines the contract — the code must meet it.

Tell the user: GREEN: Test passes

Step 3: REFACTOR — Improve While Staying Green

Now improve the code you just wrote (and any related code) without changing behavior.

Refactor targets:

• Remove duplication (in both production code and tests)
• Improve variable and function names
• Extract helpers if logic is repeated
• Simplify conditionals
• Improve code structure and readability

Refactor rules:

• Only refactor when all tests are green
• Run tests after every change — if anything breaks, undo the last change immediately
• Do not add new behavior during refactoring
• Keep refactoring small and incremental

Tell the user: REFACTOR: [what you improved] or REFACTOR: No changes needed — code is clean

Step 4: Repeat or Finish

After completing one cycle, assess progress:

• If the feature has more behaviors to implement, return to Step 1 with the next behavior
• If all described behaviors are covered, run the full test suite to check for regressions
• Present a summary when done

Handling Multiple Behaviors

When the user describes a feature with multiple aspects, decompose it into a sequence of behaviors to implement one at a time. List them before starting:

Feature: [name]
Behaviors to implement:
1. [First behavior — simplest/foundational]
2. [Second behavior — builds on first]
3. [Third behavior — edge case or variation]

Start with the simplest or most foundational behavior. Each cycle builds on the last.

Output Format

For each cycle, clearly label the phase:

── Cycle 1: [behavior being implemented] ──

RED: Writing test...
  [show test code]
  Running: [test command]
  Result: FAIL — [failure reason] (expected)

GREEN: Writing implementation...
  [show production code]
  Running: [test command]
  Result: PASS

REFACTOR: [what was improved, or "no changes needed"]
  Running: [test command]
  Result: PASS

After all cycles:

── Summary ──
Feature: [name]
Cycles: [N]
Tests written: [N]
Files modified: [list]
All tests passing: yes/no

Best Practices

• One test, one behavior — resist the urge to test multiple things at once
• Let the test drive the design — don't plan the implementation before writing the test
• Keep the green phase minimal — perfection comes in refactoring, not in the first pass
• Run tests constantly — after every code change, no exceptions
• If you get stuck in red, the test might be too big — split it into a smaller behavior
• Match the project's existing test style and conventions