Método CIV: cómo construimos software con IA sin perder el control
Llevamos dos años construyendo ShephERP con inteligencia artificial escribiendo la mayor parte del código. Por el camino hemos aprendido que el cuello de botella nunca fue el modelo. Era todo lo demás. A esa forma de trabajar la hemos puesto nombre: método CIV . El problema que nadie cuenta La promesa de la IA en desarrollo es real: un agente escribe en veinte minutos lo que antes costaba dos días. Lo que casi nadie cuenta es lo que pasa en la semana seis. Un modelo de lenguaje es un ejecutor asombrosamente rápido y asombrosamente literal. Sin contexto, inventa : si no le has dicho que los socios con la cuota vencida pierden el descuento, aplicará el descuento, porque es lo más razonable. Y sin límites, rompe : arreglará el bug que le pediste y, de paso, tocará otras cuatro cosas que nadie le pidió. El resultado es un proyecto que arranca a una velocidad espectacular y se atasca a los dos meses, con miles de líneas que nadie ha revisado y un equipo que ya no se atreve a tocar nada. Multiplicar la velocidad de escribir código sin multiplicar la capacidad de verificarlo no es productividad: es deuda a velocidad de máquina. No se desarrolla más rápido con mejores prompts , sino con mejor contexto y mejores límites. Tres pilares: Contexto, Iteración, Verificación CIV son las tres cosas que hay que poner alrededor del agente. No son fases que se recorren una detrás de otra: funcionan siempre a la vez, y si quitas una, el sistema se cae. C — Contexto: la documentación es el código fuente En un proyecto CIV, la carpeta docs/ existe antes que el código. Dentro está todo: el negocio del cliente, su vocabulario exacto, las reglas numeradas una a una, las decisiones técnicas con su fecha y sus alternativas descartadas, y el acta de cada reunión escrita el mismo día . No documentamos para auditar ni para quedar bien. Documentamos porque es literalmente la entrada del ejecutor . Un acta de reunión es el activo más valioso que existe para una IA, porque contiene lo único que ningún repositorio puede deducir: la intención. El código dice qué hace el sistema; solo el acta dice por qué se hizo así y qué se rompe si lo cambias. De ahí sale nuestro primer principio, que es también el más incómodo: si no está escrito, no existe . Una decisión que solo vive en una llamada no es una decisión, es un rumor que el agente no puede respetar. I — Iteración: un ticket es un prompt El trabajo baja en tres alturas —épica (un trimestre), hito (lo que se puede enseñar en dos semanas) y tarea (lo que cabe en una sesión)— y aterriza en tickets escritos para alguien que no estuvo en la conversación, no recuerda nada y no va a preguntar . Eso cambia por completo cómo se escribe un ticket. Nada de «arreglar el filtro». Pasos con datos reales, la URL exacta, una captura anotada con una flecha sobre lo que está mal, la petición y la respuesta pegadas, el resultado esperado, los criterios de aceptación en checklist y —la línea que más dinero ahorra— qué NO hay que tocar . Lo llamamos Definition of Ready para IA , y tiene una regla de oro: si el agente tiene que preguntar algo para poder empezar, el ticket estaba mal escrito y vuelve a quien lo redactó. No es burocracia. Un ticket incompleto no se detiene: se completa solo, con la suposición más probable del modelo. Y la suposición más probable casi nunca es la regla de negocio de tu cliente. Cada tarea recorre después seis pasos siempre iguales: leer, planear, vallar, ejecutar, verificar y devolver. El más importante es el segundo: el plan se aprueba antes de la primera línea de código . Corregir un plan cuesta un minuto; corregir una tarde cuesta una tarde. V — Verificación: primero la valla, después se suelta Aquí conviene deshacer una confusión muy común, porque de ella depende todo lo demás. Mucha gente habla de «tests unitarios, e2e y Cypress» como si fueran tres cosas del mismo tipo. No lo son: se están mezclando dos ejes distintos. Uno es el nivel —cuánto sistema real ejercitas—, y otro es la herramienta con la que lo ejercitas. Cypress no es un nivel: es una herramienta para el nivel de extremo a extremo de interfaz. Y «extremo a extremo» tampoco es uno solo: probar la API completa y probar la aplicación en un navegador son cosas distintas, con coste y utilidad distintos. En CIV son seis niveles, del más barato al más caro: tipos y estilo, unitarios, integración, extremo a extremo de API, extremo a extremo de interfaz y humo en producción. La pregunta que decide dónde va cada test es siempre la misma: ¿cuál es el trozo más pequeño donde este fallo se puede detectar? Un descuento mal calculado es un test unitario, aunque lo descubrieras comprando en la tienda. Por encima de todo eso, cobertura por encima del 95% y la regla que lo sostiene: el trinquete . Los umbrales solo suben. Nunca bajan, nunca «temporalmente». La deuda que ya existía se congela con una línea base y se paga por escalones; la deuda nueva se bloquea el mismo día. Y ningún bug se cierra hasta que deja detrás el test que lo habría detectado: ningún bug muere sin testigo . Por qué esto se paga solo Un proyecto normal se degrada: cada mes cuesta más tocarlo. Un proyecto CIV tiende a lo contrario, y la razón es concreta. El contexto crece, así que cada tarea nueva llega con más terreno resuelto. La valla crece, así que cada cambio es menos arriesgado que el anterior. Y el coste de incorporar a alguien —o a otro agente— baja, porque incorporarse es leer una carpeta en orden. Medimos siete cosas, pero hay una que casi nadie mide y que lo dice todo: la tasa de ticket limpio , el porcentaje de tickets que el agente resuelve sin tener que repreguntar. Si esa cifra baja, el problema no está en el modelo que uses. Está en tu contexto y en cómo escribes los tickets. Lo que CIV no es No es vibe coding . No es cobertura de escaparate —tests que ejecutan mucho y no comprueban nada—. No son documentos ceremoniales que nadie actualiza, que con IA son peor que no tener ninguno, porque el agente sí los lee y se los cree. No son atajos que llevan seis meses siendo permanentes. Y, sobre todo, no es soltar a un agente sin correa y llamarlo autonomía. CIV no nació en una pizarra: salió de construir un ERP completo con IA, equivocarnos y anotar por qué. Es lo que hacemos todos los días. Contexto. Iteración. Verificación. Quita uno de los tres y no es CIV: es suerte.