Test with confidence, code with clarity

Your home for mastering Test-Driven Development through real-world katas and expert guidance.

TDD Buddy Logo
Latest The Vocabulary File Is Scaffolding, Not Destination

Kata Catalog

Practice TDD with a curated set of real-world katas, each with clear requirements and test cases.

Browse Katas

Guides & References

Learn best practices, naming conventions, and advanced TDD techniques from industry experts.

Explore Guides

Interactive Learning

Discover the TDD Gears model and learn how to apply TDD principles in real-world scenarios.

Learn More

Why TDD Matters More in the AI Era

The bar for "good tests" just moved. Agents made it non-optional.

  • The 2026 community wave converged on a vocabulary file. The mattpocock ubiquitous-language skill is widely installed. Giuseppe Trisciuoglio's constitution split publishes an ontology file. AgentOps keeps a shared-vocabulary library. The direction is sound: the agent cannot pick up institutional context, so canonical terms have to sit in the artifact it reads.
  • The file is a bootstrap, not a canonical source. The vocabulary file earns its keep when the test API has not yet pinned the terms. Once the suite composes with `aLoyaltyMember()` and `anOrderOver(50.dollars())`, the glossary is retelling the same story in a second artifact that is free to drift from the first.
  • Two canonical sources rebuild the prose-spec drift trap. The spec-driven-is-the-drift-trap post named the failure mode: a non-executable artifact positioned as the source of truth drifts from the running code. The vocabulary file is the same shape at the glossary tier. The test API does not drift from itself; the glossary does and will.
  • The glossary's job is to dissolve itself. A vocabulary file whose terms have been absorbed into the builder API is a scaffold the codebase can take down. A vocabulary file maintained indefinitely alongside a strong test API is a parallel artifact competing with the running code for authority. The successful glossary ends by not being needed.

Read the argument: The Vocabulary File Is Scaffolding, Not Destination

The Bar Moved

Old bar

Tests exist and pass. Good enough for humans with context.

New bar

Scenario names · builders · domain types · ubiquitous language. The test suite is the interface agents operate against.

TDD Gears

Shift gears based on context, not habit

TDD Gears model showing Low, Medium, High, and Reverse gears for test-driven development

Low Gear

New territory. Build context. Small steps. Learn the shape of the problem before solving it.

Medium Gear

Patterns emerge. Apply design principles. Let the tests guide you toward better abstractions.

High Gear

Known patterns. Follow existing architecture. Move fast because the structure is already proven.

Reverse Gear

Wrong direction. Back up. Delete the test. Try a different approach. This isn't failure — it's steering.