House rulesLesson

Ubiquitous language

When people and agents use different words for one thing, or one word for different things, every conversation about the code drifts. A glossary fixes the words. In a project with several distinct parts, one glossary per part keeps each list short enough to read.

Know ubiquitous language already? Skip to In Terrarium.

Outside the box · General

The concept

Eric Evans's domain-driven design calls it a ubiquitous language: one shared vocabulary that developers and the people who know the domain both use, in conversation, in documents and in the code itself. Each term has one definition and one preferred word.

One language rarely fits a large system. The same word can mean different things in two parts of it: an "account" in billing is not an "account" in sign-in. Domain-driven design draws a boundary, a bounded context, around each part, and each context gets its own language. A map says which contexts exist and how they relate.

For an agent, the glossary is also context it reads. A short glossary costs every session little, while words from parts of the system the session never touches only crowd out the ones it needs.

Full referenceUbiquitous Language (Martin Fowler)

Looking inside

In Terrarium

Terrarium splits its vocabulary by who needs it; GLOSSARY-MAP.md lists every glossary, which is also the list of Tenants. The ADR that settles the split starts with where a term goes:

docs/adr/0021-multi-context-domain-docs.md ↗11–14as of 1 Nov 2026

11- **Where a term goes.** A term an agent needs whatever the task goes in the
12  root `GLOSSARY.md`. A term used only while working on one Tenant goes in that
13  Tenant's `GLOSSARY.md`. Each term is defined once; other files may point to
14  it.

The Platform glossary, GLOSSARY.md, holds the words every agent needs whatever its task, such as , and . The file has two sections, ## Glossary and ## Retired terms; ADR-0021 (docs/adr/0021-multi-context-domain-docs.md) sets what each may hold. CLAUDE.md imports the map and then this glossary, and tells agents to use a glossary's term rather than a synonym.

Each Tenant's own words live in layers/<tenant>/GLOSSARY.md, beside its code. The Blog's glossary, layers/blog/GLOSSARY.md, defines a as a Space of the Blog, and the Atlas's glossary defines a as a Space of the Atlas. A rule, .claude/rules/tenant-glossary.md, has an agent read a Tenant's glossary before it works on that Tenant. Besides its terms, a Tenant's glossary holds why the Tenant exists, who it is for and its product decisions.

Each term is defined once, in one glossary; anywhere else may point to it. The rule of two in docs/agents/domain.md gives a concept a term only once its second instance exists or is concretely scheduled; before that it is described in plain words where it lives. It also says a concept missing from the glossary means either the writer is inventing language or there is a real gap to record. A rule, .claude/rules/glossary-terms.md, sends an agent to that doc before it adds or changes a term.

Why it's built this way

Split by who needs a word. When the root glossary held every Tenant's words, an agent looking up a Platform term read past another Tenant's fictional species. Terrarium keeps the root to words every agent needs, and a Tenant's words beside its code. The cost: more files than one flat glossary, which was simpler. ADR-0021 (docs/adr/0021-multi-context-domain-docs.md).
A home for a Tenant's purpose. A demo Tenant's reason to exist is a product choice. The definitions-only root can't hold it, and an ADR per Tenant would mix product choices with architecture, so the Tenant's glossary holds it. The cost: an agent may merge a change to those decisions in an ordinary PR, while an ADR change waits for a human merge. ADR-0021 (docs/adr/0021-multi-context-domain-docs.md).
Coin a word on its second instance. Every session reads the glossary and checks its words against it, so each coined term costs every session. A second instance proves a term worth that cost. The cost: the first instance is described in plain words until a second one arrives. docs/agents/domain.md

What to watch for

The Skill's templates differ. The domain-modeling Skill in .agents/skills/domain-modeling/ supports several glossaries tied together by a map, which is the shape Terrarium uses. Its entry layout differs from Terrarium's, and domain.md lists where Terrarium departs from it.

Try it in your project

List the five nouns your team argues about most. Write each with a one-sentence definition in a GLOSSARY.md at the root, and add one line to your CLAUDE.md that imports it with @GLOSSARY.md and tells agents to use its words. When one part of the system starts using a word differently, give that part its own glossary and add a map.

Where next

Last updated 1 Nov 2026 · Latest source on GitHub ↗