ConcertoNotes 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
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)
- Test name should read like a spec:
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)
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
/gosubagents: 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