tdd

TDD — Test-Driven Development

Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST. Violating the letter of this process is violating the spirit of this process.

Process

Red → Green → Refactor

1. Red: Write a failing test that describes the desired behavior

   • Test name should read like a spec: it("returns 401 when token is expired") (reason: the test name IS your specification — it must communicate intent to future readers)
   • Run the test — confirm it fails for the right reason (reason: a test that fails for the wrong reason gives false confidence)

2. Green: Write the minimum code to make the test pass

   • Do not write more than needed — because premature optimization is the root of all evil; make it work first
   • Do not optimize yet — because optimization without a passing test is speculation, not engineering
   • Run the test — confirm it passes (reason: a passing test is the only proof the code works)

3. Refactor: Clean up without changing behavior

   • Extract duplicates, rename for clarity, simplify — because readability matters more than cleverness
   • Run tests again — must still pass (reason: refactoring without re-running tests is just renaming bugs)

Cycle

Repeat for each behavior. One test, one behavior, one cycle — because scope creep in a single test cycle leads to unverified code.

When to Trigger

• /go subagents: always — because autonomous agents without TDD produce unverified code
• New function or method being written
• Bug fix (write regression test first — because a bug that happened once will happen again without a guard)

Anti-Rationalization

Excuse	Rebuttal	What to do instead
"This is too simple for tests"	Simple code still breaks. The Beyonce Rule applies: if you liked it, you should have put a test on it.	Write the test anyway — it takes 30 seconds and catches edge cases.
"I'll write tests after"	That's documentation, not specification. Tests written after confirm what you built; tests written before define what you should build.	Write the test first. If you can't describe the behavior, you don't understand the requirement.
"Tests slow me down"	15 minutes of TDD saves hours of debugging regression bugs later.	Time the cycle — Red-Green-Refactor is usually faster than debug-after-deploy.
"I'll just test manually"	Manual tests don't catch regressions. Automate it once, save hours forever.	Write an automated test that runs on every commit.
"The types guarantee correctness"	Types check shape, not logic. add(a,b) can still return a-b.	Write a test that verifies the actual business rule, not just the type signature.
"I need to see the API shape first"	Spike freely, then delete and rebuild test-first. A throwaway spike is research, not implementation.	Spike, discard, then TDD the real implementation from what you learned.

Evidence Required

Before claiming TDD is done, show ALL of these:

• Failing test output (Red phase): the test name and failure message
• Passing test output (Green phase): ✓ with the same test name
• Test covers behavior, not implementation (no mocking internals)
• Refactor step completed OR explicitly noted as unnecessary with reason

No evidence = not done. "I wrote tests" without showing output is not TDD.

Red Flags

• Writing implementation before any test exists
• Test that tests implementation details instead of behavior
• Skipping the refactor step
• Multiple behaviors in one test