🎯

domain-driven-design

🎯Skill
g1joshi/agent-skills1 InstallsAdded Feb 10, 2026

Installation

$npx skills add g1joshi/agent-skills --skill domain-driven-design

Run it in a terminal; it asks which AI coding tools to install it for (Claude Code, Codex, Cursor and more).

Uses skills.sh Β· Node.js 22.20+

After installing

Ask for related work and the agent uses it on its own, or call it yourself.

Run it (Claude Code)/domain-driven-design
Install by hand

Copy the whole skill folder from GitHub to the place below. Copying only SKILL.md can leave out files the skill uses.

Open the skill folder β†’
  • This project .claude/skills/domain-driven-design/
  • All projects ~/.claude/skills/domain-driven-design/

These paths are for Claude Code. For other tools, the command above puts it in the right place.

Expert Domain-Driven Design (DDD) assistance covering strategic bounded contexts, ubiquitous language, aggregates, value objects, domain events, and repository patterns. Use when modeling complex business domains, decomposing monoliths into microservices, or implementing rich domain models.

Domain-Driven Design (DDD)

DDD is a software design approach focusing on modeling software to match a domain according to input from that domain's experts. It is essential for tackling high complexity in the heart of software.

When to Use

  • Complex Business Domains: Healthcare, fintech, logistics, and enterprise systems with intricate operational rules and workflows.
  • Monolith Decomposition: Establishing well-defined Bounded Contexts as boundaries for microservices or modular monoliths.
  • Cross-Functional Team Alignment: Creating a shared Ubiquitous Language between domain experts and software engineers.
  • High-Change Core Software: Managing business logic that evolves rapidly without introducing unexpected regressions.

Quick Start

// Aggregate Root
public class Order {
    private OrderId id;
    private Money totalAmount;
    private OrderStatus status;
    private List<OrderItem> items; // Aggregates items

    // Behaviors (Rich Model), not just Getters/Setters
    public void addItem(Product product, int quantity) {
        if (this.status != OrderStatus.DRAFT) {
            throw new DomainException("Cannot modify confirmed order");
        }
        this.items.add(new OrderItem(product, quantity));
        recalculateTotal();
    }

    public void confirm() {
        if (items.isEmpty()) throw new DomainException("Order empty");
        this.status = OrderStatus.CONFIRMED;
        // Raise Domain Event
        DomainEvents.publish(new OrderConfirmed(this.id));
    }
}

Core Concepts

Strategic DDD: Bounded Contexts & Context Mapping

Divides a large organization into autonomous boundaries with distinct terminology and models:

[ Sales Context ] ──(Customer = Buyer)──→ [ Context Map ] ──(Customer = Borrower)──→ [ Underwriting Context ]

Value Objects vs Entities

Entities possess a persistent identity that endures across mutations; Value Objects are immutable and defined entirely by their attributes:

// domain/value-objects/money.vo.ts
export class Money {
  constructor(
    public readonly amount: number,
    public readonly currency: "USD" | "EUR" | "GBP",
  ) {
    if (amount < 0) throw new Error("Amount cannot be negative");
    Object.freeze(this);
  }

  public add(other: Money): Money {
    if (this.currency !== other.currency) throw new Error("Currency mismatch");
    return new Money(this.amount + other.amount, this.currency);
  }

  public equals(other: Money): boolean {
    return this.amount === other.amount && this.currency === other.currency;
  }
}

Aggregate Roots & Transaction Boundaries

The Aggregate Root is the sole gateway through which external callers can interact with inner entities:

// domain/aggregates/invoice.ts
export class Invoice {
  private readonly lineItems: InvoiceLineItem[] = [];

  constructor(
    public readonly id: string,
    public readonly customerId: string,
  ) {}

  public addLineItem(description: string, price: Money): void {
    if (this.lineItems.length >= 100)
      throw new Error("Maximum line items exceeded");
    this.lineItems.push(
      new InvoiceLineItem(crypto.randomUUID(), description, price),
    );
  }

  get total(): Money {
    return this.lineItems.reduce(
      (sum, item) => sum.add(item.price),
      new Money(0, "USD"),
    );
  }
}

Common Patterns

Aggregate Root with Encapsulated Business Invariants

Problem: Direct mutation of entity state bypasses business rules and produces inconsistent data.
Solution: Protect invariants inside Aggregate Roots and emit Domain Events.

// domain/aggregates/bank-account.ts
export class BankAccount {
  private _balance: number = 0;
  private readonly _domainEvents: any[] = [];

  constructor(
    public readonly id: string,
    initialDeposit: number,
  ) {
    if (initialDeposit < 25) throw new Error("Minimum opening balance is $25");
    this._balance = initialDeposit;
  }

  public withdraw(amount: number): void {
    if (amount <= 0) throw new Error("Withdrawal amount must be positive");
    if (this._balance - amount < 0) throw new Error("Insufficient funds");
    this._balance -= amount;
    this._domainEvents.push({
      type: "FUNDS_WITHDRAWN",
      accountId: this.id,
      amount,
    });
  }

  get balance(): number {
    return this._balance;
  }
  pullDomainEvents(): any[] {
    return this._domainEvents.splice(0);
  }
}

Best Practices

Do:

  • Co-Design with Domain Experts: Conduct Event Storming workshops to map domain workflows before writing code.
  • Enforce Invariants Inside the Aggregate: Ensure invalid state can never exist within an entity or aggregate root.
  • Reference Other Aggregates by ID Only: Never hold direct object references to other aggregate roots; use their unique IDs.
  • Make Value Objects Immutable: Guarantee side-effect free equality checks and safe passing across concurrent threads.

Don't:

  • Create massive aggregates: Keep aggregates small; large aggregates cause database lock contention and performance bottlenecks.
  • Let technical database concerns leak into Domain logic: Design domain models for business behavior, not database normalization.
  • Use DDD for generic CRUD contexts: Reserve DDD tactical patterns for the Core Domain where competitive advantage lies.

Troubleshooting

ErrorCauseSolution
God ClassAggregate knowing too much.Split Aggregates; use Domain Events to coordinate.
PerformanceLoading huge Aggregates.Lazy load is tricky; prefer smaller Aggregates tailored to invariants.

References

More from this repository10