Construir software con agentes de IA es fácil de empezar y difícil de sostener. La primera tarde parece magia. Tres meses después tienes una app que no terminas de leer, una carpeta de decisiones que ya no cuadra con el código y la sensación incómoda de que los agentes avanzan rápido en direcciones que nunca aprobaste.
Los agentes no son el problema. Escriben buen código. El problema es que generar código nunca fue la parte difícil de entregar software, y ahora que es barato, todo lo que siempre fue difícil pasa a ser el trabajo entero. Ese trabajo tiene una forma. Este es el mapa.
Yo opero agentes a diario construyendo PaellaDoc. No en una demo, en un producto real con usuarios, invariantes y un backlog que tiene que sobrevivir a que yo olvide cosas. Lo que sigue es el bucle que de verdad corro, partido en cinco partes: definir, especificar, ejecutar, verificar, aprender. Cada parte es un sitio donde el trabajo se pierde si no lo sostienes. Cada una es una parada de este mapa, y cada una enlaza al cluster donde lo he escrito en detalle.
La única idea debajo de las cinco partes
Esta es la frase a la que se reduce la guía entera, la misma que atraviesa todo lo que construyo:
El agente puede escribir el código. No puede ser lo que decide si el código cuenta, porque es la misma cosa a la que se está juzgando.
Algo fuera del agente tiene que sostener el contrato: qué estás construyendo, qué tiene que seguir siendo cierto, qué evidencia demuestra que está hecho. Cuando construyes con un solo agente en un solo chat, ese algo eres tú, sosteniéndolo todo en la cabeza. Funciona hasta que el trabajo se te sale de una cabeza. Construir con agentes a cualquier escala seria es la disciplina de sacar ese contrato de tu cabeza y meterlo en un sistema que sobreviva a las sesiones, a los modelos y a tu propia mala memoria. El manifiesto detrás de este sitio a eso lo llama ser el runtime. Las cinco partes de abajo son cómo dejas de serlo a mano.
Parte 1. Definir: decidir se encareció
Construir se abarató. Decidir qué construir se encareció, y casi nadie ha vuelto a poner precio a su atención en consecuencia. Cuando un agente produce una feature que funciona en una tarde, el coste de construir lo equivocado se desploma a casi nada por intento y estalla en el agregado. Acabas con una feature factory corriendo a velocidad de máquina, entregando superficie que nadie pidió.
La primera parte del bucle es negarte a que los agentes arranquen hasta saber qué comportamiento intentas instalar y por qué. Esto es trabajo de producto, y la IA cambió su economía sin cambiar su naturaleza. El discovery sigue siendo hablar con la realidad. Un modelo es buena socia para pensar y pésima para decidir, porque sintetiza con aplomo una respuesta a partir de lo que le diste, haya evidencia o no. Toda la disciplina vive en product management en la era IA: las decisiones, las asunciones arriesgadas, la evidencia de que un cambio merece la pena antes de que los agentes lo construyan entero.
Hay una trampa concreta que conviene nombrar. Cuando construir es caro, una mala idea muere en el backlog porque nadie quiere pagar por construirla. Cuando construir es barato, esa misma mala idea se construye, se lanza y se defiende, porque ya existe y alguien le ha cogido cariño. La producción barata no solo te deja construir más cosas buenas. Quita la fricción que antes mataba a las flojas, y esa fricción hacía un trabajo real. La Parte 1 va de volver a poner fricción deliberada justo donde el mercado la quitó: en la decisión, no en el teclado.
Definir es también donde muchos proyectos reales arrancan hoy, de lado: alguien vibe-codea un prototipo un fin de semana, funciona, y sin ruido se convierte en el producto. Es una rampa de entrada legítima, no un pecado. Solo significa que el paso de definir ocurre después de la primera build en vez de antes, y el ascenso de prototipo a producción tiene su propio puente difícil, que es todo el cluster de vibe coding a producción. En cualquier caso, sales de la Parte 1 con intención que puedes defender, no con una intuición.
Parte 2. Especificar: convertir la intención en contrato
La intención en tu cabeza no se puede delegar a un agente, y la intención en un prompt se evapora cuando termina la sesión. El puente entre decidir y construir es la especificación: el contrato que dice qué tiene que cambiar, qué no, y cómo reconocer un resultado correcto.
Es la parte que casi todo el mundo se salta, y es la palanca más barata de todo el bucle. Una spec no es ceremonia. Es lo que te deja apuntar un agente a una tarea y demostrar después si la hizo, sin volver a litigar el diseño entero de memoria. El argumento completo es el desarrollo guiado por especificaciones: el contrato de aceptación existe antes de escribir una línea, y un build verde no es lo mismo que una feature correcta.
Dos propiedades hacen que una spec valga la pena cuando quien la consume son agentes. Primero, tiene que ser portable, capaz de entrar por una herramienta y salir por otra sin degradarse en prosa, que es el argumento de las especificaciones de software deberían ser portables. Segundo, sus criterios de aceptación tienen que ser cosas que una máquina pueda comprobar de verdad, no sensaciones que un humano tenga que mirar a ojo. Sales de la Parte 2 con un contrato que puede viajar con la tarea a la ejecución y volver con la evidencia pegada.
Parte 3. Ejecutar: operar los agentes sin ser su runtime
Ahora los agentes escriben. Esta es la parte que todo el mundo cree que es el trabajo entero, y es la que más parece magia y menos se comporta como tal a escala.
En el momento en que pasas de un agente a varios, el trabajo deja de ser “promptear bien” y se convierte en operaciones. Partes el producto en tareas, abres sesiones paralelas en worktrees, enrutas cada tarea al motor adecuado y pagas el coste real de ser el scheduler. Peleas con la pérdida de contexto entre sesiones, el asesino de productividad que aparece cada vez que una ventana se compacta o una sesión nueva arranca en frío y olvida la decisión que tomaste ayer. Decides qué memoria para agentes de código tiene que persistir fuera del chat, porque el chat es el único sitio donde tus decisiones duraderas jamás deberían vivir. Y aceptas que los agentes van a derivar, así que diseñas para la divergencia en vez de rezar contra ella, y aprendes a correr varios agentes sin que se contaminen entre sí.
Toda esta parte es un cluster, el que contiene esta guía: operar agentes de código. Su verdad incómoda es que un buen desarrollador puede hacer todo esto a mano y no darse cuenta, porque se le da bien. Justo por eso queda invisible y sin precio. El trabajo de la Parte 3 es real lo hayas nombrado o no, y nombrarlo es el primer paso para sacarlo de tu propia atención.
Esto es lo que se siente en un día normal. Tengo varias sesiones abiertas, cada una en su worktree, cada una en una tarea distinta. Una refactoriza un módulo, una añade una feature, una persigue un bug. Sobre la hora dos noto que la sesión de la feature y la del refactor han editado la misma interfaz, de formas incompatibles, y ninguna sabe que la otra existe. Nadie se lo ha dicho, porque “el otro agente cambió el contrato” no es algo que un agente pueda observar desde dentro de su propia ventana. Así que paro, leo los dos diffs, decido qué forma gana y le paso a la sesión perdedora una corrección. Esa interrupción es el trabajo. No es un fallo de las herramientas. Es la coordinación que antes se repartía entre un equipo de humanos que hablaban entre ellos, ahora colapsada en una persona que tiene que ser el único canal entre agentes que no se ven. Multiplícalo por ocho sesiones y entiendes por qué throughput y sistema de entrega no son lo mismo.
La ejecución también tiene un sitio físico. Todo esto puede correr en la nube de otro, medido y con límites, o puede correr en tu máquina, donde tu código y tu contexto siguen siendo tuyos. Es el argumento de el manifiesto detrás de este sitio, y la definición operativa de la fábrica local de software: producto, código y evidencia en hardware que posees, con agentes enrutados entre motores en vez de atados a un proveedor. Sales de la Parte 3 con código que funciona y, si lo hiciste bien, un rastro de lo que pasó.
Parte 4. Verificar: que «hecho» signifique algo
El agente dice que está hecho. El build está verde. Ninguna de las dos cosas es evidencia. Esta es la parte de construir con agentes que la velocidad de las Partes 1 a 3 vuelve innegociable, porque el output dejó de ser el cuello de botella el día en que los agentes empezaron a producir más de lo que puedes leer.
Verificar es donde rechazas el éxito auto-declarado. Hecho significa que el comportamiento pasa los criterios de aceptación que existían antes de escribir una línea, con la evidencia pegada. La disciplina entera es verificar código generado por IA: evidencia, no sensaciones. Es también donde vive el modo de fallo del código de IA, el que me sigo encontrando: código localmente correcto y globalmente incoherente, cada diff sensato por su cuenta mientras el sistema pierde el hilo en silencio. Un agente que arregla el requisito nuevo y rompe callado un invariante viejo pasará su propia revisión siempre, porque nada le dijo que el invariante existía.
La versión más afilada que me sigo encontrando es un agente que reporta «tests pasan» de tests que nunca corrió, o que pasan porque no comprueban nada relevante. Un éxito auto-reportado es una afirmación, no un resultado, y a velocidad de agente recibes demasiadas afirmaciones para revisarlas leyendo una a una. Así que la verificación tiene que volverse algo que hace el sistema, no algo que haces tú mirando un resumen. Puertas que corren los criterios reales contra el comportamiento real, y un run que no tiene permiso para llamarse hecho hasta que están verdes.
Por eso los criterios de la Parte 2 importan tanto aquí. Verificar no es una actividad aparte atornillada al final. Es el contrato de la Parte 2, ejecutado contra el resultado real. Sales de la Parte 4 con trabajo que está demostrado o marcado con claridad como todavía-no, y sin checks verdes mintiéndote.
Parte 5. Aprender: quedarte con lo que el sistema acaba de descubrir
Cada run produce algo que vale la pena guardar y que no es código: una decisión, un invariante descubierto a las malas, la razón por la que se descartó un enfoque. Si ese conocimiento solo vive en el transcript, muere cuando el transcript se va scroll arriba, y el siguiente agente, o el siguiente tú, lo redescubre rompiendo lo mismo otra vez.
La Parte 5 es hacer que el sistema recuerde. No un wiki que nadie actualiza, sino una estructura a la que el trabajo escribe como efecto secundario de hacer el trabajo. La forma de eso es un grafo de conocimiento de producto, respaldado en el lado de ingeniería por un grafo de conocimiento del código: la topología real del producto, las relaciones que los agentes necesitan para razonar un cambio en vez de hacer grep a ciegas y rezar. La memoria que persiste aquí es lo que impide que la pérdida de contexto de la Parte 3 sea permanente, y lo que deja a un agente hacer onboarding contra el grafo en vez de contra un conocimiento tribal que nadie escribió.
Y debajo de las cinco partes hay una forma de trabajar, no una herramienta. El hilo más viejo de este sitio, el framework de desarrollo AI-first, es el argumento de que este bucle es una disciplina que adoptas a propósito, no un set de features que compras. El framework es el método. Las cinco partes son el método en movimiento.
Las cinco partes son un sistema, no cinco herramientas
Esta es la parte que más importa, y la razón de que el interlinking de este sitio sea el argumento y no un adorno. Si te compras una herramienta de discovery, una de specs, un ejecutor de agentes, un dashboard de tests y un wiki, no has construido este bucle. Has construido cinco silos, con las costuras entre ellos como el sitio exacto donde el trabajo se va a morir: la decisión que nunca llegó a la spec, la spec que el agente nunca vio, la evidencia que vive en un log de CI que nadie lee, el invariante que solo estuvo en la cabeza de alguien.
El bucle solo funciona cuando el mismo contrato fluye por las cinco partes. La intención de la Parte 1 se convierte en los criterios de aceptación de la Parte 2, viaja con la tarea por la ejecución de la Parte 3, se comprueba contra el resultado real en la Parte 4 y deja atrás conocimiento que el sistema guarda en la Parte 5. Un contrato, cinco paradas, ningún traspaso donde se aplane de vuelta a prosa.
Eso es lo que construyo, y la razón de construirlo local-first y portable en vez de como otro silo en la nube. No un agente mejor. Los agentes son buenos. La capa donde el contrato sigue vivo por las cinco partes, en tu máquina, por encima de cualquier modelo o proveedor. El agente escribe el código. Tú te quedas la intención de producto y las decisiones que importan. El sistema carga con el resto.
Construir software con agentes de IA, bien hecho, no es teclear más rápido. Es correr este bucle a propósito, y negarte a ser el único sitio donde se sostiene.
¿Cuál de las cinco partes corre ahora mismo en tu cabeza sin que la hayas nombrado? Cuéntame en el foro.
Preguntas frecuentes
¿Cómo empiezo a construir software con agentes de IA?
Empieza negándote a que los agentes construyan hasta saber qué comportamiento instalas y por qué. El código es la parte barata ahora; decidir qué construir es donde se movió el coste. Define intención que puedas defender, conviértela en una spec con criterios de aceptación que una máquina pueda comprobar, y solo entonces apunta agentes a la tarea.
¿Qué hace falta además del modelo para construir con agentes?
Algo fuera del agente que sostenga el contrato, porque el agente no puede juzgar si su propio código cuenta. Eso significa una spec que diga qué tiene que cambiar y seguir siendo cierto, memoria que persista decisiones e invariantes fuera del chat, y puertas que demuestren que el trabajo está hecho. Con un agente en un chat, ese algo eres tú.
¿Cómo se verifica lo que construyen los agentes?
No fiándote del «hecho» ni de un build verde. Hecho significa que el comportamiento pasa los criterios de aceptación que existían antes de escribir una línea, con la evidencia pegada. A velocidad de agente recibes demasiadas afirmaciones para revisarlas leyendo, así que la verificación tiene que volverse puertas que el sistema corre contra el comportamiento real, no mirar un resumen.
¿Cómo se escala de un agente a varios?
En el momento en que pasas de uno a varios, el trabajo se vuelve operaciones: partir el producto en tareas, correr sesiones en paralelo, pelear con la pérdida de contexto, persistir memoria compartida y reconciliar agentes que no se ven. Solo escala cuando el mismo contrato fluye por definir, especificar, ejecutar, verificar y aprender, en vez de vivir en tu cabeza.