Test-Driven Development

Philosophy

Core principle: tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.

• Good tests are integration-style: real code paths through public APIs. They read like specs ("user can checkout with valid cart") and survive refactors.
• Bad tests couple to implementation: mock internal collaborators, hit private methods, or verify via side channels (e.g. raw DB queries). Warning sign: the test breaks on a refactor with no behavior change.

See tests.md for examples and mocking.md for mocking rules.

Anti-pattern: horizontal slices

Do not write all tests first, then all implementation. Bulk-written tests verify imagined behavior — they test the shape of things (signatures, data) rather than user-facing behavior, and become insensitive to real changes.

Correct: vertical slices. One test → one implementation → repeat. Each test responds to what you learned from the previous cycle.

WRONG (horizontal):  RED: t1,t2,t3,t4,t5  → GREEN: i1,i2,i3,i4,i5
RIGHT (vertical):    RED→GREEN: t1→i1, t2→i2, t3→i3, ...

Workflow

1. Planning

Before writing code:

• Confirm interface changes with the user
• Confirm which behaviors to test, prioritized — you can't test everything
• Identify deep modules (small interface, deep implementation)
• Design interfaces for testability
• List behaviors (not implementation steps)
• Get user approval

Ask: "What should the public interface look like? Which behaviors matter most?"

2. Tracer bullet

Write ONE test for ONE behavior. RED → minimal code → GREEN. Proves the path works end-to-end.

3. Incremental loop

For each remaining behavior: RED (next test fails) → GREEN (minimal code passes).

Rules: one test at a time; only enough code to pass it; no anticipating future tests; tests stay on observable behavior.

4. Refactor

After GREEN, look for refactor candidates:

• Extract duplication
• Deepen modules (move complexity behind simple interfaces)
• Apply SOLID where natural
• Reconsider existing code in light of the new code
• Re-run tests after each step

Never refactor while RED. Get to GREEN first.

Per-cycle checklist

[ ] Test describes behavior, not implementation
[ ] Test uses public interface only
[ ] Test would survive an internal refactor
[ ] Code is minimal for this test
[ ] No speculative features added

When the function under test builds prompts

If your function assembles a prompt that gets shipped to an LLM (or stored in a cache key), add one regression test that pins the exact byte sequence for a representative input. Prompt-cache hit rates depend on byte-equal prefixes; a refactor that re-orders fields, swaps a sort -u for awk '!seen[$0]++', or relies on find's readdir order can silently change the bytes without changing the test's observable behavior — and shred the cache. Test seen in practice: extracting a helper changed find issues -name '*.md' order from one machine to another; behavior tests stayed green; prompt cache lost ~40% of its hit rate for a day.