domain-modeling

Domain Modeling

A model's vocabulary is the code's vocabulary. The same word means the same thing in conversation, code, and documentation; inside one deliberately bounded area. A term that needs qualifying every time it's used ("order" meaning a purchase in one team's code and a queue position in another's) is not one term with an ambiguity problem, it's two terms wearing the same word, and the fix is a boundary, not a footnote.

Phase 1: Build the ubiquitous language

• Build the vocabulary with the people who know the domain, not in isolation; a term invented by engineers alone tends to drift from how the business actually talks about the thing, which reopens the translation gap this phase exists to close.
• Use the agreed term everywhere: class names, variable names, module boundaries, commit messages, conversation, and documentation. If the code says Customer and the domain experts say Client, one of the two is wrong; reconcile it rather than letting code and conversation quietly diverge into two dialects.
• A term needing a qualifier every time it's spoken ("the shipping order, not the purchase order") is the tell that two concepts are sharing one word. Split the word, or draw a boundary (Phase 2) so each side keeps its own meaning without collision.
• Record the language in a living glossary (a CONTEXT.md or equivalent) that a new contributor reads before writing code in the area; the language exists to lower everyone's cognitive load, which only works if it's written down somewhere more durable than institutional memory.
• domain-modeling owns the project's glossary or vocabulary artifact (CONTEXT.md or equivalent). explain-plainly should consume its terms or propose entries into that artifact rather than maintaining a separate glossary.

Phase 2: Draw bounded contexts

A bounded context is an explicit boundary (team, codebase area, or database schema) inside which one model and its language hold a single, consistent meaning. Outside that boundary, the same word is allowed to mean something else on purpose, because it belongs to a different model serving a different concern.