---
name: domain-driven-design
description: This skill should be used when designing software architecture, modeling domains, reviewing code for DDD compliance, identifying bounded contexts, designing aggregates, or discussing strategic and tactical DDD patterns. Provides comprehensive Domain-Driven Design principles, axioms, heuristics, and anti-patterns for building maintainable, domain-centric software systems.
---

# Domain-Driven Design

## Overview

Domain-Driven Design (DDD) is an approach to software development that centers the design on the core business domain. This skill provides principles, patterns, and heuristics for both strategic design (system boundaries and relationships) and tactical design (code-level patterns).

## When to Apply This Skill

- Designing new systems or features with complex business logic
- Identifying and defining bounded contexts
- Modeling aggregates, entities, and value objects
- Reviewing code for DDD pattern compliance
- Decomposing monoliths into services
- Establishing ubiquitous language with domain experts

## Core Axioms

### Axiom 1: The Domain is Supreme

Software exists to solve domain problems. Technical decisions serve the domain, not vice versa. When technical elegance conflicts with domain clarity, domain clarity wins.

### Axiom 2: Language Creates Reality

The ubiquitous language shapes how teams think about the domain. Ambiguous language creates ambiguous software. Invest heavily in precise terminology.

### Axiom 3: Boundaries Enable Autonomy

Explicit boundaries (bounded contexts) allow teams to evolve independently. The cost of integration is worth the benefit of isolation.

### Axiom 4: Models are Imperfect Approximations

No model captures all domain complexity. Accept that models simplify reality. Refine models continuously as understanding deepens.

## Strategic Design Quick Reference

| Pattern | Purpose | Key Heuristic |
|---------|---------|---------------|
| **Bounded Context** | Define linguistic/model boundaries | One team, one language, one model |
| **Context Map** | Document context relationships | Make implicit integrations explicit |
| **Subdomain** | Classify domain areas by value | Core (invest), Supporting (adequate), Generic (outsource) |
| **Ubiquitous Language** | Shared vocabulary | If experts don't use the term, neither should code |

For detailed strategic patterns, consult `references/strategic-patterns.md`.

## Tactical Design Quick Reference

| Pattern | Purpose | Key Heuristic |
|---------|---------|---------------|
| **Entity** | Identity-tracked object | "Same identity = same thing" regardless of attributes |
| **Value Object** | Immutable, identity-less | Equality by value, always immutable, self-validating |
| **Aggregate** | Consistency boundary | Small aggregates, reference by ID, one transaction = one aggregate |
| **Domain Event** | Record state changes | Past tense naming, immutable, contains all relevant data |
| **Repository** | Collection abstraction | One per aggregate root, domain-focused interface |
| **Domain Service** | Stateless operations | When logic doesn't belong to any single entity |
| **Factory** | Complex object creation | When construction logic is complex or variable |

For detailed tactical patterns, consult `references/tactical-patterns.md`.

## Essential Heuristics

### Aggregate Design Heuristics

1. **Protect business invariants inside aggregate boundaries** - If two pieces of data must be consistent, they belong in the same aggregate
2. **Design small aggregates** - Large aggregates cause concurrency issues and slow performance
3. **Reference other aggregates by identity only** - Never hold direct object references across aggregate boundaries
4. **Update one aggregate per transaction** - Eventual consistency across aggregates using domain events
5. **Aggregate roots are the only entry point** - External code never reaches inside to manipulate child entities

### Bounded Context Heuristics

1. **Linguistic boundaries** - When the same word means different things, you have different contexts
2. **Team boundaries** - One context per team enables autonomy
3. **Process boundaries** - Different business processes often indicate different contexts
4. **Data ownership** - Each context owns its data; no shared databases

### Modeling Heuristics

1. **Nouns → Entities or Value Objects** - Things with identity become entities; descriptive things become value objects
2. **Verbs → Domain Services or Methods** - Actions become methods on entities or stateless services
3. **Business rules → Invariants** - Rules the domain must always satisfy become aggregate invariants
4. **Events in domain expert language → Domain Events** - "When X happens" becomes a domain event

## Decision Guides

### Entity vs Value Object

```
Does this thing have a lifecycle and identity that matters?
├─ YES → Is identity based on an ID (not attributes)?
│        ├─ YES → Entity
│        └─ NO  → Reconsider; might be Value Object with natural key
└─ NO  → Value Object
```

### Where Does This Logic Belong?

```
Is this logic stateless?
├─ NO  → Does it belong to a single aggregate?
│        ├─ YES → Method on the aggregate/entity
│        └─ NO  → Reconsider aggregate boundaries
└─ YES → Does it coordinate multiple aggregates?
         ├─ YES → Application Service
         └─ NO  → Does it represent a domain concept?
                  ├─ YES → Domain Service
                  └─ NO  → Infrastructure Service
```

### Should This Be a Separate Bounded Context?

```
Do different stakeholders use different language for this?
├─ YES → Separate bounded context
└─ NO  → Does a different team own this?
         ├─ YES → Separate bounded context
         └─ NO  → Would a separate model reduce complexity?
                  ├─ YES → Consider separation (but weigh integration cost)
                  └─ NO  → Keep in current context
```

## Anti-Patterns Overview

| Anti-Pattern | Description | Fix |
|--------------|-------------|-----|
| **Anemic Domain Model** | Entities with only getters/setters | Move behavior into domain objects |
| **Big Ball of Mud** | No clear boundaries | Identify bounded contexts |
| **Smart UI** | Business logic in presentation layer | Extract domain layer |
| **Database-Driven Design** | Model follows database schema | Model follows domain, map to database |
| **Leaky Abstractions** | Infrastructure concerns in domain | Dependency inversion, ports and adapters |
| **God Aggregate** | One aggregate does everything | Split by invariant boundaries |
| **Premature Abstraction** | Abstracting before understanding | Concrete first, abstract when patterns emerge |

For detailed anti-patterns and remediation, consult `references/anti-patterns.md`.

## Implementation Checklist

When implementing DDD in a codebase:

- [ ] Ubiquitous language documented and used consistently in code
- [ ] Bounded contexts identified with clear boundaries
- [ ] Context map documenting integration patterns
- [ ] Aggregates designed small with clear invariants
- [ ] Entities have behavior, not just data
- [ ] Value objects are immutable and self-validating
- [ ] Domain events capture important state changes
- [ ] Repositories abstract persistence for aggregate roots
- [ ] No business logic in application services (orchestration only)
- [ ] No infrastructure concerns in domain layer

## Resources

### references/

- `strategic-patterns.md` - Detailed strategic DDD patterns including bounded contexts, context maps, subdomain classification, and ubiquitous language
- `tactical-patterns.md` - Detailed tactical DDD patterns including entities, value objects, aggregates, domain events, repositories, and services
- `anti-patterns.md` - Common DDD anti-patterns, how to identify them, and remediation strategies

To search references for specific topics:
- Bounded contexts: `grep -i "bounded context" references/`
- Aggregate design: `grep -i "aggregate" references/`
- Value objects: `grep -i "value object" references/`
