Test-Driven Development

Apply these test-quality rules during each red → green cycle.

Read GLOSSARY.md, then use docs/decisions/README.md to load only the decision subjects relevant to the behavior under test. If code, spec, and a decision contract conflict at the decision level, surface the conflict instead of silently choosing one. Use current terms in test names and public interfaces.

Good tests

Test behavior through public interfaces so internal refactoring does not break tests. Use specification-style names that state the capability under test.

Mock only at system boundaries such as external APIs, time, and randomness; prefer a real test database over a mocked one.

Seams

A seam is the public boundary where a test observes behavior without reaching into internals.

Reuse an existing seam before creating one. Create a seam only for a stable use case or domain concept, not an implementation helper whose name may change.

Select test seams from the agreed behavior and existing public interfaces, prioritizing critical paths and complex logic. Briefly state the chosen seam and the behavior it will verify, then proceed with the first test.

Resolve technical uncertainty through repository evidence. Ask the user only when the expected behavior remains unclear or proceeding would change the agreed product contract.

Anti-patterns

• Implementation-coupled: mocks internal collaborators, tests private methods, or verifies through a side channel. It breaks when implementation changes but behavior does not.
• Tautological: derives the expected value using the same logic as the code, so the assertion passes by construction. Use an independent source such as a known literal, worked example, or spec.
• Horizontal slicing: writes many tests before any implementation. Implement one failing test and its minimal code before choosing the next test.

Loop rules

• Red before green. Write the failing test first, then only enough code to pass it. Do not anticipate future tests or add speculative features.
• One slice at a time. Use one seam, one test, and one minimal implementation per cycle.
• Refactor after green. Keep the tests green through the refactor. This loop opens no review of its own: reviewing the finished diff belongs to whatever workflow owns it, or to a review the user runs.