Cómo construir un revisor de código con rúbrica

Construir un revisor de código con IA empieza por la rúbrica, no por el prompt. Si defines primero las categorías de hallazgo que buscas, tu revisor tendrá criterio real y no se limitará a comentar el estilo. Esto es para quienes automatizan revisiones de pull requests dentro de un pipeline de continuous integration.

Aquí cambia la lógica que veníamos usando. Hasta ahora la IA generaba código; a partir de este punto, la IA juzga. Vamos a construir un revisor que tome un pull request, analice los cambios y emita un veredicto sobre su estado.

Por qué empezar por la rúbrica y no por el prompt

Hay una regla que no vamos a saltarnos: no arrancamos por el prompt, arrancamos por la rúbrica. Un revisor sin rúbrica escribe tests, pero carece de criterio.

¿Y qué pasa sin ese criterio? Sin alcance definido, la IA elige lo que le parece importante y, por defecto, eso es el estilo, que es lo más superficial y abundante.

¿Qué es una rúbrica en revisión de código? Es una lista de categorías de hallazgo nombradas, cada una con su definición. Antes de escribir el prompt, decides qué tipo de problema quieres que el revisor busque en tu proyecto.

Nombrar las categorías hace tres cosas concretas:

• Le dice a la IA dónde mirar.
• Te permite medir el acuerdo por categoría más adelante.
• Convierte una buena revisión desde una sensación en un checklist auditable.

Ese último punto es clave: pasas de "me parece que está bien" a un criterio verificable.

Cuáles son las seis categorías de la rúbrica

Para este ejercicio definimos seis categorías de hallazgo, cada una con su definición clara [00:52]:

• Corrección: evalúa si el código hace lo que dice. Por ejemplo, en un refund, si actúa correctamente cuando se excede un monto.
• Seguridad: evalúa si se abre una vulnerabilidad, como SQL por concatenación o una autorización ausente.
• Rendimiento: evalúa si escala o se degrada, por ejemplo una consulta muy intensa en la liquidación.
• Tests faltantes: evalúa si el cambio viene o no acompañado de pruebas.
• Estilo: evalúa convenciones, legibilidad, nombres y formatos.
• Documentación: evalúa si los cambios públicos están documentados, como el docstring de un endpoint.

Con estas categorías el revisor sabe exactamente qué buscar en cada diff.

Cómo preparar las ramas para revisar los cambios

El ejercicio usa dos ramas para comparar. La idea es partir de una base sana y medir solo el riesgo que introduce el cambio nuevo [01:56].

• La rama Develop está limpia, con muchos tests funcionales. Incluso se le aplicó mutation testing y casi todos los mutantes murieron, lo que la vuelve muy estable.
• La segunda rama tiene cambios respecto a Develop y sabemos que trae problemas: autorización ausente, una función del refund ignorada, tests faltantes y sin documentación.

No se crea un pull request real en GitHub todavía. En su lugar, le pedimos al revisor que analice los diffs internos. Para verlos, te paras en la rama actual dentro de Graph y usas la opción compare with develop [02:33].

¿Se necesita un PR en GitHub para revisar con IA? No al inicio. Puedes pedirle al revisor que analice los diffs entre tu rama actual y Develop de forma local, sin crear un PR real.

La misión aquí no es corregir el código, sino que el revisor identifique correctamente esos problemas y analice bien los cambios.

Cómo embeber la rúbrica en un prompt revisor de PRs

El siguiente paso es dejar la rúbrica dentro de un prompt y guardarlo en un archivo llamado Reviewer para poder versionarlo. La intención es que este prompt sea un activo del repositorio [03:29].

El prompt le da instrucciones muy acotadas al revisor:

• Revisa los cambios de la rama actual contra Develop y trata el diff como un pull request hacia Develop.
• Usa solo el diff mostrado y los archivos incluidos; no inventes información de GitHub, CI ni historial remoto.
• No reescribas el código ni propongas refactors grandes.
• Para cada categoría, indica si hay hallazgos; si los hay, cita el archivo y la línea, explica por qué importa y sugiere una corrección breve.
• Si una categoría no tiene hallazgos claros, escribe "sin hallazgos".

Esa restricción de citar archivo y línea es lo que vuelve el resultado accionable y no una opinión vaga.

Qué devuelve el revisor al correr el prompt

Al correr el prompt en Cloud, unos minutos después aparece la revisión organizada [05:20]. El resultado agrupa los hallazgos por las categorías especificadas: seguridad, corrección y las demás quedan separadas, incluso las que no tienen hallazgos.

Y aquí viene lo interesante: aparecieron justo los problemas esperados, con las funciones específicas citadas y algunas líneas también referenciadas. La revisión detecta el riesgo que introdujo el cambio sin salirse del alcance.

¿Por qué la rúbrica evita que la IA solo comente estilo? Porque al nombrar categorías como corrección, seguridad y tests faltantes, obligas a la IA a mirar ahí primero, en vez de quedarse en lo más superficial y abundante.

Hay un detalle que todavía queda pendiente: la revisión está escrita en prosa. Para un humano eso funciona, pero un pipeline de continuous integration no puede consumir prosa ni actuar sobre ella [06:33].

Por eso el siguiente paso será exigirle al prompt que hable en un idioma que ese pipeline sí pueda consumir. ¿Cómo transformarías tú una revisión en prosa a un formato que CI pueda procesar? Déjalo en los comentarios.