Lecciones Prácticas del Uso de Agentes de IA en una Base de Código de 100k LOC

Seis Técnicas Concretas para el Desarrollo Asistido por IA a Gran Escala

Un desarrollador documentó recientemente su experiencia usando agentes de IA (Claude Code + Cursor) para construir una capa de API compatible con pandas sobre el motor analítico chDB. El proyecto involucró alinear más de 600 métodos entre dos sistemas y costó aproximadamente $20k en tokens. Aquí están las lecciones específicas y prácticas que compartieron.

Detalles Clave de Implementación

• Mantener un archivo de reglas CLAUDE.md: Dado que la IA no tiene memoria entre sesiones, comprometieron un archivo de reglas al repositorio que contenía cada patrón que la IA seguía entendiendo mal, cada atajo que prohibieron y cada decisión arquitectónica que se estableció. Esto también sirvió como interfaz de colaboración del equipo. Advierten contra dejar que este archivo se convierta en un "manifiesto de 500 líneas" que la IA comenzará a ignorar.
• Observar el razonamiento, no solo la salida: En las primeras etapas, leer cómo piensa la IA es más valioso que lo que produce. Cuando su lógica se desvía de la tuya, pregúntate: ¿estaba equivocado mi pensamiento o simplemente no lo comuniqué correctamente?
• Usar periódicamente un agente sin contexto como crítico: Comenzaron a usar un agente nuevo (claude.ai/code, no la CLI de Claude Code) sin memoria del proyecto para evaluar su trabajo desde una perspectiva crítica y racional externa. Dos palabras clave importan: critical (anular el modo complaciente predeterminado de la IA) y rational (exigir razonamiento estructurado, no solo impresiones).
• Usar el sistema objetivo como oráculo de prueba: Dado que su objetivo era igualar una API existente, encontraron código real en la naturaleza (cuadernos de GitHub/Kaggle), cambiaron una línea de importación y compararon salidas en lugar de inventar casos de prueba.
• Reglas sobre prompts: Observaron cómo la IA toma atajos y escribieron prohibiciones explícitas. Por ejemplo: cuando las pruebas fallaban debido a un desajuste en el orden de las filas, el movimiento favorito de la IA era agregar .sort_values() para hacer que la prueba pasara. Prohibieron esto explícitamente. Los casos que genuinamente no pueden igualarse se marcan como XFAIL, nunca se omiten silenciosamente.
• Sistema de archivos sobre historial de conversación para tuberías multiagente: Orquestan flujos de trabajo multiagente con scripts de Python donde el sistema de archivos es la capa de contexto compartida. Cada agente escribe su trabajo en un directorio de seguimiento, y el siguiente lee lo que necesita. Patrones clave que funcionaron: separación de roles, decisiones estructuradas (APROBAR/RECHAZAR/ESCALAR como JSON para flujo de control determinista) y reversión automática de git en caso de fallo.

El desarrollador señala que la IA sobresale en trabajos a escala—alinear cientos de funciones, generar miles de pruebas, detectar regresiones—pero el juicio ("¿es esto un error o una característica? ¿Es correcta la arquitectura?") sigue siendo responsabilidad del humano.