DDD en la era agéntica: tu código es el contexto

April 20, 2026

Cuando los equipos empiezan a trabajar con agentes de IA, el primer error que cometen es obsesionarse con el prompt. Creen que si encuentran la instrucción correcta, el agente va a producir el resultado correcto.

El prompt importa. Pero no es lo más importante.

Lo más importante es el codebase que el agente tiene que leer para generar su respuesta.

Qué lee realmente un agente

Cuando le pedís a un agente que implemente una feature, refactorice un módulo o escriba tests, el agente no trabaja solo con lo que escribís en el chat. Trabaja con todo lo que puede leer:

Cada uno de esos elementos es contexto. Los nombres de las funciones, la estructura de carpetas, los tipos TypeScript, los archivos de configuración — todo eso es input que el agente consume antes de escribir una sola línea.

Un prompt perfecto sobre un codebase caótico produce output caótico.

El codebase caótico: el peor input que le podés dar

Imaginá una carpeta utils/ con 40 archivos. Funciones que se llaman handleData(), processInfo(), doStuff(). Tipos any por todos lados. Clases que se llaman Manager y hacen tres cosas distintas.

1export function handleData(data: any) {
2  const result = processInfo(data)
3  doStuff(result)
4  return result
5}

El agente puede trabajar con esto. Pero va a aprender del estilo existente y producir más de lo mismo. No porque el agente sea malo — sino porque el codebase no le comunica nada útil sobre el dominio.

El agente infiere convenciones del código que lee. Si el código no tiene convenciones claras, el agente inventa las suyas. Y cada output va a ser diferente porque no hay nada consistente de donde derivar coherencia.

DDD como lenguaje compartido entre el equipo y el agente

Domain-Driven Design no es un patrón de arquitectura. Es una filosofía de comunicación.

La idea central: el código debería hablar el mismo idioma que el negocio. Si el negocio habla de Orders, Customers y Payments, el código también debería hablar de Orders, Customers y Payments.

Cuando el modelo de dominio es claro, el agente lo entiende sin adivinar:

1export class Order {
2  constructor(
3    private readonly id: OrderId,
4    private readonly customerId: CustomerId,
5    private items: OrderItem[],
6    private status: OrderStatus,
7  ) {}
8
9  addItem(item: OrderItem): void {
10    if (this.status !== OrderStatus.DRAFT) {
11      throw new OrderNotEditableError(this.id)
12    }
13    this.items.push(item)
14  }
15
16  submit(): void {
17    if (this.items.length === 0) {
18      throw new EmptyOrderError(this.id)
19    }
20    this.status = OrderStatus.SUBMITTED
21  }
22}

Order es un agregado. OrderId es un value object. OrderStatus tiene estados bien definidos con nombres que explican su propósito. OrderNotEditableError le dice exactamente al agente cuándo lanzar esa excepción y por qué.

El agente no necesita adivinar nada. Tiene suficiente contexto para tomar decisiones correctas porque cada nombre comunica intención.

La diferencia entre los dos codebases no es solo estética. Es la calidad del contexto que le das al agente. Un codebase con capas bien definidas le permite razonar sobre responsabilidades, bordes de módulo y efectos colaterales — porque esa información está codificada en la estructura misma.

Tu CLAUDE.md es un documento de dominio, no un README

Hay una capa de contexto que va más allá del código: la documentación estructurada que le dás al agente de forma explícita.

En Claude Code, ese archivo es CLAUDE.md. En Cursor, son las reglas del proyecto. En cualquier herramienta agéntica, hay algún mecanismo para instrucciones persistentes.

La mayoría lo usa como un README glorificado. Pero si lo pensás como un documento de dominio, cambia completamente lo que escribís:

1## Domain Model
2
3**Order**: Purchase intent. Starts in DRAFT, cannot be
4edited after SUBMITTED.
5
6**OrderItem**: Single product line. Price in cents (integer),
7never floats for currency.
8
9**Business rules**:
10
11- At least one item required before submission.
12- Discounts at Order level, not per item.
13- Cancellation only before PROCESSING status.

Eso no es documentación para el equipo. Es contexto que el agente va a consumir antes de tomar cualquier decisión técnica. Cuanto más preciso sea el lenguaje del dominio ahí, más precisas van a ser las decisiones del agente.

Los equipos que van a sacar ventaja

La IA no va a reemplazar a los developers que escriben buen código. Va a amplificar a los que ya saben lo que hacen.

Un codebase bien modelado, con un dominio claro, tipos explícitos y convenciones consistentes va a producir outputs de agente radicalmente mejores que un codebase caótico — sin importar cuánto tiempo inviertas en pulir el prompt.

La diferencia entre un equipo que usa IA con frustración y uno que la usa con fluidez no está en qué herramienta eligen. Está en la calidad del contexto que le dan.

Y eso, a fin de cuentas, es exactamente lo mismo que siempre distinguió a un buen equipo de uno mediocre.