ENSAYO · 13 DE OCTUBRE DE 2026

La arquitectura limpia del trabajo con agentes

Harold Maussa · Inspirado en The Clean Architecture de Robert C. Martin (2012)

Hace poco vi pasar algo que se repite en muchos equipos. Se construyó una función que, en teoría, estaba bien: el código funcionaba, las pruebas pasaban y la revisión la aprobó. Pero producto ya había decidido no hacerla, porque mantenerla a largo plazo era insostenible. Esa decisión existía: se tomó en una reunión y quedó escrita en una wiki que nadie revisa. Nadie la mencionó en el ticket ni la recordó en la revisión.

Nadie hizo nada mal. La decisión simplemente no estaba donde el trabajo ocurría.

Ahora imaginemos ese mismo cambio hecho por un agente. Lo habría escrito en una tarde, sin dudar, con pruebas y todo. Y tampoco habría sabido nada de esa reunión. La diferencia es que el agente no hace un cambio por semana: hace diez por día.

1. El problema: el agente escribe rápido, pero no sabe qué se decidió

En pocos meses cambió quién escribe el código. Hoy un agente como Claude Code puede leer un repositorio, entender lo que se le pide y entregar en una tarde lo que antes tomaba una semana. La velocidad dejó de ser el problema.

El problema ahora es otro: el agente no conoce el negocio. No sabe que la consulta gratis nunca debe mostrar el detalle de un embargo, porque ese detalle es lo que se vende. No sabe que se probó una suscripción y se descartó porque el comprador decide una sola vez. No sabe que hay una prohibición que, si se rompe, cuesta dinero en cada consulta. Esas cosas no están en el código. Están en un chat de hace tres meses, en una reunión, o en la cabeza de una persona.

Cuando el código lo escribía una persona del equipo, ese conocimiento viajaba con ella. Lo sabía porque estuvo en la reunión. El agente no estuvo en ninguna reunión. Cada conversación empieza de cero, y el dueño del producto termina repitiéndole lo mismo una y otra vez, o descubriendo en producción que el agente hizo algo razonable pero equivocado.

La respuesta habitual ha sido escribir más instrucciones: archivos de reglas, especificaciones por tarea, plantillas de prompts. Ayudan, pero tienen un defecto de fondo: nadie las aprobó. Son texto que alguien escribió en algún momento, que puede estar viejo, que se contradice con otro archivo, y que el agente trata como sugerencia. No tienen autoridad.

Este ensayo propone una forma de organizar el trabajo con agentes en la que lo decidido tiene autoridad, vive en un solo lugar y gobierna todo lo demás.

2. El origen: la regla de dependencia

En 2012, Robert C. Martin publicó The Clean Architecture, una idea que se volvió referencia en el diseño de software. La dibujó como anillos concéntricos. En el centro, las reglas del negocio. Hacia afuera, los casos de uso, los adaptadores y, en el borde, los detalles: la base de datos, la interfaz y los frameworks.

Lo importante no eran los anillos, sino una sola regla: las dependencias apuntan hacia adentro. El código de un anillo exterior puede conocer al de adentro, pero nunca al revés. Las reglas del negocio no saben nada de la base de datos. Así, lo que más importa y menos cambia queda protegido de lo que más cambia.

La pregunta de este ensayo es qué pasa si aplicamos esa regla ya no al código, sino al proceso de desarrollo. ¿Qué pasa si lo que ponemos en el centro no es el código, sino las reglas que el negocio aprobó?

3. El modelo

El modelo tiene un centro, tres anillos y una regla.

El centro: el mapa

En el centro está el mapa del producto: el conjunto de lo que el negocio decidió, con autoridad. No es una especificación de una tarea, ni un documento de arquitectura. Es el conocimiento permanente del producto, organizado por áreas y con entradas de tipos distintos:

• Reglas de negocio: lo que el negocio exige. «La imagen para vendedores solo se genera si el veredicto público es verde».
• Reglas técnicas: lo que la técnica exige. «Todo pago pasa por la pasarela».
• Prohibiciones: lo que nunca se hace. Para el agente son un alto: si lo que va a hacer rompe una, se detiene y avisa.
• Decisiones: una elección entre opciones, con su porqué, incluyendo lo que se probó y no funcionó.
• Flujos: el recorrido de una persona, paso a paso.
• Comportamientos esperados: ejemplos concretos de lo que debe pasar, que luego se vuelven pruebas.

Cada entrada lleva su porqué, obligatorio, porque sin él el agente no sabe cuándo aplica. Y cada entrada tiene versiones: nada se borra, se retira, y se puede ver el mapa como estaba en cualquier fecha.

Lo que hace distinto a este centro es cómo se cambia. Nadie edita una regla vigente directamente, ni las personas ni los agentes. Todo cambio llega como propuesta y pasa a vigente cuando lo aprueba la persona correcta según el tipo de regla: una regla de negocio la aprueba quien es dueño del producto; una regla técnica, quien desarrolla.

El primer anillo: las intenciones

Alrededor del mapa están las intenciones. Una intención reemplaza al ticket, pero cuenta mucho más. Tiene:

• el qué y el porqué, en palabras de la persona;
• la apuesta: a qué resultado de negocio apunta y por qué se cree que lo moverá, con un valor medido de hoy y una meta;
• los cambios que propone al mapa;
• las pantallas esperadas, si el cambio toca algo visible;
• el plan.

La intención no se mide por haberse entregado, sino por si movió el número que prometía mover.

El segundo anillo: la construcción

En el siguiente anillo vive el agente. Construye: escribe el código, una prueba por cada comportamiento esperado, toma capturas de lo que construyó y las compara con las pantallas que se aprobaron, y entrega un reporte con cifras reales.

El tercer anillo: producción y medición

En el borde está lo que más cambia: el despliegue, los chequeos en vivo y la medición. ¿Se movió el número?

La regla: todo apunta hacia adentro

Como en la arquitectura de Martin, la regla es una sola: el código obedece al mapa, nunca al revés. Si el código y el mapa no coinciden, no se corrige ninguno de los dos en silencio. O el código incumple una regla vigente, y se abre una intención de arreglo, o el mapa está equivocado, y se propone cambiarlo. Decide una persona.

De adentro hacia afuera, los anillos van de lo que más dura a lo que más cambia. Una regla del negocio puede durar años. Una intención, semanas. Un despliegue, minutos.

4. Cada frontera tiene un contrato y una puerta

En la arquitectura limpia original, lo más útil es saber qué cruza cada frontera. Aquí pasa lo mismo, con una diferencia: cada frontera tiene una puerta, y solo la abre una persona.

Las puertas exigen solo lo que la intención necesita. Un cambio sin pantallas no pide capturas. Pero nada se salta en silencio: si un requisito no aplica, una persona lo autoriza con su motivo, y queda registrado. Un agente nunca puede autorizarlo.

5. Si algo no está en el mapa, el agente pregunta

El segundo ciclo del modelo es el que más lo diferencia de un sistema de reglas estático.

Cuando el agente encuentra un caso que el mapa no cubre, no adivina. Abre una pregunta, dirigida a la persona que corresponde, con opciones concretas y con lo que pasaría al elegir cada una. Mientras tanto, sigue con lo que no depende de la respuesta.

La persona responde, muchas veces con un toque. Y la respuesta no se pierde en un chat: se vuelve una regla propuesta, que pasa por su puerta y queda en el mapa.

Así, cada duda del agente es una oportunidad de que el negocio deje por escrito algo que antes solo vivía en una cabeza. El mapa crece con el uso, desde las preguntas reales.

6. El ciclo se cierra: lo medido vuelve al mapa

El tercer ciclo es el de la medición. Cuando una intención sale a producción, se mide el resultado contra la apuesta. Funcionó, no funcionó o se revirtió. Y lo aprendido vuelve al mapa como una decisión, con su porqué.

La próxima vez que alguien, persona o agente, quiera probar algo parecido, el mapa le dirá que ya se probó y qué pasó.

7. Los principios

1. Las reglas aprobadas están en el centro, y todo lo demás depende de ellas.
2. Todo apunta hacia adentro. El código obedece al mapa, nunca al revés.
3. El agente escribe; la persona aprueba.
4. Un agente nunca aprueba. Ni reglas, ni pantallas, ni la salida a producción. Si trabaja sin una persona presente, no aprueba nunca.
5. Nadie edita una regla vigente directamente. Todo cambio es una propuesta que pasa por su puerta.
6. Cada regla lleva su porqué. Sin porqué no se sabe cuándo aplica.
7. Cada frontera tiene un contrato y una puerta. Se sabe qué cruza y quién lo deja pasar.
8. El agente no adivina: pregunta, y la respuesta se vuelve regla.
9. El trabajo termina cuando se mide, no cuando se entrega.
10. Lo inferido no tiene autoridad. Lo que el agente deduce del código sirve para proponer, pero solo lo aprobado manda.

8. Lo que no es

No es una especificación por tarea. Herramientas recientes, como GitHub Spec Kit o Kiro, organizan el trabajo de un agente en fases (requisitos, diseño, tareas), con una persona que aprueba cada fase. Es un gran avance, y este modelo comparte con ellas la puerta humana. La diferencia está en qué se aprueba: una especificación vive y muere con su tarea; el mapa es el conocimiento permanente del producto, que gobierna todas las tareas y crece con cada una.

No es un archivo de reglas. Los archivos de instrucciones para agentes son útiles, pero nadie los aprueba, se quedan viejos y no distinguen una preferencia de una prohibición. En el mapa, cada entrada tiene tipo, dueño, versión y la firma de quien la aprobó.

No es Jira con inteligencia artificial. No hay puntos, ni sprints, ni tickets que se cierran sin que nadie vuelva a mirar. Lo que va primero se decide por cuánto mueve un resultado de negocio.

No saca a la persona del camino. Muchos sistemas de agentes buscan que la persona intervenga lo menos posible. Este modelo pone a la persona en el centro: define el qué y el porqué, y aprueba lo que define el negocio. El agente ejecuta dentro de esos límites, a toda velocidad.

9. Los límites

Un modelo honesto tiene que decir dónde puede fallar.

La fricción de aprobar. Si cada cambio necesita una firma, aprobar puede volverse una carga. La respuesta del modelo es que solo se aprueba lo que define el negocio; el avance lo registra el agente sin frenar a nadie. Pero esto hay que medirlo: cuántas aprobaciones hay por semana y cuánto esperan.

El agente puede olvidar. Las reglas y las instrucciones son, al final, texto que el agente lee. En un trabajo largo puede olvidarse de registrar un avance o de consultar el mapa. Por eso no basta con instrucciones: hacen falta avisos en momentos fijos, como al crear una rama o al abrir un Pull Request, que le recuerden lo que toca, justo cuando toca.

El mapa puede quedarse corto. El mapa solo sabe lo que alguien aprobó. El ciclo de preguntas lo hace crecer, pero al principio estará incompleto, y el agente preguntará mucho.

Inferir o aprobar. Hay quienes sostienen que el contexto se debe inferir del código y de la historia, porque los documentos se quedan viejos. Es una crítica seria. La respuesta de este modelo es que lo inferido no tiene autoridad, y que el ciclo de preguntas evita que el mapa envejezca. Pero la prueba no es el argumento: es medir si, después de unas semanas, el agente deja de hacer cosas que el negocio no espera.

10. Un caso real

El modelo no es teórico: lo estamos usando en PlacaSegura, un producto que revisa el historial de un vehículo antes de comprarlo.

El dueño escribió, en palabras simples: «La sección Cómo funciona está muy triste y sin relevancia». A partir de esa frase, el agente:

1. Consultó el mapa de las áreas que tocaba el cambio y respetó sus reglas, entre ellas la prohibición de mostrar en lo gratis el detalle que se vende.
2. Armó la intención: rehacer la sección como un recorrido de tres pasos con piezas reales del producto, con la apuesta de que, si el visitante ve qué recibe gratis y qué desbloquea al pagar, más gente se anima a hacer la consulta gratis. Midió el valor de hoy (4,1 % de las visitas a la portada) y propuso una meta (5 % en 28 días, sin bajar las compras).
3. Cargó las pantallas esperadas, en celular y en computador, y una especificación, para que el dueño las aprobara antes de escribir código.
4. Propuso un comportamiento esperado nuevo para el mapa, que después se volvió prueba.
5. Construyó, registró cada paso del plan, comparó las capturas con las pantallas aprobadas y entregó un reporte de construcción.
6. Desplegó, con su reporte de chequeos, y la intención pasó a medición.

Hoy esa intención está esperando su plazo para saber si el número se movió.

El caso también mostró los límites. En la primera prueba, el agente construyó y entregó sin registrar nada del avance: las instrucciones estaban ahí, pero las olvidó. La corrección fue la del apartado anterior: avisos en momentos fijos que le recuerdan qué registrar. En otra, el agente subió una maqueta que no se veía bien fuera del proyecto, y el sistema aprendió a rechazar ese tipo de maqueta con un mensaje que le dice qué falta. Cada falla terminó en una regla nueva o en una corrección del sistema. Eso es, en pequeño, el modelo funcionando sobre sí mismo.

11. Cierre

Cuando el código lo escribe un agente, escribir deja de ser lo difícil. Lo difícil es decidir bien qué se construye, saber qué se decidió antes, y comprobar si sirvió.

No necesitamos un Jira más rápido. Necesitamos un lugar donde lo decidido tenga autoridad, donde el agente pregunte en vez de adivinar, y donde el trabajo termine cuando se mide.

La arquitectura limpia nos enseñó a proteger las reglas del negocio de los detalles que cambian. En la era de los agentes, la lección es la misma, un nivel más arriba: proteger lo que el negocio decidió de la velocidad con que hoy se escribe el código.

El agente escribe. La persona aprueba. Un agente nunca aprueba.

Este modelo se está construyendo como plataforma en Daidara.