Ir al contenido

Lo que aprendí

Construí software con un agente de IA. Esto es 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

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.

Lección 1

Un agente olvida tu diseño de una sesión a otra.

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.

Distancia al diseñoReglas en un documentoEl diseño12345SesiónReglas que se ejecutanEl diseñoRechazado por una comprobación12345Sesión
Con reglas en un documento, los pequeños desvíos se acumulan. Con reglas que se ejecutan, cada uno se detiene en el cambio que lo provoca.

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.

Reglas en un documento

  • El agente las lee al empezar y las sigue casi siempre.
  • El desvío aparece semanas después, en revisión.
  • Revisar es buscar errores a ojo.

Reglas que se ejecutan

  • Se comprueban en cada cambio, sin excepción.
  • El cambio se rechaza en el momento, con el nombre de la regla.
  • Revisar es decidir sobre lo que ya pasó las comprobaciones.

Lección 2

El agente trabaja siempre en el mismo orden.

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.

  1. Autorizar
  2. Explorar
  3. Resolver dudas
  4. Clasificar
  • Pequeña: directo al código

    1. Implementar
  • Grande: con seguimiento primero

    1. Hacer seguimiento
    2. Implementar

Cerrar

Toda petición pasa por el mismo tronco. Clasificar decide si el trabajo va directo al código o se sigue primero.
  1. Autorizar

    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.

  2. Explorar

    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.

  3. Resolver dudas

    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.

  4. Clasificar

    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.

  5. Hacer seguimiento

    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.

  6. Implementar

    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.

  7. Cerrar

    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

El agente abre la pull request. Yo decido cuándo está lista.

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.

  1. El agente escribe y prueba en local
  2. Abre la pull request
  3. Una persona pone la etiqueta
  4. Arranca la integración continua
  5. Si pasa, se puede fusionar. Si falla, se quita la etiqueta y vuelve al agente

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

Si no ves qué hace el agente, no sabes cuándo intervenir.

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.

  • landingEscribiendo tests para la nueva secciónTrabajando
  • webPregunta antes de lanzar una migraciónTe necesita
  • mobileTodas las comprobaciones pasan, rama listaTerminado

SiguienteRevisa el plan de la web y lanza las comprobaciones antes del commit.

  • Estado de cada sesión

    Trabajando, te necesita, terminada o con error. Solo entro donde hace falta.

  • Plan y tareas

    La lista de tareas del agente y de los subagentes que lanza. Puedo seguir un trabajo largo sin leer cada mensaje.

  • Contexto restante

    Una barra por sesión. Cuando se agota, empiezo una sesión nueva antes de que baje la calidad.

  • Consejo y siguiente paso

    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

Unas capas claras le dicen al agente dónde va cada pieza.

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.

EntradaInfraestructuraAplicaciónDominioLas dependencias apuntan hacia dentro
La entrada y la infraestructura quedan por fuera; toda dependencia apunta hacia dentro, hacia el dominio.
  1. Entrada

    Lo que recibe el mundo exterior: una pantalla, una ruta HTTP, un comando. Traduce y delega; no decide.

  2. Aplicación

    Los casos de uso. Coordina el trabajo, pero las reglas no viven aquí.

  3. Dominio

    Las reglas del negocio. No sabe nada de bases de datos, frameworks ni red.

  4. Infraestructura

    Bases de datos, servicios externos, archivos. Implementa lo que el dominio necesita.

Todas las flechas apuntan hacia el dominio. La infraestructura depende del dominio, no al revés.

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

Una regla solo cuenta si romperla rompe el build.

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.

  1. Escrita

    Está en las instrucciones del proyecto, donde el agente la lee primero. Explica el porqué, no solo el qué.

  2. Conectada

    Un linter, un test o un hook la comprueba en cada máquina, antes de cada commit o push.

  3. Impuesta

    La integración continua rechaza el merge si se rompe, sea quien sea el autor, persona o agente.

PasaTiposCódigo que compila "por casualidad" o que usa datos con la forma equivocada.
FallaArquitecturaImports que cruzan capas o ciclos entre módulos.
PasaLint estrictoPatrones peligrosos, como insertar datos como HTML en lugar de como texto.
PasaCobertura mínimaComportamiento nuevo sin test que lo pruebe.
PasaSecretosClaves o contraseñas a punto de subirse al repositorio.
Una comprobación falla. El agente lee el nombre de la regla, mueve el import y vuelve a ejecutar todo.

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

Cuatro prácticas que hacen difícil romper la arquitectura sin querer.

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.

  • Prohibir todo por defecto y probar la prohibición.

    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.

  • Escribir las reglas de arquitectura como tests.

    "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.

  • Dos herramientas que se solapan a propósito.

    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.

  • Documentar qué comprobación atrapa cada regla.

    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.

Reglas de capasUnafuncionalidadimporta otraLa pantallalee la basede datosGrafo dedependenciasCiclos deimportsMóduloshuérfanosEl dominioimportainfraestructura
Cada herramienta atrapa algo que a la otra se le escapa, y las dos atrapan la regla más importante.

Lección 8

Cinco hábitos para que un agente sea seguro de usar.

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.

Fuera

  • Comentarios e issues
  • Páginas web
  • Documentación descargada

Se lee como dato, nunca como orden

El agente

  • Lee el código
  • Ejecuta las comprobaciones
  • Edita en una rama

Leer secretos: denegado

Irreversible: decide una persona

Una persona

  • Borra
  • Publica
  • Fusiona
El texto de fuera entra solo como dato. El agente trabaja dentro de sus permisos, y todo lo irreversible espera a una persona.
  • El texto de fuera es un dato, no una orden.

    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 mínimo acceso necesario.

    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

  • Fijar las dependencias.

    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

  • Los secretos se quedan fuera.

    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

  • Los datos se muestran como texto.

    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

Lo que necesita atención, en un solo panel.

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.

  • Mapa del trabajo

    Cada herramienta que usa el agente, con una marca donde una comprobación automática le dijo que no.

  • Actualizaciones

    Qué está desactualizado en cada ecosistema y lo difícil que será actualizarlo.

  • Vulnerabilidades

    Avisos de seguridad conocidos para mis dependencias, con enlace a cada uno.

  • Pendientes

    Las tareas que el agente deja para más tarde, en una sola lista que puedo vaciar.

  • Estado de la rama

    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

La IA no me quitó trabajo. Me cambió el trabajo.

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.

Foto de Hernán David Figueroa

Sobre el desarrollador

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