La idea en una frase
Deja que la IA escriba, y haz que el proyecto diga que no cuando algo está mal.
Una arquitectura estricta, con tests y linters que fallan al romperla, convierte la velocidad del agente en código que puedes mantener.
Lo que aprendí
Trabajo con IA desde 2022 y con agentes desde mediados de 2025, cuando empezaron a aparecer. Con ellos he construido proyectos reales: un backend, una app móvil, una web y esta página. Al principio el agente escribía rápido y yo revisaba despacio. Con el tiempo entendí que la calidad no dependía de escribir mejores instrucciones, sino de construir un entorno donde el código malo no pudiera pasar.
Esta página recoge esas lecciones. No vende nada: cuenta qué salió mal, qué cambié y por qué funciona, de forma que sirva en cualquier lenguaje o stack.
La idea en una frase
Una arquitectura estricta, con tests y linters que fallan al romperla, convierte la velocidad del agente en código que puedes mantener.
Lección 1
Escribí las reglas del proyecto en un documento: qué capa puede importar a cuál, dónde va cada cosa, qué no se toca. El agente las leía y seguía casi todas. Pero cada sesión empieza de cero, y "casi todas" se acumula.
El desvío nunca era grande. Un import que cruzaba una frontera, una lógica de negocio dentro de un controlador, un test que faltaba. Cada cambio parecía razonable por sí solo, y me daba cuenta semanas después, cuando ya había código encima.
Dejé de confiar en que el agente recordara las reglas y las convertí en comprobaciones que se ejecutan solas. Si un cambio cruza una frontera, la compilación o un test falla, con el nombre de la regla en el mensaje de error.
Un agente lee los errores con mucha atención. Un error con nombre le dice exactamente qué regla rompió, y lo corrige antes de que yo vea el cambio. La regla deja de depender de la memoria de nadie, ni la del agente ni la mía.
Lección 2
Sin un orden fijo, el agente hacía lo que parecía más útil en cada momento. A veces editaba archivos cuando yo solo había hecho una pregunta. A veces empezaba a escribir sin leer cómo estaba hecho el resto, o declaraba algo terminado sin haberlo probado.
Para esto uso Organic Driven Development: un flujo de siete pasos que el agente sigue en cada petición, pequeña o grande. El proceso crece con el tamaño de la tarea, en lugar de aplicar la misma ceremonia a todo.
Pequeña: directo al código
Grande: con seguimiento primero
Cerrar
Primero comprueba si de verdad le pedí un cambio. Una pregunta, una revisión o un plan no tocan ningún archivo.
Sin este pasoEdiciones sorpresa cuando yo solo quería una respuesta.
Lee el código existente y las reglas del proyecto antes de proponer nada.
Sin este pasoSoluciones que funcionan pero no encajan con lo que ya hay.
Si una decisión es mía (producto, alcance, diseño), hace una sola pregunta concreta y espera. Si es técnica, decide y sigue.
Sin este pasoO me llena de preguntas mecánicas, o decide por mí cosas que no le tocan.
Una tarea es pequeña si se entiende, el riesgo está contenido y se podría retomar solo con el diff. Si no, es grande.
Sin este pasoO todo lleva ceremonia, o nada la lleva.
Las tareas grandes reciben un documento que cita mi petición palabra por palabra, una lista de tareas y un registro de decisiones.
Sin este pasoEl trabajo se pierde al cortarse una sesión, y el resultado se aleja de lo que pedí sin que nadie lo note.
Primero un test que falla, luego el código que lo hace pasar. Los commits van por unidad de trabajo, de unas 400 líneas como máximo.
Sin este pasoCambios enormes, sin prueba de que funcionan, imposibles de revisar en una sentada.
Informa de qué pasó, qué falló y qué no pudo comprobar.
Sin este paso"Listo" sin evidencia, y descubrir el fallo yo después.
El orden convierte el buen criterio en hábito. No depende de que el agente "se acuerde" de ser cuidadoso: cada paso tiene una salida concreta que puedo comprobar. Y como el proceso escala con la tarea, un arreglo de una línea sigue siendo rápido.
Lección 3
Cuando el agente puede hacer todo el ciclo solo, escribir, probar y fusionar, la revisión se vuelve un trámite. Los cambios llegaban a la rama principal porque los checks pasaban, no porque alguien hubiera decidido que estaban bien.
Separé "está hecho" de "está listo". El agente trabaja en una rama y abre la pull request, pero la integración continua solo arranca cuando yo pongo una etiqueta a mano. El merge exige que esa ejecución pase, y el agente tiene prohibido poner la etiqueta.
Cada merge pasa por una decisión humana explícita, y esa decisión es barata: llego a la revisión con los tests, el lint y la arquitectura ya comprobados en local. Mi trabajo deja de ser cazar errores y pasa a ser juzgar si el cambio es el correcto.
Lección 4
Con varias sesiones abiertas a la vez, perdía el hilo. Una llevaba diez minutos esperando una respuesta mía, otra se había quedado sin contexto y empezaba a cometer errores tontos, y otra había terminado sin que me enterara. Para saberlo tenía que leer cada conversación.
Añadí al entorno del agente mods que muestran su estado de un vistazo. No cambian lo que el agente hace; me dan visibilidad sobre ello.
SiguienteRevisa el plan de la web y lanza las comprobaciones antes del commit.
Trabajando, te necesita, terminada o con error. Solo entro donde hace falta.
La lista de tareas del agente y de los subagentes que lanza. Puedo seguir un trabajo largo sin leer cada mensaje.
Una barra por sesión. Cuando se agota, empiezo una sesión nueva antes de que baje la calidad.
Después de cada turno, una nota corta sobre lo que acaba de hacer y una sugerencia de qué hacer después.
Trabajar con un agente es, sobre todo, decidir cuándo intervenir. Cuanto antes veo que una sesión se atasca o se desvía, menos trabajo hay que deshacer. La visibilidad convierte la supervisión en algo que cabe en un vistazo.
Lección 5
Cuando el proyecto no tenía una estructura explícita, el agente ponía el código donde le resultaba más cómodo. La lógica de negocio acababa mezclada con el acceso a datos y con la interfaz. Cada cambio tocaba muchos archivos, y nadie, ni él ni yo, podía decir con seguridad qué rompería.
Construí repositorios base con una arquitectura estricta ya definida: backend, móvil, web y landing. Los nombres de las capas cambian según el proyecto, pero la idea es siempre la misma. Las dependencias apuntan siempre hacia el dominio, nunca al revés, y cada módulo o funcionalidad se mantiene aislado: una funcionalidad no importa directamente otra.
Lo que recibe el mundo exterior: una pantalla, una ruta HTTP, un comando. Traduce y delega; no decide.
Los casos de uso. Coordina el trabajo, pero las reglas no viven aquí.
Las reglas del negocio. No sabe nada de bases de datos, frameworks ni red.
Bases de datos, servicios externos, archivos. Implementa lo que el dominio necesita.
Prohibido: el dominio importa infraestructura
Para el agente, la arquitectura es un mapa: ante cada cambio sabe en qué capa va y qué puede importar. Para mí, cada cambio queda acotado y es más fácil de revisar. Y como la regla es simple ("las flechas apuntan hacia dentro"), una herramienta puede comprobarla en cada build.
Lección 6
Tenía reglas en tres sitios distintos: algunas solo escritas, otras comprobadas en mi máquina, otras solo en la integración continua. Las que solo estaban escritas eran justo las que el agente acababa rompiendo.
Ahora cada regla sube una escalera de tres peldaños, y en todos mis proyectos se comprueban las mismas cinco cosas, aunque la herramienta concreta cambie según el lenguaje.
Está en las instrucciones del proyecto, donde el agente la lee primero. Explica el porqué, no solo el qué.
Un linter, un test o un hook la comprueba en cada máquina, antes de cada commit o push.
La integración continua rechaza el merge si se rompe, sea quien sea el autor, persona o agente.
La fila en rojo es la útil. Detiene el cambio, nombra la regla y el agente sabe qué corregir. Un proyecto donde todo es verde porque nada se comprueba no protege nada.
Lección 7
Tener reglas que fallan es el principio. Estas cuatro prácticas son las que más me ayudaron a que esas reglas siguieran protegiendo con el tiempo, escriba quien escriba el código.
Al principio mis reglas de capas listaban lo prohibido, así que lo que no estaba en la lista quedaba permitido sin que nadie lo decidiera. Ahora la regla prohíbe cualquier import que no esté explícitamente permitido, y un pequeño proyecto de prueba demuestra que cada import prohibido falla de verdad. Si alguien debilita la regla, ese test se pone en rojo.
Resultado Una regla que no se puede debilitar en silencio.
"El dominio no importa nada de fuera" puede ser una frase en un documento o un test que se ejecuta con el resto de la suite. Lo segundo corre en cada máquina y en la integración continua, y su mensaje de error explica la regla mejor que cualquier documento.
Resultado La regla se ejecuta allí donde se ejecutan los tests.
Una comprueba capa contra capa. La otra mira el grafo completo de dependencias: ciclos, módulos huérfanos, un dominio que importa algo que no debería. Cada una atrapa lo que a la otra se le escapa, y si una se desconfigura, la otra sigue ahí.
Resultado Una herramienta rota no abre un hueco.
Mantengo una tabla "atrapada por" que asocia cada regla de arquitectura con la herramienta que la impone. Una regla sin comprobación destaca enseguida como la siguiente que hay que conectar.
Resultado La siguiente regla que conectar siempre está a la vista.
Lección 8
Un agente que lee, escribe y ejecuta comandos tiene más acceso que muchas personas del equipo. Estos hábitos valen tanto para el flujo del agente como para la aplicación que construye, y cada uno está respaldado por una comprobación, no solo por una frase.
Se lee como dato, nunca como orden
Leer secretos: denegado
Irreversible: decide una persona
Comentarios, issues, descripciones de pull requests, páginas web y documentación descargada informan al agente. Pero cualquiera puede escribir en ellos, y alguno puede intentar darle instrucciones. La regla es que solo yo doy órdenes, y todo lo que pida un texto externo se verifica primero.
Respaldado por Las instrucciones del proyecto y la revisión humana
El agente recibe solo los permisos que la tarea requiere. Leer secretos está denegado, y todo lo irreversible (borrar, publicar, fusionar) espera a una persona.
Respaldado por Reglas de permisos y listas de denegación
Archivos de bloqueo con versiones exactas y sumas de comprobación, acciones de integración continua fijadas por commit, y un periodo de espera antes de instalar una versión recién publicada. Un ataque a la cadena de suministro suele descubrirse en días; esperar es barato.
Respaldado por Instalaciones congeladas y límites de antigüedad
Cada commit se escanea antes de crearse y otra vez en la integración continua. Los archivos de entorno se ignoran, salvo el de ejemplo, que no lleva valores reales.
Respaldado por Dos escáneres de secretos independientes
Nada que venga de un usuario o de una API se inserta como HTML. El lint rechaza esas operaciones, y una política de seguridad de contenido bloquea cualquier script que el build no haya registrado.
Respaldado por El lint y la política de seguridad de contenido
Lección 9
Los problemas que no rompen el build se acumulan en silencio: dependencias que se quedan antiguas, vulnerabilidades publicadas en librerías que uso, tareas que el agente dejó "para después", una rama que se quedó atrás respecto a la remota. Me enteraba tarde, normalmente en la revisión o cuando algo ya fallaba.
Añadí un mod que mantiene el estado del proyecto junto a la conversación con el agente. Muestra cinco cosas.
Cada herramienta que usa el agente, con una marca donde una comprobación automática le dijo que no.
Qué está desactualizado en cada ecosistema y lo difícil que será actualizarlo.
Avisos de seguridad conocidos para mis dependencias, con enlace a cada uno.
Las tareas que el agente deja para más tarde, en una sola lista que puedo vaciar.
Un aviso cuando voy por detrás de la remota, antes de construir sobre código viejo.
El agente y yo vemos lo mismo. Puedo pedirle que trate un aviso concreto antes de que se convierta en un problema, en lugar de descubrirlo en la revisión.
Lo que me llevo
Dejé de escribir la mayor parte del código y pasé a diseñar el entorno donde se escribe: las capas, las reglas que fallan, el orden de trabajo, la puerta antes del merge y la visibilidad sobre lo que ocurre. Cuanto más estricto es ese entorno, más libertad puedo darle al agente, porque lo que está mal no consigue pasar.
Si tuviera que quedarme con una sola idea: no intentes que el agente sea perfecto. Haz que el proyecto detecte cuando no lo es.

Hernán David Figueroa
Desarrollador fullstack con más de 8 años de experiencia, especializado en fintech y pagos seguros. Trabajo en terminales POS y funciones de pago para Android e iOS en una pasarela de pagos colombiana. Trabajo con IA desde 2022 y con agentes desde mediados de 2025. Vivo en Bogotá.
Escribo y mantengo Guardrail por mi cuenta. Ver mi perfil de desarrollador