Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Ubiquitous Language

Pattern

A reusable solution you can apply to your work.

A ubiquitous language is a shared vocabulary, drawn from the business domain, that every participant in a project uses consistently in conversation, documentation, and code.

“If you’re arguing about what a word means, you’re doing design.” — Eric Evans, paraphrased from Domain-Driven Design

Also known as: Domain Language, Shared Vocabulary

Understand This First

  • Domain Model – the domain model identifies the concepts; the ubiquitous language gives them authoritative names.
  • Requirement – requirements written in the ubiquitous language are less ambiguous.

Context

You’ve identified the concepts in your problem domain, perhaps by building a domain model. Now everyone on the team needs to talk about those concepts the same way. This operates at the architectural level because language decisions ripple into class names, variable names, API endpoints, database columns, and documentation. A naming choice made in a whiteboard session ends up as a column header someone reads three years later.

Eric Evans coined the term in his 2003 book Domain-Driven Design. The idea is simple: the development team and the domain experts agree on a single set of terms for the things the software deals with, and then everyone uses those terms everywhere. In code. In conversation. In tickets. In tests.

Problem

How do you prevent the slow drift where developers, product managers, domain experts, and AI agents all use different words for the same thing, or the same word for different things?

A team building a healthcare scheduling system calls the same concept “appointment” in the product requirements, “booking” in the API, “slot” in the database, and “visit” in the UI. Each translation is a place where meaning can slip. A developer reads “booking” in the code and assumes it means a confirmed reservation. The product manager meant it as a tentative hold. The bug that results from this mismatch won’t look like a naming problem. It will look like wrong business logic, and it will take days to trace back to a vocabulary disagreement.

Forces

  • Domain experts and developers come from different backgrounds and naturally use different vocabularies for the same concepts.
  • Code is precise; conversation is loose. Terms that feel interchangeable in a meeting (“customer” vs. “client” vs. “account holder”) create real ambiguity in code.
  • The language needs to be simple enough for non-technical stakeholders to use but precise enough for developers to implement.
  • AI agents treat names as hard signals. An agent that encounters booking, appointment, and slot in the same codebase will treat them as three distinct concepts unless told otherwise.

Solution

Choose one term for each domain concept and use it everywhere. Write the terms down in a glossary that the whole team can reference. When someone introduces a new term or uses a synonym, stop and resolve it: is this a new concept, or a different name for something that already exists? If it’s a synonym, pick the winner and update the code to match.

The glossary doesn’t need to be elaborate. A markdown file listing each term with a one-sentence definition is enough to start. What matters is that it exists, that it’s maintained, and that it has authority. When the glossary says the concept is called “appointment” and someone’s PR uses “booking,” the review comment is straightforward: “Our domain language calls this an appointment.”

For agentic workflows, the glossary becomes a context document you include in the agent’s prompt or instruction file. Daniel Schleicher’s Spec Ambiguity Resolver demonstrated this approach: it maintains a living domain-terms.md file as the single source of truth for project vocabulary, referencing it during spec writing, design, and implementation. The agent checks new terms against the glossary before using them. When it encounters ambiguity, it flags the conflict rather than guessing.

This works because language models are amplifiers. Give an agent clear, consistent terminology and it generates code with matching names and coherent structure. Give it a codebase where the same concept has four names, and it will invent a fifth.

How It Plays Out

A fintech team builds a lending platform. Early on, the codebase uses “loan,” “credit facility,” and “advance” interchangeably. The domain experts clarify: a “loan” is a fixed-amount disbursement with a repayment schedule. A “credit facility” is a revolving line. An “advance” is an informal term they want to stop using. The team writes a glossary, renames the code to match, and adds a linting rule that flags “advance” in new code.

Six months later, when they direct an agent to add a refinancing feature, they include the glossary in the context. The agent asks: “Should a refinance create a new loan entity or modify the existing one?” That’s the right question, asked in the right terms, because the agent shares the team’s vocabulary.

Without the glossary, the agent would have generated code using whatever term it inferred from the surrounding context, and different files would have pulled it in different directions.

Example Prompt

“Read the domain glossary in docs/domain-terms.md before making any changes. We call the person receiving care a ‘patient,’ not a ‘client’ or ‘user.’ Add a referral tracking feature where a provider can refer a patient to a specialist. Use the term ‘referral’ consistently, not ‘recommendation’ or ‘transfer.’”

Consequences

A shared language cuts translation overhead. Code reviews go faster because reviewers don’t mentally map between vocabularies. Onboarding improves because new team members (and new agents) learn one set of terms instead of decoding a patchwork of synonyms. Conversations with domain experts become more productive because both sides speak the same dialect.

The cost is discipline. Maintaining a ubiquitous language requires the team to care about naming and to push back when someone introduces a rogue term. It also requires updating the glossary as the domain evolves, and renaming code when the agreed terminology changes. Renaming is real work with real risk, especially in a large codebase, but the alternative is a system that slowly becomes unintelligible to everyone, including the agents working in it.

There’s a scope limit too. A ubiquitous language works within a bounded context, not across an entire organization. The word “account” means one thing in the billing system and something different in the identity system. Trying to force a single definition across both leads to a bloated, compromised term that satisfies nobody. Each bounded context gets its own language, with explicit translation at the boundaries.

  • Uses / Depends on: Domain Model – the domain model identifies the concepts; the ubiquitous language gives them authoritative names.
  • Uses / Depends on: Requirement – requirements written in the ubiquitous language are less ambiguous.
  • Enables: Cohesion – code organized around shared domain terms tends to group related behavior naturally.
  • Enables: Instruction File – a domain glossary is a form of instruction file that shapes agent behavior through vocabulary.
  • Enables: Source of Truth – the glossary is the source of truth for naming.
  • Enables: Naming – the ubiquitous language provides the domain terms that code identifiers should draw from.
  • Contrasts with: Data Model – a data model defines structure; a ubiquitous language defines the words used to talk about that structure.

Sources

  • Eric Evans introduced ubiquitous language as a core practice in Domain-Driven Design: Tackling Complexity in the Heart of Software (2003). Chapters 2-3 develop the argument that a shared vocabulary, used consistently in conversation and code, is the foundation of effective domain modeling.
  • Daniel Schleicher demonstrated how ubiquitous language translates to agentic workflows in “How Creating a Ubiquitous Language Ensures AI Builds What You Actually Want” (2026). His Spec Ambiguity Resolver maintains a living glossary file that agents reference during spec writing and implementation.

Further Reading

  • Vaughn Vernon, Domain-Driven Design Distilled (2016) – a shorter, more accessible introduction to DDD that covers ubiquitous language without the full weight of Evans’s 500-page treatment.