Cómo hice que la IA dejara de alucinar en nuestra base de código
Las herramientas de codificación con IA fallan en proyectos de producción reales. Funcionan bien con código nuevo. Se desmoronan con código antiguo que tiene historial.
Nuestro proyecto fintech tiene tres años de historial. Tiene dos frontends en React, un panel de administración y un backend en FastAPI. La base de datos es compleja, con muchas tablas y joins pesados.
Intentamos usar IA para avanzar más rápido. Fallamos.
Le pedí a la IA que creara una tabla de contactos. Creó nuevas columnas para nombres y correos electrónicos. No se dio cuenta de que ya teníamos estos datos en nuestra tabla de usuarios. Duplicó la información en lugar de usar una clave foránea.
La IA no era tonta. No tenía contexto. Tomó una decisión con información incompleta.
Dejé de preguntar cómo obtener mejor código. Empecé a preguntar qué contexto necesita la IA para tomar buenas decisiones.
Construimos un flujo de trabajo estructurado. La IA es tan buena como el contexto que le proporcionas. Hicimos que ese contexto fuera explícito.
Esta es nuestra configuración:
- Directorio ADR: Creamos una carpeta para los Architecture Decision Records. Estos archivos explican por qué tomamos decisiones específicas. Un archivo le indica a la IA que verifique las tablas existentes antes de crear nuevas. Prohíbe la duplicación de datos de usuario.
- context.md: Este archivo explica nuestros términos específicos. Le indica a la IA cómo se relacionan nuestros términos únicos entre sí.
- plot.md: Proporciona un mapa de alto nivel del proyecto y cómo se conectan las piezas.
- Pruebas obligatorias: Cada nueva ruta de API requiere casos de prueba.
Esto lo cambió todo. En una ocasión, la IA modificó una función de utilidad compartida. El cambio rompió otras ocho partes del sistema. La suite de pruebas lo detectó de inmediato. La IA vio el fallo y corrigió su propio error creando una versión que gestionaba tanto los requisitos antiguos como los nuevos.
Sin pruebas, ese error habría llegado a producción.
Trata a la IA como a un nuevo desarrollador. No culpas a un nuevo empleado por no conocer tu base de código. Le proporcionas documentación y onboarding. Hicimos lo mismo con la IA.
Nuestra estructura:
- docs/context.md: Términos y conexiones del proyecto.
- docs/plot.md: Mapa de alto nivel de la base de código.
- docs/adr/: Reglas específicas como la creación de tablas y la estructura de la API.
Tres reglas para tu equipo:
- Sé específico en los ADR. Usa instrucciones claras en lugar de consejos vagos.
- Haz que la documentación sea autoritativa. Dile a la IA que estas reglas son la prioridad.
- Convierte los errores en reglas. Cada vez que la IA falle, escribe un nuevo ADR.
Este sistema no hace que la IA sea perfecta. Hace que la IA sea predecible. Queremos una base de código donde la IA sea consistente para que el equipo avance más rápido.