Pull request reviews con Claude Code, 10 pasos para un workflow de PR que nadie bloquea ya
Los pull requests son el sitio donde el código de IA pasa en silencio o revienta el build. Aquí van 10 pasos para usar Claude Code como segundo par de ojos en los reviews, sin que tu compañero reviewer pierda su trabajo ni se paralice la pipeline.
Abres GitHub por la mañana, tres pull requests esperando. Uno es tuyo, dos de compañeros. El trabajo de reviewer te cuesta una hora cada vez, porque quieres leer el código, comprobar los tests, recorrer el log de CI y al final hacer checkout de la rama en local. Justo este loop es el que Claude Code puede acortar si lo usas bien.
Importante de entrada. Claude Code no reemplaza al reviewer humano. Lo que hace bien es leer por adelantado, estructurar los findings y formular comentarios concretos. Lo que hace mal es juzgar arquitectura y captar contexto de negocio. Lo usamos como primera pasada, no como instancia final.
Asumo que tienes Claude Code instalado en local y que has hecho el mini módulo L1-08 a L1-10 más el playbook git-für-ki-quickstart. Quien todavía no esté firme con branches y pull requests, que mire antes ahí.
Paso 1, hacer checkout de la rama correcta en local
Primera regla. Nunca un review desde el diff de GitHub solo. Necesitas la rama en local, porque Claude Code trabaja con el working tree, no con web diffs.
git fetch origin
git checkout -b review/pr-142 origin/feature/auth-flow
Ponte una rama de review con un prefijo claro. Así puedes después listar todos los reviews abiertos con git branch | grep review/ y nada queda en la rama equivocada.
Si el PR apunta a una base branch distinta de la que tienes, tira primero la base. Si no, lees diffs contra un estado viejo.
Paso 2, hacer visible el diff en el working tree
Claude Code solo ve lo que hay en el working tree. Para que pueda leer el diff del PR, le das el comando como él mismo lo leería.
En el chat de Claude Code:
git diff origin/main...HEAD > .review-diff.txt
Eso escribe el diff completo en un archivo al que luego puedes referenciar. Cuidado, no comitees el archivo. Mete .review-diff.txt en el .gitignore o bórralo tras el review.
Alternativamente puedes pedirle a Claude Code directamente que genere el diff. Él ejecuta el git diff y lee el resultado por sí mismo. Funciona igual, pero con diffs grandes es peor, porque el resultado se queda en el contexto.
Paso 3, empezar con un prompt estructurado
La diferencia entre un AI review usable y uno inservible es el prompt. Genérico "review this PR" te da palabrería genérica. Necesitas una lista de preguntas concretas.
Mi prompt estándar para una pasada de review:
Eres reviewer del diff en .review-diff.txt.
Comprueba en este orden:
1. Hay bugs obvios (off-by-one, null refs, type casts erróneos)
2. Se procesa input del usuario sin validar
3. Los tests nuevos tienen sentido (¿testean lo que deberían testear?)
4. Hay duplicación de código frente al código existente en el repo
5. Se violan convenciones del CLAUDE.md
Output como lista numerada con ruta del archivo, número de línea y propuesta concreta.
Sin halagos, solo findings.
Tengo el prompt en ~/.claude/commands/review-pr.md como slash command. Entonces basta /review-pr y el loop corre.
Paso 4, prensar los findings en una lista
Lo que Claude Code devuelve suele ser demasiado largo. Prosa larga, dos frases por finding, un muro de texto. Comprímelo en una lista escueta.
Prompt de seguimiento:
Convierte los findings en una tabla Markdown:
| Archivo | Línea | Severity | Finding | Propuesta |
Severity es alta, media, baja.
Alta son bugs y problemas de seguridad.
Media son violaciones de convenciones.
Baja son temas de estilo y gusto.
Esta tabla la puedes pegar directa en el comentario del PR de GitHub. El compañero ve de un vistazo qué es importante y qué es gusto.
Paso 5, comprueba cada finding tú mismo antes de postearlo
Este es el paso más importante. No posteas nada sin revisar.
Claude Code alucina en los reviews con regularidad. Afirma que una función no existe cuando vive dos archivos más allá. Se queja de una validación que ya pasa en el middleware. Ve "código duplicado" que no está duplicado para nada.
Yo recorro cada fila de la tabla manualmente. En severity alta siempre abro el archivo y miro. En severity media basta normalmente con leer la línea en el diff. En severity baja a veces puedo fiarme, pero nunca a ciegas.
Lo que no aguanta, fuera. Mejor tres findings buenos que diez con dos alucinados de propina.
Paso 6, correr los tests en local
Antes de postear el comentario del review, corres una vez la suite de tests del repo. A veces el diff se ve limpio, pero la rama está rota igual porque falta una migración o no está puesta una env var.
npm test
# o
pnpm test
# o lo que use el repo
Si los tests fallan, eso va en tu comentario de review. Un PR que rompe los tests en local no es un PR que deba mergearse.
Tip, si tienes el repo en local por primera vez y los tests están rojos, pregunta primero si ya estaban rojos antes. No quieres echarle la culpa al compañero por tests rotos que llevan así dos semanas.
Paso 7, comprobar puntos calientes de performance a vista
El código de IA tiene una manía. Construye gustosamente loops innecesarios, redundancias y patrones O(n^2) porque a primera vista funcionan. Comprueba esto a propósito.
En el diff en .review-diff.txt busca:
- for loops anidados o map dentro de map
- await dentro de un for loop (en vez de Promise.all)
- queries N+1 contra la DB
- operaciones de archivo sync dentro de funciones async
Si encuentras algo, dame archivo y línea y escribe una propuesta mejor.
Eso encuentra el 80 por ciento de los problemas de performance que el reviewer suele pasar por alto. El 20 por ciento restante necesita datos de profiling y no va en la primera pasada.
Paso 8, escribir el comentario con voz humana
Lo que al final pones en GitHub no puede sonar a output de IA. Primero molesta a los compañeros, segundo es más honesto si usas tu propia voz.
Yo cojo la tabla del paso 4, la recorto a los findings que sobrevivieron al paso 5, y escribo un párrafo de introducción yo mismo. Algo como:
He pasado por el diff. Tres findings que bloquearía, dos para discusión. Tests pasan en local. La migración en 003 la miraría otra vez, hay un índice que nunca se usa.
Este párrafo de intro lo escribes tú. El resto de la tabla la puedes copiar del output de Claude, pero respondes por cada entrada.
Paso 9, poner los findings polémicos a discusión, no como bloqueo
A veces no está claro si un finding es de verdad un block o cuestión de gusto. Aquí un buen review marca la diferencia.
En vez de "esto está mal" escribe "yo lo haría distinto, porque...". En vez de "blocks merge" escribe "sin block, pero a mí me valdría un refactor". El compañero no se siente atacado y tú dejas la puerta abierta a una discusión real.
Claude Code formula a menudo de forma directiva. En el setting de review eso es demasiado duro. Al pasarlo a tu comentario, suavizas el tono donde encaje. Fácticamente duro en bugs y seguridad, más suave en estilo y convención.
Paso 10, recoger el setup de review
Último paso que se olvida a menudo. Recoges antes de hacer el siguiente PR.
git checkout main
git branch -D review/pr-142
rm .review-diff.txt
Si no haces eso, después de dos semanas tienes 30 ramas de review en tu repo local, unos cuantos .review-diff.txt por ahí y Claude Code se encuentra en la siguiente sesión un .review-diff.txt viejo que lo confunde.
Tengo un slash command para la limpieza en ~/.claude/commands/review-cleanup.md que borra la rama y quita el archivo de diff. Convierte tres comandos en uno.
Qué viene después
Cuando hayas corrido este loop tres, cuatro veces, te das cuenta de dónde Claude Code es bueno en tu repo y dónde no. En algunos repos sus findings de arquitectura son usables, en otros no. En tests suele ser fiable, en migraciones y código de infra a menudo no.
Si quieres llevar el loop al equipo, mira el playbook Claude Code en equipo, mantener CLAUDE.md juntos. Ahí está cómo repartir el slash command /review-pr de forma que todos obtengan el mismo output.
Quien quiera dar un paso más y dejar correr los reviews automatizados en la pipeline, para ese Claude Code Headless en CI/CD es el siguiente playbook adecuado. Cuidado, los reviews headless tienen otras trampas que los interactivos, es una disciplina propia.