Revisor de Pull Requests con IA

El problema

Revisar Pull Requests a fondo es lento, y en equipos pequeños casi siempre se queda en un «LGTM» rápido. Los bugs sutiles, las vulnerabilidades y los problemas de estilo se cuelan porque nadie tiene tiempo de mirarlos con calma.

Nos propusimos construir en un equipo de siete una herramienta web donde pegas la URL de un PR de GitHub y recibes un informe visual con lo que un revisor humano debería mirar, ordenado por gravedad.

La solución: interfaz

Una web en React donde pegas la URL del PR y pulsas Analizar. El resultado son tarjetas por hallazgo, clasificadas en crítica, alta, media o baja, con el fichero, la línea y la explicación. Si el PR está limpio, lo dice con su propia pantalla. Si algo falla (el PR no existe, GitHub limita las peticiones o el modelo no responde), el usuario recibe un mensaje claro de qué ha pasado y qué puede hacer.

La solución: arquitectura

URL del PRWeb en React

FastAPI

download_diffAPI REST de GitHub

validate_constraintsMáximo 5 ficheros y 1.000 líneas por PR

Tres análisis en paralelo · Llama 3.3 70B en Groq

bug_agent

security_agent

style_agent

consolidationElimina duplicados y asigna la gravedad

JSON con contrato PydanticLo pinta React en tarjetas

Un grafo de LangGraph descarga el diff, comprueba los límites y lanza tres análisis especializados en paralelo (bugs, seguridad y estilo) sobre Llama 3.3 70B en Groq. Un nodo final de consolidación elimina duplicados, asigna la gravedad y devuelve un JSON con contrato Pydantic. Todo queda trazado en LangSmith.

Lo que construí yo

• La integración con GitHub. El nodo download_diff y las herramientas que hablan con la API de GitHub: validación de la URL, descarga del diff, conteo de ficheros y líneas cambiadas, y timeouts.
• El agente de bugs y la ejecución en paralelo del grafo, con los scripts de verificación contra PRs reales y contra diffs con bugs sembrados a propósito.
• Los límites del MVP (validate_constraints): como máximo 5 ficheros y 1.000 líneas por PR, para que el análisis sea rápido y el coste predecible.
• El manejo de errores de punta a punta. Diseñé el módulo de errores: cada fallo de GitHub o de Groq se traduce en un código HTTP, un código estable y un mensaje seguro para el usuario, mientras el detalle técnico solo va a los logs y a LangSmith. En el frontend, el componente que muestra esos errores al usuario.
• El arranque del frontend con React, Vite y Tailwind, y la decisión de cambiar Next.js por React + Vite en la documentación de arquitectura.
• Después del curso seguí mejorándolo en mi propio fork: robustez ante URLs con www, token de GitHub ausente y respuestas inesperadas de Groq, y el renombrado a Pullsight.

Decisiones técnicas

• Tres análisis especializados, no un prompt gigante. Cada uno tiene un único foco y su propio prompt, lo que reduce falsos positivos y permite mejorar uno sin romper los demás.
• Errores que no tumban el grafo. Los tres análisis corren en el mismo paso; si GitHub o Groq caen, pueden fallar los tres a la vez. Un reducer en el estado se queda con el primer error en vez de abortar el grafo, y el usuario recibe un único mensaje coherente.
• Mensaje seguro para el usuario, detalle para el desarrollador. Nunca se muestra una traza ni un mensaje interno en la interfaz.
• Límites explícitos en los requisitos. Mejor rechazar un PR enorme con un mensaje claro que devolver un análisis a medias.

Stack desglosado

• Backend: FastAPI + Pydantic (contrato JSON documentado en la arquitectura).
• IA: LangGraph, Groq (Llama 3.3 70B) y LangSmith para trazas y ajuste de prompts.
• Frontend: React + Vite + Tailwind CSS, con modo oscuro.
• Integración: API REST de GitHub con httpx.
• Calidad: 70 tests en el backend y una batería de pruebas funcionales documentada.
• Proceso: requisitos, arquitectura y estado del arte redactados antes de programar, ramas por feature y revisión de PRs antes de mergear a develop.

Resultados y aprendizajes

Lo que funcionó: trabajar con contratos claros. Con el JSON de respuesta definido desde el primer día, frontend y backend avanzaron en paralelo sin bloquearse, y conectarlos fue casi inmediato.

Lo que aprendí: a trabajar en un equipo real con Git Flow, revisiones de código, reparto de roles y documentación compartida. Y que el manejo de errores no es un detalle: es lo que separa una demo de una herramienta que alguien puede usar.

Trabajo futuro: comentar los hallazgos directamente en el PR de GitHub, soportar PRs grandes troceando el diff y dejar elegir el modelo de lenguaje.