Code review con IA: mandan las instrucciones, no la herramienta

En 2024, GitHub documentó públicamente algo que muchos equipos de desarrollo ya sospechaban: subir de versión el modelo detrás de Copilot Code Review no disparaba la calidad de los comentarios de revisión al mismo ritmo que mejoraba la escritura de código. La compañía introdujo entonces las instrucciones personalizadas de repositorio, un archivo `.github/copilot-instructions.md` donde el equipo describe sus convenciones, su arquitectura y sus prioridades de revisión en lenguaje natural. La idea no es nueva en ingeniería de prompts, pero sí lo es llevarla al flujo de trabajo diario de un equipo que revisa decenas de pull requests por semana. Lo que cambió la percepción de utilidad de la herramienta no fue el salto de un modelo a otro, sino ese archivo de contexto que el equipo tardaba una tarde en escribir. Hemos visto el mismo patrón en clientes que probaron primero GitHub Copilot y después herramientas como CodeRabbit o Graphite Reviewer: la sensación de 'esto no entiende nuestro código' se repite con cualquier proveedor si nadie le explica las reglas del juego. El problema nunca fue de qué IA se trataba, era de qué sabía esa IA sobre el equipo.

Ese dato de productividad al escribir código no es el mismo problema que revisar código ajeno, y ahí está la primera confusión habitual. Generar una función nueva es una tarea con contexto local: el modelo ve lo que hay delante y completa un patrón razonable. Revisar un pull request es una tarea con contexto histórico: hay que saber por qué el equipo evita cierta librería, qué servicio es intocable por una migración pendiente, o qué patrón de nombres se decidió hace dos años tras un incidente de producción. Un modelo más grande escribe mejor autocompletado porque el patrón está en el código que tiene delante. Un modelo más grande no revisa mejor por sí solo porque la información que necesita no está en el diff, está en la cabeza de alguien del equipo que nunca la escribió en ningún sitio. Esa es la distinción que la mayoría de comparativas de 'mejor IA para code review' pasan por alto.

Cuando una IA revisa un pull request, normalmente ve el diff, quizá algunos archivos relacionados y poco más: no ha estado en el incidente de producción de hace dos años, no sabe que ese endpoint se reescribió tres veces por un problema de concurrencia, ni que el equipo decidió no usar cierta dependencia después de una vulnerabilidad conocida. Cada nuevo pull request es, para el modelo, un arranque en frío: no acumula memoria entre revisiones salvo que alguien se la dé explícitamente. Aumentar el tamaño del modelo o su ventana de contexto no resuelve esto, porque el problema no es cuánto puede procesar el modelo sino qué información existe para procesar. Si esa decisión de arquitectura nunca se escribió en ningún archivo, ni el modelo más avanzado del mercado puede intuirla a partir del código. Esto explica por qué equipos con stacks parecidos y el mismo proveedor de IA tienen experiencias radicalmente distintas: el que documenta sus decisiones obtiene revisiones útiles, el que no, obtiene comentarios de estilo genéricos que cualquier linter ya hacía.

El punto ciego que ningún modelo resuelve solo

Este punto ciego no es un defecto temporal que la próxima versión del modelo vaya a arreglar, es estructural: ningún sistema puede razonar sobre información que no recibe. La solución no pasa por esperar al siguiente modelo de moda, pasa por tratar el contexto de revisión como un activo de la empresa que hay que mantener, igual que se mantiene la documentación técnica o el runbook de incidentes. En la práctica esto significa capturar por escrito las decisiones que hoy solo viven en la memoria de dos o tres personas senior del equipo. Cuando esas personas cambian de proyecto o se van, ese conocimiento desaparece también para los revisores humanos, no solo para la IA — la instrucción escrita protege contra ambos escenarios. Por eso el archivo de instrucciones no es un capricho de configuración de IA, es documentación de arquitectura que la mayoría de PYMEs nunca llegó a escribir con o sin inteligencia artificial de por medio.

• Convenciones reales del equipo, no una guía de estilo genérica copiada de internet
• Decisiones de arquitectura documentadas junto al motivo, no solo la regla (ej.: 'no usar esta librería, causó un incidente de facturación')
• Lista explícita de patrones o dependencias prohibidas y su porqué
• Ejemplos reales de comentarios de revisión que el equipo considera útiles y otros que considera ruido
• Nivel de severidad esperado según el tipo de código: no es lo mismo tocar el módulo de pagos que un script interno de utilidades

Errores típicos al escribir instrucciones para IA

• No copiar una guía de estilo genérica de internet como instrucción principal
• Actualizar el archivo de instrucciones cada vez que ocurra un incidente evitable
• Versionar el archivo de instrucciones en git, igual que el código que revisa
• Revisar cada trimestre si las instrucciones siguen reflejando el estado real del proyecto
• No delegar su redacción a alguien sin contexto histórico del equipo

Aquí conviene ser honestos, incluso cuando no ayuda a vender más servicio: ni la mejor instrucción convierte una IA en un revisor senior. Las instrucciones reducen el ruido y alinean los comentarios de estilo y convención con la realidad del equipo, pero no dotan al modelo de la capacidad de pensar como un atacante, ni de intuir un caso de negocio que nadie documentó nunca. Hemos visto revisiones con IA muy bien configuradas que aun así dejan pasar una condición de carrera sutil o una validación de permisos incompleta, precisamente porque detectarlas exige el mismo razonamiento adversarial que un pentester aplica a propósito, no un patrón que se pueda describir en un archivo de texto. Por eso no recomendamos sustituir la revisión humana en código que toca pagos, autenticación o datos personales, por muy bien instruido que esté el asistente. Lo que sí recomendamos es usar la IA para absorber el volumen de comentarios menores y dejar al revisor humano concentrado en lo que de verdad requiere criterio. Automatizar mal esa frontera es, de las dos decisiones, la que más cuesta deshacer después.

La IA no revisa peor código con el paso de las versiones, revisa el mismo código con la misma ignorancia sobre por qué tu equipo decidió lo que decidió. Ese hueco no lo llena un modelo mejor, lo llena una instrucción escrita por alguien que estuvo en la reunión donde se tomó la decisión.

Empezar no requiere un proyecto de meses ni elegir antes el proveedor perfecto de IA. Basta con elegir un repositorio activo, reunir a las dos o tres personas que llevan más tiempo en él, y anotar durante una hora las decisiones que hoy solo están en su cabeza: qué no se debe tocar, qué ya se intentó y falló, qué patrón es obligatorio y por qué. Ese primer archivo de instrucciones no será perfecto, y no hace falta que lo sea: se corrige con el primer incidente que revele un hueco. Lo importante es tratarlo como un documento vivo que crece con cada error evitable, no como una tarea de configuración que se hace una vez y se olvida. Cambiar de modelo de IA cuando salga el siguiente será, en la mayoría de los casos, la parte menos determinante de todo el proceso.