Originally published at tddbuddy.com.
Related reading: The Hidden Output of TDD Was Never Code argued the suite IS the controlled vocabulary. Spec-Driven Development Is the Prose-Spec Drift Trap, Reborn named the structural failure mode this post extends to the glossary tier. The Instruction File Is Not the Discipline is the companion on procedural prose artifacts; this post is the companion on noun claims.
The glossary said "loyalty member" means a customer with an active card. The builder had required a verified email for six months. The new hire wrote their test from the glossary.
The 2026 practitioner community converged on a specific artifact: a UBIQUITOUS_LANGUAGE.md or glossary file the coding agent reads before every write. The mattpocock ubiquitous-language skill scans conversations for domain terms, flags synonyms and overloaded words, and writes a canonical glossary with definitions and aliases. Giuseppe Trisciuoglio's constitution skill splits the artifact into an architecture file and an ontology file. AgentOps publishes a shared-vocabulary library that other skills load on demand. Variants of the same pattern ship across the coding-agent ecosystem.
The direction is sound. An agent cannot pick up the institutional context a new engineer absorbs by osmosis, so the canonical terms the team has committed to have to sit in an artifact the agent reads. The vocabulary arc argued earlier in the year that vocabulary is the asset agents amplify, and the vocabulary file is the industry's attempt to make the asset discoverable. The sharper claim is about which artifact ends up canonical. A vocabulary file maintained alongside a strong test API is a second source of truth, and the spec-driven-is-the-drift-trap post already named the structural failure mode of exactly that pattern.
The vocabulary file is scaffolding. The test API is the dictionary. A team that forgets which is which rebuilds the drift trap one glossary at a time.
The 2026 Community Converged on the Vocabulary File
The diagnosis the pattern is responding to is correct. An agent arriving at a repository with no prior session carries none of the institutional context a team member absorbs over a quarter of standups, review comments, and corridor conversations. The glossary file is a serialization of that context, written for the agent to read before it writes a line.
The engineering is also real. The mattpocock skill does synonym detection, overloaded-term flagging, and alias handling. The Giuseppe Trisciuoglio constitution split separates ontology from architecture, which is a design improvement over earlier monolithic AGENTS.md files. AgentOps's shared-vocabulary library lets other skills load terms on demand instead of baking them into every prompt. The pattern is thoughtful, widely adopted, and solving a problem that deserves to be solved.
The lineage is older than 2026. Ubiquitous language is Eric Evans's term from Domain-Driven Design; the DDD tradition argued for twenty years that the team must speak one language across code, tests, documentation, and conversation. The 2026 extension is specifically about which artifact the AGENT reads to pick that language up. The question the pattern is answering is new. The question it is not answering, which is which artifact stays canonical as the suite matures, is the whole of this post.
The File Is a Bootstrap, Not a Canonical Source
The file earns its keep in the window where the suite does not yet encode the terms. A greenfield project with no scenario tests has no vocabulary surface for the agent to read. A mid-migration project with legacy code and new tests has partial coverage. Both benefit from a file that names the terms until the suite catches up. The disciplined move is to treat the vocabulary file as scaffolding that comes down as the suite becomes canonical.
**Loyalty member**: a customer with an active loyalty card issued in a past
calendar year. Aliases: "loyalty customer", "card holder".
See also: "first-year member" (narrower).
Not to be confused with: "subscriber" (billing concept, not loyalty).
aLoyaltyMember()
aLoyaltyMember().inTheirFirstYear()
aSubscriber() // distinct builder in the billing module
The file is prose about the terms. The suite is the terms. The two artifacts carry the same information in different registers, which is fine while both are young and dangerous when the suite is strong and the file is forgotten. A new hire reads the glossary. The glossary says "customer with an active card." The builder has required a verified email for six months, since an identity-verification sprint nobody updated the glossary for. The new hire writes a test with their own new Customer { HasLoyaltyCard = true } setup. The suite accepts the test. The production path handles the test's data differently from every other loyalty scenario because the email requirement is in the builder, not the glossary. The glossary did not lie. It just stopped being true.
Two Canonical Sources Rebuild the Prose-Spec Drift Trap
The spec-driven post named the structural failure mode: a non-executable artifact positioned as a source of truth drifts from the running code at the same rate every prose spec in the industry has ever drifted. The Confluence spec went stale against the service. The Gherkin feature file went stale against the step definitions. The OpenAPI document went stale against the implementation. The vocabulary file is the same shape at the glossary tier.
The mechanism is identical. The code changes with every commit because the compiler and the suite force it to. The prose does not, because nothing fails when the prose becomes false. The drift accrues silently. By the time a reader notices, the file is reporting a vocabulary from an older version of the system, and the reader cannot tell which entries are current without checking each one against the suite anyway, which is the work the file was supposed to save them from doing.
The spec-driven failure mode had a precise shape: the artifact competed with the running code for authority and lost without resigning. The glossary carries that shape forward. A team that treats the glossary as the source of truth will discover, repeatedly, that the agent produced code consistent with the glossary and inconsistent with the suite, which is the opposite of the win the pattern was supposed to deliver.
The Test API Is the Vocabulary Surface That Does Not Drift From Itself
A builder named aLoyaltyMember() IS the term "loyalty member" in the codebase's language. A rename of the builder is a rename of the term, enforced at every call site by the compiler. The glossary describing the term is a copy; the builder is the referent.
That distinction is the whole post. A copy can disagree with the original. A referent cannot disagree with itself. The suite is the vocabulary surface that holds canonical state because the state is the artifact. Changing aLoyaltyMember() to require a verified email is not a description of a change; it is the change. Every test using the builder picks up the new behavior at the next test run. Every production call site that composes against the builder picks up the new behavior at the next build. The compiler and the test runner enforce the vocabulary without a glossary needing to agree.
A vocabulary file positioned as a secondary reference (generated from the builder API, treated as a convenience view, updated from the suite) is one shape. A vocabulary file positioned as the source of truth that the suite must honor is a different shape. The second shape is where the drift trap lives.
The Glossary's Job Is to Dissolve Itself
The successful glossary ends by not being needed. A vocabulary file with 40 entries at the start of a project has done its job when 36 of those entries have corresponding builders, factories or domain types. The 36 are now in the suite. The file is a receipt of work the suite now carries.
year 0: 40 glossary entries, 0 builders
year 1: 12 glossary entries, 28 builders
year 2: 4 glossary entries, 36 builders
The dissolution is the goal. A simple audit makes the progress visible: a script that compares glossary entries to builder method names and reports which entries have a corresponding builder. Entries matched by a builder are candidates for deletion from the glossary. Entries without a builder are candidates for either a new builder or placement in a residual list of terms the suite cannot easily embody. The audit is a scaffolding-removal tool, not a maintenance tool. Running it quarterly is a reasonable rhythm; running it never leaves the scaffold up long after the building is standing.
The honest residual role of the file is small. Regulatory categories named in prose but not instantiated in code. Cross-team enums whose canonical home is a schema the team does not own. External-domain names the team uses in review but never calls directly. The residual is tens of entries, not hundreds, and the residual's purpose is explicit coordination with artifacts outside the suite's reach, not a parallel description of what the suite already encodes.
The Successful Glossary Ends by Not Being Needed
Concede the coordination role before closing. The glossary IS useful during new-hire onboarding, cross-team integration, and the bootstrap window when the suite's vocabulary surface is thin. The sharper claim is about canonicity. The suite is the dictionary. The file is a reader's guide to the dictionary, and a reader's guide to a dictionary that has not been written yet is one shape of document, and a reader's guide maintained indefinitely alongside a complete dictionary is a different shape, and only one of those shapes is doing useful work.
The glossary said "loyalty member" means a customer with an active card. The builder required a verified email. The new hire wrote their test from the glossary. The test passed. The production path broke on a case the glossary had never heard of because the glossary was tracking a version of the vocabulary the suite had moved past.
The vocabulary file is scaffolding. The test API is the vocabulary. A team maintaining both indefinitely has not finished the dictionary; a team that treats the file as the destination has rebuilt the prose-spec drift trap at the glossary tier. The successful glossary ends by not being needed, because the suite ended up carrying the terms the glossary was holding in trust until it could.
Top comments (0)