← narwal.one/Second Brain
SecondBrain
Ask the Brain
Index/Conceptupdated Sat Sep 26 2026 08:00:00 GMT+0800 (Philippine Standard Time)

Ubiquitous Language

ddddomain-driven-designterminologyagent-steeringai-codingcontext-engineering

Ubiquitous Language

Domain-driven design's core discipline, ported by Matt Pocock into AI-coding practice: one shared set of terms that developers, domain experts, and the code itself all use the same way. Concretely, a markdown file of terms (usually as a table) that the human, the agent, and the codebase all reference.

The original DDD formulation Pocock quotes:

"Conversations among developers, and expressions of the code, and conversations with domain experts are all derived from the same domain model."

Why it matters more under AI

Pocock's failure mode: the AI is way too verbose — it's like you're talking at cross-purposes. Diagnosis: no shared language. Two sides using overlapping terms with different meanings produces low-quality translation on both ends — the domain expert's intent → code loses fidelity; the code → explanation to the domain expert loses fidelity. Under AI, the agent is one of the parties in that translation loop, and its verbosity is a symptom of missing shared vocabulary.

Effects Pocock claims (from watching Claude's thinking traces during use):

  • Less verbose reasoning — the agent's thoughts get more compact when it has the right terms to reach for.
  • More aligned implementation — the code matches the plan better because the same words survive the plan → code hop.
  • Sharper planning — the ubiquitous-language file is open during planning, so both sides reach for the same terms.

The Pocock skill

ubiquitous-language — scans your codebase for existing terminology, builds a markdown file with tables of terms + definitions. Kept open during planning, referenced during implementation, updated as the vocabulary evolves.

Relation to vault concepts

  • Design Concept (Brooks) — ubiquitous language is the artifact form of the design concept: the shared invisible model made explicit as a document. Design concept is the phenomenon; ubiquitous language is the practice for pinning it down.
  • Context Engineering — ubiquitous language is a specific contextual substrate — the vocabulary layer. Prukalpa's data + semantics + skills framing at the enterprise scale; ubiquitous language operates at the codebase scale.
  • Deep Modules — module boundaries are named in the ubiquitous-language file; deep-module design and ubiquitous-language discipline reinforce each other.
  • Leading Words — Pocock's other steering technique. Leading words steer the agent's prior activation; ubiquitous language steers its vocabulary. Both are strategies for injecting shape into the agent's thinking without long imperative prompts.
  • Skill Checklist (Pocock) — his skills framework includes steering as a dimension; ubiquitous language is one of the concrete steering assets.
  • Verification Tax — shared vocabulary reduces verification cost by eliminating misinterpretation as a failure mode.

Cross-links

2026-09-26 — Worked example and payoff (AI Skills with Matt Pocock (The Pragmatic Engineer))

  • Motivation: agents are "awfully verbose" (Opus 5 singled out); a shared domain language is how you close the human↔agent communication barrier.
  • Worked example — the materialization cascade: in Pocock's course app, converting a ghost lesson inside a ghost section inside a ghost course into a real lesson must make the section and course real too. Naming that once lets him describe changes in a few words instead of a paragraph. The agent is good at coining such terms with you.
  • Skills: grill-with-docs ("terribly named") builds the domain language during the grilling session; a separate domain-modeling skill maintains it.
  • Codebase payoff: when the terms also appear in the code, the agent navigates by simple grep — "the difference is night and day."
  • Pocock recommends the first ~3 chapters of Evans's DDD specifically for ubiquitous language and domain modelling.

Source