Test-Driven Development
Write one failing test that describes the next behavior, write the minimal code to pass it, then refactor while green. Every production change starts with a test that proves the need exists. This is the discipline within each vertical slice — not framework syntax, but when and why to write tests.
Skip for exploratory prototyping, config-only changes (environment variables, feature flags), visual/CSS-only tweaks, and one-off scripts that won't be maintained.
Quick Reference — TDD Cycle
| Phase | Action | Rule |
|---|
| RED | Write one test that fails for the right reason | No production code without a failing test |
| GREEN | Write the simplest code that makes the test pass | Resist the urge to generalize prematurely |
| REFACTOR | Improve structure while all tests stay green | Never change behavior and structure at once |
Quick Reference — Principles
| Principle | Practice |
|---|
| One test at a time | Complete the full red-green-refactor cycle before writing the next test |
| Behavior over implementation | Test what code does, not how it does it; assert outputs and side effects |
| Vertical slices | TDD one end-to-end behavior at a time, not one layer at a time |
| Mock at boundaries | Mock I/O, network, filesystem, clock. Never mock internal collaborators |
| Deep modules | Design small interfaces with rich internals; fewer tests cover more behavior |
| Refactor only when green | All tests pass before touching structure; refactoring under red hides new bugs |
| Design through tests | The first test IS the API design decision; awkward tests signal awkward interfaces |
| Failing test for every bug | Reproduce the bug as a failing test before writing the fix |
Planning Before Coding
| Step | Action | Output |
|---|
| 1 | Identify behaviors | List of observable behaviors the feature must exhibit |
| 2 | Order by dependency | Sequence where each test builds on prior passing tests |
| 3 | Design the interface | Function signatures, parameter types, return types |
| 4 | Identify mock boundaries | External dependencies that need test doubles |
Common Mistakes
| Mistake | Correct Pattern |
|---|
| Writing all tests first | One test at a time. Complete the cycle before starting the next |
| Testing private methods | Test through the public interface; private methods are implementation detail |
| Mocking internal collaborators | Only mock at I/O boundaries; trust your own code |
| Writing code before a failing test | RED first. The failing test proves the behavior is missing |
| Refactoring while tests are red | Get to GREEN first, then refactor with confidence |
| Tests coupled to call sequences | Assert on outputs and state, not on which internal methods were called |
| Skipping the refactor phase | GREEN is not done. Clean up duplication and naming before moving on |
| Hardcoding expected values | Use triangulation: add a second test case to force the general solution |
| One giant test per feature | One test per behavior — small, focused, independently meaningful |
Delegation
- Slice decomposition: If the
tracer-bullets skill is available, use it to decompose features into vertical slices before applying TDD within each slice
- Test framework syntax: Delegate framework-specific patterns to
vitest-testing, e2e-testing, or api-testing skills
- Feature planning: If the
plan-first-development skill is available, use it for upfront planning before entering the TDD cycle
- Individual TDD cycles: Delegate each red-green-refactor cycle to a
Task subagent to keep context focused
References
- Test Quality — good vs bad tests, what to test, naming, triangulation, refactoring signals
- Mocking Boundaries — boundary rule, test doubles, dependency injection, anti-patterns
- Design for Testability — deep modules, interface-first design, pure functions, computation vs I/O