Solving AI Agent Ambiguity with Domain-Driven Design's Ubiquitous Language

Ubiquitous Language: DDD’s pattern for shared vocabulary

AI coding agents act as confident amplifiers of the vocabulary provided by engineers. Without precise definitions, these agents generate plausible but semantically incorrect code that bypasses traditional human friction points like code reviews.

Why This Matters

Traditional development relies on human interaction—pair programming and whiteboard sessions—to resolve ambiguity. AI agents remove this friction; they do not ask for clarification and will confidently implement an incorrect interpretation of a term. This creates a technical reality where code compiles and tests pass, but the system fails in production because the agent mashed distinct domain concepts (e.g., booking vs. reservation) into a single implementation.

Key Insights

• Ubiquitous Language is a pattern introduced by Eric Evans in 2003 to build a common, rigorous language between developers and domain experts.
• Bounded Contexts dictate that there is one Ubiquitous Language per context; for example, a ‘Customer’ may be a ‘Lead’ in marketing but a ‘Debtor’ in finance.
• The ‘Spec Ambiguity Resolver’ pattern, proposed by Daniel Schleicher, uses a living glossary where AI flags ambiguous terms for human approval before implementation.
• MCP tool naming acts as a vocabulary decision; using confirm_purchase_intent() versus submit_order() alters agent behavior even if the underlying operation is identical.

Working Examples

Example of domain-specific language definitions for a fulfillment module in CLAUDE.md.

## Fulfillment Domain Language
**Consignee**:
The person or entity receiving a shipment. Identified by delivery
address, contact phone, and access instructions. A consignee may
differ from the purchaser.
*Avoid*: Customer, Buyer, User
**Consignment**:
The full set of items to be delivered to a consignee. May be
fulfilled as one or more Shipments depending on stock location
and logistics.
*Avoid*: Order, Delivery (a delivery is one shipment arriving,
not the full set)
**Shipment**:
A physical package dispatched to a consignee via a carrier. Has
tracking number, weight, dimensions, and a declared value.
*Avoid*: Order, Package (ambiguous with code packages)
**Dispatch**:
The act of handing a shipment to a carrier. Irreversible - once
dispatched, the shipment is the carrier's responsibility.
*Avoid*: Send, Ship (verb), Process

Example of domain-specific language definitions for a billing module in CLAUDE.md.

## Billing Domain Language
**Debtor**:
The legal entity liable for payment. Identified by tax ID, billing
address, and agreed payment terms (net-30, net-60, etc.).
*Avoid*: Customer, Account, User
**Invoice**:
A legal demand for payment tied to one or more line items. Carries
a due date, VAT status, and regulatory classification. An invoice
is never deleted - it is reversed with a **Credit Note**.
*Avoid*: Order, Bill (ambiguous with infrastructure billing)
**Settlement**:
The act of a debtor satisfying an invoice in full or in part.
Records payment method, date, and reconciliation reference.
*Avoid*: Payment (ambiguous - is it the act or the money?),
Transaction

Practical Applications

• • Use Case: Using CLAUDE.md, AGENT.md, or domain-terms.md files to provide canonical glossaries that agents reference during every session.
• Pitfall: Flattening distinct domain entities into generic classes (e.g., using Customer with a type field), which erases precision and leads to generic ambiguity.
• • Use Case: Implementing Matt Pocock’s glossary skill to scan codebases and extract terminology into markdown for agent context.
• Pitfall: Applying one universal language across all modules instead of maintaining separate vocabularies per Bounded Context.

References:

• https://dev.to/aws/your-agent-keeps-using-that-word—4g36