Enfoques

Cuando le pedís algo a un agente, en el momento del pedido vos sabés qué querías. El problema aparece dos semanas después, cuando mirás el código y no podés distinguir entre “el agente hizo otra cosa” y “yo pedí eso”. Sin un artefacto escrito antes, no hay forma de saberlo: tu recuerdo del pedido se contaminó con el resultado.

El spec resuelve eso siendo anterior e independiente. No describe la implementación —eso es el diseño— sino el comportamiento observable: qué tiene que pasar, con qué entradas, y cómo se comprueba. Escrito así, cualquiera puede verificar el resultado sin haber estado en la conversación. Incluido vos, en dos semanas.

Hay un efecto secundario que vale más que el original: si no podés escribir cómo vas a comprobar que está bien, todavía no sabés qué estás pidiendo. La mitad de las tareas que “el agente hizo mal” eran tareas mal formuladas, y la especificación las hace fallar antes de gastar un token.

El ciclo por fases —explorar, proponer, especificar, diseñar, tareas, aplicar, verificar, archivar— existe por un motivo mecánico, no ceremonial: cada fase necesita contexto distinto y tiene criterio de terminado distinto. Mezclarlas en un solo pedido es pedirle a la misma persona que diseñe, construya e inspeccione al mismo tiempo. Va a aprobar su propio trabajo.

Y ojo con el otro extremo. Un spec de tres páginas para un cambio de dos líneas no es rigor, es teatro. La ceremonia tiene un costo fijo y hay que pagarlo solo cuando el cambio lo justifica.

La idea que sobrevive a las herramientas

Si no podés escribir cómo vas a comprobar que está bien, todavía no sabés qué estás pidiendo.

El motivo es mecánico y no tiene nada que ver con la disciplina moral. Si pedís los tests después de escribir el código, el agente escribe tests que pasan. Es literalmente lo que le pediste, y lo va a hacer bien. El resultado es una suite verde que no probó nada, porque ningún test de esa suite tuvo jamás la oportunidad de fallar.

Por eso el paso que la gente saltea —ver el test en rojo— no es una formalidad. Sobre comportamiento que todavía no existe es todo el mecanismo: el rojo es la prueba de que el test puede detectar la ausencia de lo que testea. Que pase en la primera corrida te dice que el test corre, que es otra afirmación y bastante menos útil. La regla es más angosta que el eslogan, igual. Un test de caracterización que cerca comportamiento que ya está en producción tiene que pasar de una: no está probando algo nuevo, está fijando algo viejo.

Con un agente aparece además un modo de falla propio: mockea lo que estabas probando. Si el test de la función de cobro mockea la función de cobro, pasa siempre y no cubre nada. Suena a chiste hasta que lo ves en un PR. La defensa es leer qué mockea el test, no cuántos tests hay.

Y hay un beneficio de segundo orden que en equipos importa más que el primero: el test escrito antes es una especificación ejecutable. No puede desviarse del código —el día que los dos no coinciden, el build lo dice—. Sí puede desviarse de lo que vos querías, y por eso existen el spec y el registro: el test no los reemplaza.

La idea que sobrevive a las herramientas

Sobre comportamiento nuevo, un test que nunca viste fallar no es un test: es una opinión escrita en verde.

Arranquemos por el problema real, que no es la calidad de la revisión sino su repetición. Revisás un cambio. Después viene el commit, el push, el PR, el release. En cada uno de esos puntos alguien —o algún agente— vuelve a preguntar “¿esto está revisado?”. Sin una respuesta verificable, la única salida honesta es revisar otra vez. Y revisar otra vez con un agente cuesta plata y tiempo, cada vez.

El comprobante corta eso. La revisión ocurre una sola vez, sobre un objetivo inmutable: el árbol exacto, los archivos exactos, los modos exactos. Lo que queda es un comprobante atado a ese contenido. Los puntos siguientes no revisan: validan. Y si el contenido cambió aunque sea un byte, el comprobante no aplica — que es justamente lo que querés que pase.

Eso resuelve además el problema de que la revisión no termina. Un agente al que le pedís “revisá esto” sigue produciendo una cosa más mientras le sigas preguntando; sin un límite declarado, la revisión se corta cuando te cansaste, que no es un criterio. Acá el presupuesto de corrección se fija al abrir la revisión, en función del tamaño del cambio, y no se renegocia después. Lo que aparece más tarde es trabajo nuevo, no una prórroga.

La otra mitad es la proporcionalidad. Un cambio de documentación no merece el mismo análisis que uno que toca permisos o pagos. El riesgo del cambio decide cuánto análisis se corre: nada para lo trivial, un enfoque para lo normal, el barrido completo para lo peligroso. Elegir eso a mano, cambio por cambio, es exactamente el tipo de decisión que la gente deja de tomar a la tercera semana.

Y una advertencia, porque el patrón se puede degradar rápido: un comprobante que no se puede invalidar es un sello de goma. Todo el valor está en que sea frágil ante el cambio de contenido. Si tu proceso lo mantiene válido “porque total es lo mismo”, dejaste de tener control y pasaste a tener papeleo.

La idea que sobrevive a las herramientas

Una revisión sin comprobante hay que repetirla; un comprobante que no se puede invalidar no es una revisión.

El código te dice qué se decidió. No te dice qué más había sobre la mesa, ni por qué eso se descartó, ni qué estabas aceptando pagar a cambio. Esa parte nunca estuvo en el repositorio: estaba en una conversación, en un hilo de Slack, o en la cabeza de alguien que hoy trabaja en otro lado.

Con un agente el problema cambia de escala. Un compañero humano que no entiende una decisión pregunta. El agente no pregunta: completa. Ve un servicio que no usa el ORM del proyecto y lo “arregla”; ve dos módulos que no comparten un helper y los unifica. Cada una de esas correcciones es razonable si no sabés lo que el ADR sabía, y ninguna se va a marcar en la revisión, porque el diff se ve bien.

Lo que hace útil al registro no es la decisión que tomaste —esa está en el código— sino la lista de las que no. Un ADR sin alternativas descartadas es un comentario largo. Con ellas es lo único que puede cerrar una discusión sin volver a tenerla, y es el único formato que le podés dar a un agente para que no la reabra.

El costo es bajo y hay que decirlo: son quince líneas escritas el día que la discusión termina. La trampa no es el esfuerzo, es la disciplina de escribirlo mientras todavía sabés por qué. Una semana después ya reescribiste el recuerdo en función de cómo salió.

Y hay una convención que sostiene toda la práctica, y que la gente rompe enseguida: un ADR aceptado no se reescribe. Mientras está propuesto puede cambiar; una vez aceptado, escribís uno nuevo que lo reemplaza y el viejo queda marcado como reemplazado. Si lo editás para que diga lo que hoy es cierto, perdiste exactamente lo que fuiste a buscar — el hilo entre lo que se decidió y lo que quedó.

La idea que sobrevive a las herramientas

Una decisión que no quedó escrita no es una decisión: es una coincidencia que alguien va a deshacer.

El modo de falla acá no es código que no funciona. Es código que funciona y no era lo que hacía falta. Compila, los tests pasan, la revisión lo aprueba, y tres semanas después alguien del negocio mira la pantalla y dice que eso no es un descuento. Nadie lo agarró antes porque no había nada mal: había algo distinto.

De todo DDD, dos piezas cargan casi todo el peso cuando trabajás con agentes. La primera es una sola regla: una palabra, un significado, y la misma palabra en la conversación, en el spec, en el código y en los tests. Suena a poco hasta que ves lo que pasa cuando falta. En cada punto donde tenés que traducir, alguien traduce; y cuando el que traduce es un modelo, la traducción la saca del promedio de internet, no de tu negocio.

La segunda es aceptar que la misma palabra significa cosas distintas en lugares distintos, y que eso está bien. “Envío” en facturación es una línea con un precio; en logística es una caja con un peso. La respuesta de DDD no es elegir una: es marcar la frontera donde cambia el significado y hacerla explícita. Para un agente esa frontera es además un límite de lectura — le dice hasta dónde tiene que entender para no equivocarse, que es la misma pregunta que hace hexagonal desde el otro lado.

Ahora la parte honesta, porque DDD tiene fama de caro y se la ganó. Lo que acabo de describir —el vocabulario y las fronteras— es barato y rinde desde el primer día. Los patrones tácticos —agregados, objetos de valor, repositorios, eventos de dominio— son caros y la mayoría de los proyectos no los necesita. Son dos cosas distintas que vienen en el mismo libro.

Y ojo con pedírselos a un agente, porque los conoce y los aplica con entusiasmo. Un patrón con nombre propio es justo lo que un modelo reproduce mejor: pedile DDD sobre una tabla de seis columnas y te devuelve un agregado, un repositorio y una fábrica para guardar un nombre y un mail. Eso no es dominio modelado, es vocabulario de dominio aplicado a un CRUD.

La idea que sobrevive a las herramientas

El agente no construye lo que quisiste decir: construye lo que dicen tus palabras.

Un agente es correcto en proporción a lo que puede ver de una vez. Si para cambiar una regla de negocio hay que entender el ORM, el router y tres helpers compartidos, el agente necesita cargar todo eso, y en cuanto no entra, empieza a inventar. Un dominio aislado le da una superficie chica y bien delimitada. No es elegancia: es reducción de la cantidad de contexto necesaria para no equivocarse.

La otra mitad es el nombre de las cosas. Una estructura de carpetas que grita de qué se trata el negocio —cobros, reservas, envíos— le da al agente contexto gratis antes de abrir un solo archivo. Una que grita el framework le hace leer diez archivos para deducir lo mismo. Los nombres son la forma más barata de contexto que existe, y la única que no se consume.

Ahora la parte que casi nadie aplica: la misma idea de arquitectura se puede aplicar a tu flujo de trabajo con IA. El modelo es un adaptador. El arnés —Claude Code, Cursor, lo que uses— es un adaptador. Tu dominio son los specs, la memoria, los estándares y los tests. Si tu conocimiento vive adentro de una herramienta, no tenés arquitectura: tenés dependencia.

Ese es exactamente el criterio con el que este sitio marca cada herramienta como portable o no. La portabilidad no es una virtud abstracta: es la frontera puerto/adaptador aplicada a tu propio entorno de trabajo. Lo que está adentro sobrevive al cambio de herramienta. Lo que está afuera, no.

Y el contra, porque lo tiene: hexagonal mal aplicada —un puerto por cada cosa, interfaces con una sola implementación, cuatro capas para leer un registro— le da al agente más superficie, no menos. La abstracción que no separa nada real es exactamente el tipo de patrón que un modelo replica con entusiasmo.

La idea que sobrevive a las herramientas

Si para cambiar una regla de negocio hay que tocar el framework, el agente va a tocar el framework.