glossary

Glossary

A glossary prevents naming drift on the small set of terms where drift is likely. It is not a project dictionary — not every domain concept belongs. The highest-leverage element of each entry is the rationale on the Avoid line: what plausible-but-wrong name would a reviewer or agent reach for, and why is it a trap? Without that rationale, the entry teaches nothing.

LLMs are amplifiers — give them a clear vocabulary and they generate coherent structure; give them a codebase where the same concept has four names, and they'll invent a fifth. The glossary makes the choice for them.

A glossary's real failure mode is disuse. If it isn't the document a reviewer reaches for during naming disagreements, no amount of format polish saves it. Every rule below — the trap test, rationale-bearing Avoid lines, the CLAUDE.md pointer — exists to make the glossary worth opening.

Scope

Decide how many glossaries the project needs:

• Single glossary — one domain, one team, no terms with double meanings across the codebase.
• Per-bounded-context — the same word means different things in different parts of the system (e.g., Order in billing vs fulfillment). In DDD terms, each bounded context speaks its own dialect of the ubiquitous language; one glossary per dialect. Create one file per context; name each context explicitly.

Context map (multiple contexts only)

A per-context glossary defines terms within its dialect, but the relationships between contexts — which context emits an event another consumes, which value types they share — live in no single glossary. When a project has several context glossaries, an optional docs/ubiquitous-language/context-map.md names each context with a one-line purpose and the directional flows between them:

## Contexts

- **Ordering** — places and tracks customer orders.
- **Fulfillment** — picks, packs, ships.

## Relationships

- Ordering emits `OrderPlaced`; Fulfillment consumes it.
- Ordering and Billing share `CustomerId` and `Money`.