Cinco niveles de inmersión en un sistema complejo

Cuando todos los niveles de contexto se mezclan

¿Qué te impide ver la visión general cuando cada detalle está disponible a la vez?

Un repositorio ordinario no separa la información por escala: áreas de negocio, operaciones, modelos de datos, orden de llamadas, infraestructura y líneas de código individuales se presentan todas a la vez. La memoria de trabajo tiene que retener hechos de distintos niveles y reconstruir por sí sola las relaciones entre ellos. La atención cambia constantemente entre la estructura del sistema y los detalles locales, de modo que la comprensión se desmorona rápidamente tras una pausa.

Primero, un mapa de responsabilidades

¿Dónde vive la responsabilidad?

El primer pilar es un mapa de responsabilidad. Reúne controladores, servicios, modelos de datos, adaptadores de infraestructura y cadenas de llamadas en torno a las grandes áreas del sistema — un armazón al que después se pueden vincular operaciones, datos y código.

Los dominios dividen el sistema por áreas estables de responsabilidad, no por capas técnicas: pedidos, pagos, comunicación y analítica. En lugar de cientos de archivos aparentemente equivalentes aparece una primera topología comprensible.

El mapa se convierte en un catálogo de capacidades.

¿Qué puede hacer el sistema?

El mapa de dominios muestra dónde reside la responsabilidad, pero aún no dice qué puede hacer el sistema. Para responder a eso, cada dominio se abre en un catálogo de Action, capacidades con nombre que proporciona al resto del sistema.

Un Action es una capacidad pública y nombrada de un dominio. El catálogo no muestra funciones internas, sino las operaciones que un dominio ofrece al resto del sistema, junto con las relaciones dirigidas entre ellas. Cada Action se convierte en un único punto de invocación: quien lo invoca elige por significado la capacidad que necesita, en lugar de ensamblar la operación a partir de métodos separados.

Fijamos la frontera de la operación

¿Qué requiere y promete la operación?

La capacidad ya tiene un nombre y un lugar en el sistema. Para usarlo como caja negra, necesitamos saber exactamente qué datos acepta y qué resultado promete devolver.

Un Contract hace que el límite Action sea tipificado y no sea ambiguo. Params describe todo lo que acepta la operación; Result describe todo lo que debe devolver. El código de llamada depende de esa promesa, no de la forma interna del Action. La implementación puede cambiar siempre que la entrada, la salida y el comportamiento observable sigan siendo compatibles.

Desplegamos la operación como escenario

¿Cómo se desarrolla el escenario?

El contrato fija el principio y el fin de una operación, pero no muestra cómo uno se convierte en el otro. Para ver eso, desplegamos el flujo interno del escenario empresarial.

Un Pipeline hace que el escenario principal del negocio sea lineal y visible: validar la entrada, reservar inventario, cobrar el pago y ensamblar el resultado. Eso no quiere decir que no existan errores, ramificaciones y compensaciones; reciben un lugar explícito en relación con la línea principal. Cada paso también tiene un contrato local: declara lo que lee de Params, State y Context, y lo que agrega a State para etapas posteriores.

Sólo ahora, el comportamiento concreto

¿Dónde vive el comportamiento concreto?

El Pipeline localiza el comportamiento requerido con precisión y reduce drásticamente el área de búsqueda. Ahora podemos abrir no todo el repositorio o incluso todo el Action, sino un paso cuyo propósito, entrada y salida ya conocemos.

Code es el quinto nivel no porque los detalles no sean importantes, sino porque ahora están rodeados de significado. Sabemos qué dominio posee el comportamiento, qué capacidad implementa Action, qué promete Contract y dónde se ubica reserve_inventory en Pipeline. La implementación se lee como una respuesta local a una tarea concreta en lugar de una entrada a una investigación interminable del repositorio.

@regular_aspect("Reserve inventory")@result_string("reservation_id", required=True)@context_requires("user.tenant_id", "env.inventory_region")async def reserve_inventory_aspect(    self, params, state, box, connections, ctx):    inventory = box.resolve(InventoryResource)    reservation_id = await inventory.reserve(        tenant_id=ctx.get("user.tenant_id"),        region=ctx.get("env.inventory_region"),        items=state["validated_items"],    )    return {"reservation_id": reservation_id}

Los cinco niveles no ocultan el código ni reducen el sistema a un diagrama. Conservan el recorrido desde el modelo general hasta un detalle concreto. Quien acaba de llegar construye el contexto de forma progresiva; el arquitecto gestiona la gramática y las fronteras en lugar de cada archivo; y el agente de IA realiza trabajo local dentro de reglas declaradas: las personas diseñan el lenguaje del sistema y la máquina actúa en ese lenguaje.