La integración de agentes de inteligencia artificial en el flujo de trabajo del desarrollo de software ha dejado de ser una curiosidad experimental para convertirse en una necesidad operativa. Sin embargo, trabajar con un asistente de código durante semanas o meses revela un patrón inevitable: los mismos errores se repiten, la comunicación se vuelve ambigua y la confianza en las respuestas del agente se erosiona sin una estructura clara. En Q2BSTUDIO, donde llevamos años desarrollando aplicaciones a medida para clientes de diversos sectores, hemos observado que la clave no está en el modelo de IA elegido, sino en el protocolo de colaboración que se establece con él. Este artículo presenta un marco original —al que llamamos la Doctrina del Contraparte— compuesto por siete ejes que permiten mantener la coherencia técnica, la auditabilidad a largo plazo y la eficiencia real en proyectos que involucran agentes de IA.
La doctrina no nació de una planificación teórica, sino de la sedimentación de reglas informales tras innumerables fallos recurrentes. Cada eje responde a un modo de fallo específico que identificamos en sesiones reales de desarrollo con Claude, Copilot u otros agentes. Lo que aquí se expone no es una receta cerrada, sino una convención viva que cualquier equipo puede adoptar y adaptar. La idea central es simple: si no documentas cómo te relacionas con tu agente de IA, terminas redescubriendo la misma lección cada semana.
Eje 1: Verificación material — Toda afirmación factual que provenga del agente ('compilación exitosa', 'prueba superada', 'dato confirmado') debe ir acompañada de la evidencia que la respalda en el mismo mensaje. Sin evidencia material, la afirmación carece de valor probatorio. Esto implica exigir la salida en crudo de comandos, trazas SQL, logs de compilación o respuestas HTTP. En Q2BSTUDIO aplicamos esta regla incluso en tareas de IA que involucran datos sensibles: cada número que se reporta debe poder rastrearse hasta su origen. Un simple 'todo ok' sin evidencias es el germen de un error que puede costar horas de depuración.
Eje 2: Adversarialidad bidireccional — Antes de cerrar una decisión arquitectónica significativa (una migración de base de datos, un refactor de más de diez archivos, un compromiso regulatorio), se invoca un agente desafiante que produzca objeciones, pruebas empíricas y un nivel de confianza. El agente principal debe responder a esas objeciones con hechos, no con complacencia. Si el usuario empuja un cambio sin nuevos datos, mantener la posición original es legítimo. Esta práctica evita el sesgo de confirmación y asegura que las decisiones se basen en evidencia, no en persuasión.
Eje 3: Taxonomía de datos y fuente única — Cualquier columna derivada que se almacene debe ser categorizada en el commit que la crea como viva (no se almacena, se crea una vista), instantánea (congelada en un evento de negocio) o caché (almacenada con un refrescador declarado). Sin categoría explícita, la migración es rechazada. Las constantes de negocio se centralizan en un único archivo, y los invariantes irrevocables se protegen a nivel de base de datos (CHECK, triggers), no solo en TypeScript. Este eje es especialmente relevante en proyectos que integran servicios cloud como AWS o Azure, donde la proliferación de datos derivados puede generar inconsistencias difíciles de rastrear.
Eje 4: Disciplina de sesión — Antes de iniciar cualquier proyecto de más de dos archivos, se redacta un ADR (Architecture Decision Record) de una página que incluya la decisión, alternativas descartadas, consecuencias y referencias. El ADR se escribe antes del primer commit, no después. Además, se establece un límite de tres proyectos abiertos en paralelo y se exige un escaneo completo de símbolos antes de proponer nuevas abstracciones. Las recapitulaciones se limitan a cinco líneas; todo lo que exceda se divide en mensajes separados. Esta disciplina evita la saturación cognitiva y mantiene al agente enfocado en el contexto relevante.
Eje 5: Causa raíz, no parche — Antes de aplicar una corrección, se debe identificar la causa raíz. El workaround solo es legítimo si se declara explícitamente tanto en el commit como en un archivo de feedback o ADR. Está prohibido el parche silencioso. Cuando una solución parece demasiado simple para el síntoma observado, se exige el pipeline completo de entrada y salida antes de aceptarla. Este principio también se aplica a patrones: si se confirma un caso, se debe buscar el patrón completo en la base de datos o el código antes de corregirlo. En Q2BSTUDIO, este eje se complementa con prácticas de ciberseguridad, donde un parche mal fundamentado puede abrir vulnerabilidades.
Eje 6: Pedagogía implícita y transversalidad de negocio — En áreas donde el usuario está construyendo experiencia (PostgreSQL, EXPLAIN, cumplimiento fiscal, normativas), se aplica la regla de tres: primera vez se hace por el usuario, segunda se hace con él, tercera la hace él. Se utiliza vocabulario de negocio regulado, no vocabulario de proveedor. Cualquier mención a una norma exige cita textual; sin cita, es marketing. La práctica de un proveedor no es una restricción, debe confrontarse con los ADR del proyecto antes de tratarla como invariante. Este eje es crucial en proyectos de BI/Power BI, donde la terminología financiera o fiscal debe manejarse con precisión.
Eje 7: Auditabilidad a largo plazo — Los ADR se archivan en docs/adr/NNNN-title.md. Las sesiones significativas se registran en un log. El índice de memoria se mantiene en 200 líneas como máximo, con archivos temáticos separados. Cada memoria de feedback vinculada a una deriva activa debe apuntar a una sonda que la confirme. Sin sonda, la memoria se pudre. Se programa una auditoría trimestral donde se lee el índice línea por línea preguntando '¿esto sigue siendo cierto?'. La propia doctrina se versiona y audita como un ADR. Este eje es el que estructura todos los demás y asegura que el conocimiento no se pierda cuando el agente cambie o el equipo rote.
Implementar estos siete ejes no es cuestión de un día. Se recomienda empezar por los tres mínimos: verificación material (el más barato y de impacto inmediato), causa raíz (el más protector) y auditabilidad a largo plazo (el que sostiene el resto). Durante las primeras sesiones, basta con producir al menos un archivo de feedback fechado. En un mes, esos archivos se convierten en la materia prima de una doctrina sedimentada. En Q2BSTUDIO, hemos visto cómo equipos que adoptan este enfoque reducen el tiempo de depuración en un 30% y mejoran la consistencia del código en proyectos que integran múltiples tecnologías, desde automatización de procesos hasta inteligencia artificial aplicada.
La Doctrina del Contraparte no es un dogma, sino una convención que se revisa continuamente. Cada eje puede desactivarse durante un sprint si se asume explícitamente el coste. El día que un eje deje de servir, se retira; el día que aparezca un nuevo modo de fallo recurrente, se añade un octavo. La disciplina de la coherencia larga no es un método para la productividad corta, sino la condición para que el código generado con IA preserve su integridad a medida que el proyecto crece. En un entorno donde la velocidad de generación de código se duplica cada trimestre, tener un protocolo de colaboración sólido marca la diferencia entre un prototipo funcional y un sistema mantenible.
