Que la IA entienda la arquitectura, no solo el archivo
Un agente que ve un archivo por vez repite lo que ya está mal. Cómo construyo los agentes y las herramientas que planifican, implementan, validan y revisan — y por qué la decisión de diseño sigue siendo humana.
El problema no es que la IA escriba mal código
Es que escribe código coherente con lo que alcanza a ver. Y lo que alcanza a ver, por defecto, es un archivo y un puñado de coincidencias de texto.
En una migración eso se nota enseguida. Un endpoint no se migra solo: arrastra un modelo, dos adaptadores, la convención de errores del módulo y una decisión de diseño que nadie escribió pero que está en otros cuarenta lugares. Un agente sin ese mapa produce algo que compila, pasa el review superficial y reintroduce exactamente el acoplamiento que la migración venía a sacar.
Por eso hoy la mayor parte de mi trabajo con IA no es escribir prompts. Es construir las herramientas que escriben, validan y revisan — y ponerles límites.
Nosotros dirigimos, la IA ejecuta. Pero para dirigir hay que saber qué pedir — y por qué lo que te contesta puede estar mal.
Un agente por etapa, no un agente para todo
Un solo agente genérico hace las cuatro cosas mal. La separación que uso es la misma que aplicaría a cualquier sistema: una responsabilidad por pieza, contratos explícitos entre ellas.
- Planificar. Lee el codebase y devuelve una spec y una lista de tareas ordenada. No toca código. Su salida es un artefacto que puedo discutir antes de que exista un diff.
- Implementar. Recibe la tarea y la spec, no el pedido original. El alcance ya viene decidido.
- Testear. Escribe el comportamiento esperado como test antes de la implementación, y después corre la suite completa.
- Revisar el PR. Lee el diff contra las convenciones del repositorio y marca lo que un reviewer humano marcaría — acoplamiento nuevo, límites cruzados, tests que verifican la implementación en lugar del comportamiento.
Cada uno arranca con su propio contexto. El que revisa no vio cómo se escribió el código, y esa es exactamente la idea: un revisor que participó de la implementación no revisa, confirma.
Darle el mapa, no más contexto
La respuesta fácil es pegarle más código al prompt. Es cara y es peor: más ruido, no más comprensión.
- Navegación semántica en lugar de búsqueda por texto. Un servidor MCP sobre el compilador responde “quién implementa esto”, “quién lo llama”, “qué se rompe si cambia” — sobre símbolos reales, no sobre coincidencias de string.
- Un grafo del codebase que expone la estructura: módulos, dependencias, caminos de llamada. El agente ve la forma del sistema antes de tocar un archivo.
- Memoria entre sesiones, para que una decisión de diseño tomada el martes siga vigente el jueves y no haya que volver a defenderla.
El efecto medible fue de costo: menos tokens por iteración y menos iteraciones, porque la primera respuesta ya está apoyada en la arquitectura real.
Varios intentos en paralelo, uno solo sobrevive
La misma tarea puede resolverse de tres formas distintas, y la diferencia entre ellas casi nunca es de sintaxis: es de dónde pusieron el límite.
El orquestador reparte un mismo pedido a varios agentes, cada uno en su propio worktree de git. Corren aislados, sin verse entre ellos. Al final comparo los candidatos por lo que importa —qué toca el diff, qué tests agrega, si la cobertura sube o baja— y mergeo uno. Los otros se descartan enteros.
Las barreras se ponen antes, no después
Un agente que se autoevalúa siempre aprueba. Las validaciones que sirven son las que no dependen de él:
- Specs que nacen con sus tests. El flujo ata Spec-Driven Development con TDD y BDD: la spec define el comportamiento, ese comportamiento se escribe como test antes que la implementación, y recién entonces el agente implementa. El test no es la verificación del final; es la definición de terminado desde el principio.
- Hooks en el harness. Formateo, lint y typecheck corren solos después de cada edición, no cuando alguien se acuerda.
- Quality gates bloqueantes en el pipeline. Cobertura, contratos y build. Si el gate está rojo, el diff no llega al review humano.
Esto no reemplaza el criterio de diseño: lo protege. Los límites, los contratos y qué no se acopla siguen siendo una decisión mía. Lo que se automatiza es la parte mecánica de sostenerlos.
Qué cambió
- Cerca de un 40 % menos de tiempo en las tareas repetitivas de migración de endpoints y de generación de tests unitarios y de componente.
- Menor costo por iteración, por contexto mejor elegido en lugar de contexto más grande.
- El review humano llega a un diff que ya pasó por las convenciones del repo, así que discute diseño en lugar de estilo.
- Las prácticas se transfirieron al equipo en sesiones internas de capacitación. Una herramienta que solo funciona en mi máquina no es una mejora de proceso.