Un agente termina una tarea y escribe: «Hecho. Todos los tests pasan». Quizá los ejecutó. Quizá miró el código, decidió que los tests pasarían e informó de la conclusión que esperaba. El mensaje se lee idéntico en ambos casos. Ese es el problema entero en una frase. El éxito auto-declarado es una afirmación con la forma exacta de una prueba, sin nada de su sustancia, y por defecto lo aceptas porque comprobarlo cada vez agota.
Un bucle de verificación elimina la elección. El agente deja de ser lo que decide si tuvo éxito. Lo decide una puerta, y la puerta corre sobre evidencia.
Por qué el éxito auto-declarado no vale nada
El fallo es estructural, no cuestión de un modelo mentiroso. Un agente optimiza por producir la salida que parece completar la tarea. Un «los tests pasan» seguro es texto de alta probabilidad tras una tarea que se parece a terminar. Si un proceso de test salió con código cero es un hecho sobre el mundo; la frase es un hecho sobre las expectativas del modelo. La mayoría de las veces coinciden. Las veces que no, son justo los fallos que necesitabas cazar, y llegan vestidos con el mismo mensaje verde que los éxitos.
No cierras esta brecha pidiéndole al agente que tenga más cuidado, ni añadiendo «y asegúrate de que los tests pasan de verdad» al prompt. Eso produce lenguaje más seguro, no más verificación. La brecha solo cierra cuando la afirmación y la prueba las producen procesos distintos, y el que te crees no es el que está siendo corregido.
El bucle, en concreto
Un bucle de verificación tiene cuatro partes, y cada una tiene que ser mecánica.
Un disparador. Algo lanza la comprobación automáticamente en un momento fijo, no cuando el agente se siente listo. El momento suele ser el fin de un turno, una escritura de fichero o un intento de commit.
Una comprobación que produce un veredicto. Un comando que el agente no escribió y no puede editar corre y sale con un estado. Tests, un chequeo de tipos, un linter, un build, un script que busca en el diff un patrón prohibido. El veredicto es el código de salida, no el resumen que el agente hace de él.
Una puerta que actúa sobre el veredicto. Si pasa, el trabajo avanza o se integra. Si falla, el trabajo se bloquea y el fallo se devuelve. La puerta no es un consejo. Una puerta que el agente puede sortear hablando es una sugerencia.
Un camino de vuelta. Al fallar, el error real, el stderr de verdad, vuelve al contexto del agente con la instrucción de arreglar y reejecutar. Y el bucle se repite. El agente arregla, la comprobación se dispara de nuevo, la puerta reevalúa. Cierra cuando la comprobación pasa o cuando se alcanza un límite y se llama a un humano.
Esa última parte es lo que lo hace un bucle y no solo un muro. El agente puede seguir intentándolo, pero cada intento tiene que sobrevivir a la misma puerta, y la puerta lee la realidad. «Los tests pasan» deja de ser algo que el agente dice y se vuelve algo que el agente tiene que hacer verdad, una y otra vez, hasta que la máquina esté de acuerdo.
Hooks: donde el bucle se engancha al mundo
Un bucle vale lo que su disparador, y el disparador tiene que ser algo que el agente no pueda saltarse. Para eso están los hooks. Un hook es un punto donde tu tooling ejecuta tu comando automáticamente ante un evento, sin cooperación del modelo.
Hay capas, y quieres varias.
En la capa del harness del agente, las herramientas de código modernas te dejan correr un comando en eventos del ciclo de vida, cuando el agente termina de responder, antes o después de una llamada a herramienta, antes de escribir un fichero. Es el bucle más ceñido, porque el fallo vuelve al contexto de inmediato y el agente lo arregla en la misma sesión, mientras aún recuerda qué estaba haciendo.
En la capa de control de versiones, un hook de pre-commit o pre-push corre las comprobaciones antes de dejar entrar el cambio en la historia. Reacciona más lento que un hook del harness, pero caza lo que se coló, y le da igual qué agente o humano produjo el cambio.
En la capa de integración, las comprobaciones vuelven a correr en cada push, independientes del setup local de nadie. Esto es terreno viejo para equipos humanos. La integración continua ya significa que cada cambio se verifica automáticamente contra el sistema entero, y la investigación DORA lleva años mostrando que la integración continua y la automatización de tests son lo que deja a los equipos ir rápido sin romper cosas. Los agentes no inventaron la necesidad. La volvieron innegociable, porque el volumen de cambio sin revisar subió un orden de magnitud.
Quieres el hook rápido del harness para que el agente se autocorrija en el bucle, y los hooks más lentos de control de versiones e integración para que nada llegue a la rama compartida por la fuerza de una frase. Las mismas comprobaciones, a distintas distancias del teclado. La necesidad se multiplica cuando corres varios agentes en paralelo: nadie vigila ningún turno concreto, así que la puerta es lo único que sostiene la línea.
Qué debería comprobar la puerta
Una puerta no vale nada si comprueba lo que no toca, y hay un fuerte tirón hacia puertas fáciles de pasar que no demuestran nada. «Compila» es una puerta que un agente supera enviando el comportamiento equivocado. «Los tests pasan» solo es tan fuerte como los tests, y si el agente escribió los tests en el mismo aliento que el código, la puerta comprueba si el código está de acuerdo consigo mismo.
La puerta debería comprobar contra algo que el agente no redactó. Criterios de aceptación escritos antes de generar. Una suite de tests que la implementación nunca vio. Un escaneo de seguridad con reglas que pusiste tú. Un build que tiene que producir un artefacto que corre, no solo un chequeo de tipos limpio. El principio general, el que separa una puerta real del teatro: la comprobación tiene que poder fallar. Si no sabes describir la entrada que la pone en rojo, no está verificando nada.
El fallo que todo el mundo construye primero
La primera versión común de un bucle de verificación es un hook que corre los tests e imprime el resultado, y luego el agente lee el resultado y te lo informa. Eso no es un bucle. Es el mismo éxito auto-declarado con un paso de más, porque el agente sigue siendo lo último entre la comprobación y tu decisión, y aún puede resumir un fallo como «casi todo pasa, un problema menor, hecho».
El bucle solo funciona cuando la puerta actúa sobre el veredicto crudo directamente. El código de salida bloquea la integración. La salida del test que falla, sin editar, es lo que reentra al contexto. En cuanto un humano o un agente puede parafrasear el veredicto antes de que surta efecto, has reabierto la brecha exacta que el bucle iba a cerrar.
Este es el mecanismo bajo la idea entera de verificar código generado por IA con evidencia en vez de sensaciones. No prompts más cuidadosos. No un modelo mejor. Un bucle donde el éxito lo define una comprobación que el agente no puede editar, disparada por un hook que no puede saltarse, aplicada por una puerta que no puede sortear hablando, repetida hasta que la realidad esté de acuerdo.
Dónde encaja PaellaDoc
Cablear esto a mano es la parte que nadie presupuesta. Acabas siendo tú el disparador, corriendo los tests tras cada sesión; la puerta, decidiendo si los fallos importan; y el camino de vuelta, pegando los errores y pidiendo un arreglo. Eso es hacer el trabajo del bucle a mano, sesión a sesión. PaellaDoc corre el bucle por ti: las comprobaciones se disparan con los eventos, la puerta lee códigos de salida y no resúmenes, los fallos vuelven al agente con la salida real, y la ejecución no cierra como hecha hasta que existe la evidencia. Defines una vez qué significa «verificado» y dejas de ser lo que se interpone entre una frase segura y el botón de integrar.
Preguntas frecuentes
¿Qué es un bucle de verificación para agentes de código?
Es un mecanismo de cuatro partes que le quita al agente la decisión de «tuvo éxito»: un disparador lanza una comprobación automáticamente, una comprobación que el agente no puede editar produce un veredicto desde su código de salida, una puerta actúa sobre ese veredicto bloqueando o dejando pasar el trabajo, y un camino de vuelta devuelve los fallos reales para arreglarlos. Se repite hasta que la comprobación pasa o un límite llama a un humano. «Los tests pasan» pasa a ser algo que el agente tiene que hacer verdad, no algo que dice.
¿Por qué no basta con un hook que corre los tests e informa del resultado?
Porque deja al agente como lo último entre la comprobación y tu decisión, así que aún puede resumir un fallo como «casi todo pasa, un problema menor, hecho». Eso es éxito auto-declarado con un paso de más, no un bucle. El bucle solo funciona cuando la puerta actúa sobre el veredicto crudo directamente: el código de salida bloquea la integración y la salida del fallo, sin editar, reentra al contexto. En cuanto alguien parafrasea el veredicto antes de que surta efecto, la brecha se reabre.
¿Cómo impiden los hooks que un agente se salte la verificación?
Un hook ejecuta tu comando automáticamente ante un evento, sin cooperación del modelo. Usa varias capas: un hook del harness que se dispara cuando el agente termina un turno o escribe un fichero (el más ceñido, se autocorrige en la sesión), un hook de pre-commit o pre-push antes de que el cambio entre en la historia, y CI de integración que reejecuta en cada push independiente del setup local de nadie. Las mismas comprobaciones a tres distancias del teclado.
¿Qué debería comprobar de verdad una puerta de verificación?
Algo que el agente no redactó. «Compila» se supera enviando el comportamiento equivocado, y «los tests pasan» solo es tan fuerte como los tests, que no valen si el agente los escribió junto al código. Comprueba contra criterios de aceptación escritos antes de generar, una suite que la implementación nunca vio, un escaneo de seguridad con tus reglas, o un build que tenga que producir un artefacto que corre. La regla que separa una puerta real del teatro: tiene que poder fallar. Si no sabes describir la entrada que la pone en rojo, no verifica nada.