Actualmente, muchos equipos que utilizan la inteligencia artificial para revisar código simplemente apuntan un modelo al diff (los cambios realizados en un código) y piden un veredicto sobre si esos cambios son correctos. El humano se limita a revisar rápidamente y aprobar o rechazar. Este enfoque, aunque automático, presenta serias limitaciones.
El modelo analiza todas las líneas sin cansarse y aplica un estándar uniforme en cada solicitud de extracción (pull request). Sin embargo, carece del conocimiento específico sobre los estándares propios de cada base de código. Incluso con instrucciones precisas, la IA no siempre sigue fielmente las reglas definidas por el equipo.
“El juicio requiere intención, y la responsabilidad necesita de una persona.”
La inteligencia artificial no está al tanto de las decisiones previas, no posee el contexto necesario para cuestionar la construcción del código y no puede asumir responsabilidad. Por tanto, un simple diff no le puede brindar lo que necesita la revisión en términos de juicio y contexto.
Entonces, ¿cómo sería una revisión de código adecuada donde la verificación la realicen agentes de IA, pero las decisiones las tomen personas? En Aviator han desarrollado esa metodología en su herramienta Aviator Verify, que transforma las revisiones para que se basen en la intención y reglas claras que la IA comprueba, dejando a los humanos la última palabra.
Anatomía de una revisión basada en intención
En Aviator Verify, cada cambio se somete a dos capas de comprobación: los criterios de aceptación, que definen qué debe lograr el cambio, y los invariantes, reglas estrictas y permanentes que definen los estándares básicos del equipo o la organización, siempre aplicables sin importar la modificación.
Los criterios sin invariantes suponen confiar en la memoria de los desarrolladores, lo que conduce a errores frecuentes. En cambio, invariantes sin criterios provocan que el código cumpla reglas pero no necesariamente cumpla con el propósito real del cambio. Por ello, ambos se combinan para validar exhaustivamente las propuestas.
La revisión consta de siete elementos clave que integran ambos niveles de verificación y dejan la toma de decisiones a las personas:
- Invariantes: reglas definidas antes de cualquier cambio que resumen las normas del equipo, extraídas de revisiones previas.
- Intención y criterios de aceptación: definidos durante la sesión de codificación, explican el propósito y el comportamiento esperado del cambio.
- Decisiones clave: documentación de las elecciones técnicas hechas durante la codificación y quién las tomó.
- Plan de pruebas: escenarios derivados de los criterios e invariantes, que un agente usa para validar el comportamiento.
- Evidencias: pruebas tangibles obtenidas en entornos de ejecución, como capturas, estados de bases de datos y logs, que soportan cada veredicto.
- Revisión: realizada por una persona que evalúa intención, decisiones y evidencias, y no el código directamente.
- Actualización de invariantes: después de la integración, las reglas se revisan para perfeccionarlas según excepciones y retroalimentación recurrente.
1. Invariantes: las reglas fundamentales
Normalmente, las reglas que guían las revisiones viven en la cabeza de los desarrolladores senior y se reflejan solo en comentarios ocasionales. Por ejemplo: «usar el tipo Money para cantidades monetarias», «no modificar directamente la tabla de usuarios», o «todas las rutas de error deben incrementar contadores».
Estas reglas, cuando se documentan como invariantes, se aplican sistemáticamente a todos los cambios correspondientes. Aviator Verify extrae estas normas automáticamente de historiales de pull requests, comentarios, archivos CONTRIBUTING.md y otros documentos relevantes, también puede etiquetarse manualmente durante una revisión o conversación. Así se forma un registro vivo de estándares que corrige patrones recurrentes de errores.
Para que un invariante sea útil debe contar con:
- Propiedad clara: los equipos responsables revisan y aprueban cada regla antes de que entre en vigor.
- Redacción enfocada en resultado: la regla describe el resultado esperado y no detalles de implementación, para resistir cambios estructurales sin perder validez.
- Ámbito apropiado: cada regla se aplica solo donde tiene sentido para evitar ruido o falsos positivos.
2. Intención y criterios de aceptación
La intención y el criterio de aceptación idealmente se definen al inicio con especificaciones, pero en la práctica se pierden o queda desfasadas conforme se avanza en la implementación. La solución es capturarlos durante la propia codificación, en tiempo real, cada vez que surge una toma de decisiones con la que el agente interactúa.
Antes de abrir la petición de integración, el propio sistema extrae, presenta y permite corregir esta información para que refleje con precisión el objetivo y funcionamiento esperado del cambio.
3. Decisiones clave
Los puntos críticos donde hubo opciones técnicas (por ejemplo, elección de ubicación de estados, tratamiento ante fallos o uso de helpers) quedan documentados junto a la intención, con identificación clara del decisor (humano o agente). Esto permite a los revisores dar sentido al código sin tener que inferir por sí mismos.
4. Plan de pruebas
Al someter la propuesta, Aviator Verify fusiona intención, criterios e invariantes para generar un plan de escenarios que un agente verificará activamente para validar que el código se comporta según lo esperado.
5. Evidencias tangibles
La revisión debe ir más allá de opiniones: la verificación se realiza desde un entorno de prueba donde se recopilan datos como capturas de pantalla, registros de bases de datos, logs de servidor y consolas, y resultados detallados de cada criterio y regla. En cambios de interfaz, el agente puede incluso interactuar con la UI para confirmar que las modificaciones funcionan.
6. La revisión final
Aquí vuelve la acción humana. El equipo revisa la intención, las decisiones tomadas y la evidencia concreta, sin necesidad de leer línea a línea el código. Solo si algo no encaja se consulta el diff. Esta aproximación transforma la revisión en una evaluación eficiente y fundamentada, con responsabilidad clara sobre la aprobación o solicitud de ajustes.
7. Actualización continua de invariantes
Los aprendizajes de cada revisión se conservan mediante mecanismos para dejar constancia de excepciones justificadas o revisiones a las reglas. Por ejemplo, si una invariante falla repetidamente y se renuncia a ella con razones válidas, el equipo reevaluará y ajustará esa norma para mejorarla.
Comenzar la transición
No se trata de implementar todo de golpe. Lo recomendable es empezar por definir las invariantes, la parte menos costosa y que puede extraerse rápidamente del historial de pull requests. Durante el primer mes, el equipo percibirá un doble trabajo al convivir ambas formas. Pero en el segundo mes, las invariantes comienzan a detectar errores antes y, al tercero, las revisiones se basan en la intención, decisiones y evidencias con apenas consulta al código.
La revisión de código que su equipo ya realiza contiene reglas esperando ser formalizadas. Aviator Verify las convierte en invariantes, verifica cada cambio contra ellas y deja las decisiones en manos de los desarrolladores, potenciando así un proceso de revisión más fiable, eficiente y responsable.
Pruebe a generar las invariantes de su equipo con una cuenta gratuita de Aviator Verify y manténgalas incluso si decide no continuar usando la herramienta.
