Revisión de PR con Claude Code: pre-revisar diffs más rápido y seguro

Por qué el tiempo de revisión de PR se alarga

Las revisiones de PR casi nunca se eternizan porque el código sea "difícil". Se alargan porque el revisor tiene que reconstruir la intención, el riesgo y el impacto a partir de un diff que muestra cambios, no la historia completa.

Una edición pequeña puede tocar dependencias ocultas: renombrar un campo y se rompe un informe, cambiar un valor por defecto y la conducta cambia, ajustar una condición y cambia el manejo de errores. El tiempo de revisión crece cuando el revisor tiene que buscar contexto, ejecutar la app localmente y hacer preguntas de seguimiento solo para entender qué pretende hacer el PR.

También hay un problema humano de patrón. La gente hojea diffs de formas previsibles: nos centramos en el cambio "principal" y pasamos por alto las líneas aburridas donde se esconden errores (comprobaciones de límites, manejo de null, logging, limpieza). Tendemos además a leer lo que esperamos ver, así que los errores por copiar y pegar y las condiciones invertidas pueden pasar desapercibidos.

Una buena pre-revisión no es un veredicto. Es un segundo par de ojos rápido y estructurado que apunta dónde debería frenar un humano. El mejor resultado es:

• un resumen en lenguaje llano de lo que cambió
• puntos de riesgo específicos (archivos, funciones, suposiciones)
• notas de legibilidad (nombres, flujo de control confuso)
• preocupaciones de corrección (lógica, manejo de errores, consistencia de datos)
• casos límite que vale la pena probar (entradas, tiempo, permisos, estados vacíos)

Lo que no debe hacer: "aprobar" el PR, inventar requisitos o adivinar el comportamiento en tiempo de ejecución sin evidencia. Si el diff no incluye suficiente contexto (entradas esperadas, restricciones, contratos de quien llama), la pre-revisión debe indicarlo y listar exactamente qué falta.

La ayuda de IA es más fuerte en PRs de tamaño medio que tocan lógica de negocio o refactors donde el significado puede perderse. Es más débil cuando la respuesta correcta depende de un conocimiento organizativo profundo (comportamientos heredados, peculiaridades de rendimiento en producción, reglas internas de seguridad).

Ejemplo: un PR que "solo actualiza la paginación" suele ocultar páginas off-by-one, resultados vacíos y desajustes en el orden entre API y UI. Una pre-revisión debería sacar esas preguntas antes de que un humano pierda 30 minutos redescubriéndolas.

Qué pedirle a Claude en una pre-revisión

Trata a Claude como un revisor de primera pasada, rápido y exigente, no como quien decide si el PR se publica. El objetivo es sacar problemas temprano: código confuso, cambios de comportamiento ocultos, tests faltantes y casos límite que olvidas cuando estás inmerso en el cambio.

Dale lo que un revisor humano justo necesitaría:

• el objetivo del PR (1 a 3 frases)
• lo que no debe romperse (forma de la API, compatibilidad hacia atrás, presupuesto de rendimiento, reglas de seguridad)
• cualquier restricción o tradeoff especial (plazos, despliegue parcial)
• los hunks del diff relevantes, con suficiente código alrededor para entender la intención

Si el PR toca un área conocida de alto riesgo, dilo desde el principio (auth, facturación, migraciones, concurrencia).

Luego pide salidas en las que puedas actuar. Una petición sólida se ve así:

• Resume lo que cambió en lenguaje llano.
• Señala problemas de legibilidad (nombres, estructura, sorpresas, patrones inconsistentes).
• Identifica riesgos de corrección (manejo de null, rutas de error, off-by-one, desajustes en la forma de los datos).
• Lista casos límite y modos de fallo (timeouts, reintentos, entradas vacías, actualizaciones parciales).
• Sugiere tests faltantes y qué prueba cada test.
• Genera una lista corta de verificación para el revisor y de 5 a 10 "preguntas para hacer" antes del merge.

Mantén al humano a cargo forzando claridad sobre la incertidumbre. Pide a Claude que etiquete los hallazgos como "cierto a partir del diff" vs "necesita confirmación", y que cite las líneas exactas que dispararon cada preocupación.

Prepara el diff y el contexto antes de pedirle

Claude es tan bueno como lo que le muestras. Si pegas un diff gigantesco sin objetivo ni restricciones, obtendrás consejos genéricos y te perderás los riesgos reales.

Empieza con un objetivo concreto y criterios de éxito. Por ejemplo: "Este PR añade limitación de tasa al endpoint de login para reducir el abuso. No debe cambiar la forma de la respuesta. Debe mantener la latencia media por debajo de 50 ms."

A continuación, incluye solo lo que importa. Si cambiaron 20 archivos pero solo 3 contienen la lógica, céntrate en esos. Incluye contexto alrededor cuando un fragmento sería engañoso, como firmas de funciones, tipos clave o configuración que cambia el comportamiento.

Finalmente, sé explícito sobre las expectativas de testing. Si quieres tests unitarios para casos límite, un test de integración para un camino crítico o una comprobación manual en la UI, dilo. Si faltan tests a propósito, explica por qué.

Un "pack de contexto" sencillo que funciona bien:

• Objetivo del PR: qué cambia, qué ve el usuario, qué mejora
• Hunks relevantes del diff: solo archivos clave, con código circundante suficiente
• Restricciones duras: presupuestos de rendimiento, requisitos de compatibilidad, reglas de seguridad/privacidad
• Expectativas de test: qué debe cubrirse, qué se añadió, cómo ejecutarlo
• Elementos que "no deben cambiar": contratos públicos de API, esquema de la base de datos, comportamiento UX, formato de logging/auditoría

Paso a paso: un flujo de pre-revisión repetible

Una buena revisión de PR con Claude funciona como un bucle cerrado: proporciona justo el contexto necesario, recibe notas estructuradas y luego conviértelas en acciones. No reemplaza a los humanos. Captura fallos fáciles antes de que un compañero dedique mucho tiempo a leer.

El flujo de 5 pasos

Usa los mismos pasos cada vez para que los resultados sean previsibles:

1. Explica el cambio en lenguaje sencillo. Pide a Claude que resuma qué hace el PR, qué archivos cambiaron y la razón probable del cambio. Si no puede explicarlo de forma simple, probablemente el PR necesite una descripción más clara o un alcance menor.
2. Revisa la corrección primero. Busca errores de lógica, suposiciones rotas y cambios silenciosos de comportamiento (valores por defecto, manejo de errores, permisos, zonas horarias, off-by-one).
3. Escanea casos faltantes. Piensa como un usuario y como producción: entradas vacías, nulls, reintentos, fallos parciales, concurrencia, compatibilidad hacia atrás.
4. Revisa legibilidad y mantenibilidad. Identifica nombres confusos, funciones largas, lógica duplicada, comentarios poco claros y pequeños refactors que reduzcan el tiempo de revisiones futuras.
5. Redacta comentarios de revisión con referencias. Agrupa comentarios por archivo e incluye nombre de función o un fragmento citado para que un humano encuentre el lugar rápidamente.

Después de recibir notas, conviértelas en una puerta corta para merge:

Lista de verificación para merge (mantenla corta):

• Tests cubren el nuevo comportamiento y al menos un caso límite
• Los errores se manejan de forma consistente (y se registran si hace falta)
• No hay cambios incompatibles sin un plan claro de migración
• Nombres y estructura coinciden con el código cercano
• Las partes riesgosas tienen un plan de rollback

Termina pidiendo de 3 a 5 preguntas que obliguen a clarificar, como “¿Qué ocurre si la API devuelve una lista vacía?” o “¿Es esto seguro en condiciones de concurrencia?”

Usa una rúbrica simple (legibilidad, corrección, casos límite)

Claude es más útil cuando le das una lente fija. Sin una rúbrica, tiende a comentar lo que aparece primero (a menudo detalles de estilo) y puede pasar por alto el caso límite de riesgo.

Una rúbrica práctica:

• Legibilidad: nombres claros, flujo simple, funciones pequeñas, comentarios que expliquen el porqué, sin código muerto o salidas de depuración.
• Corrección: invariantes clave reforzadas, errores manejados consistentemente, valores null/vacíos seguros, límites correctos (off-by-one, redondeo).
• Casos límite: entradas vacías/enormes, campos opcionales faltantes, zonas horarias y horario de verano, reintentos que arriesgan doble escritura, carreras de concurrencia.
• Seguridad y privacidad: comprobaciones de auth en el lugar correcto, sin secretos en código/logs, logs que no filtran tokens o cargas sensibles.
• Compatibilidad y seguridad de despliegue: clientes y datos antiguos no se rompen, migraciones seguras, existe plan de rollback.

Cuando pidas, solicita un párrafo corto por categoría y pide “primero el problema de mayor riesgo”. Ese orden mantiene a los humanos enfocados.

Plantillas de prompt que generan notas útiles de revisión

Usa un prompt base reutilizable para que los resultados se parezcan entre PRs. Pega la descripción del PR y luego el diff. Si el comportamiento es visible para el usuario, añade el comportamiento esperado en 1 o 2 frases.

You are doing a pre-review of a pull request.

Context
- Repo/service: <name>
- Goal of change: <1-2 sentences>
- Constraints: <perf, security, backward compatibility, etc>

Input
- PR description:
<...>
- Diff (unified diff):
<...>

Output format
1) Summary (max 4 bullets)
2) Readability notes (nits + suggested rewrites)
3) Correctness risks (what could break, and why)
4) Edge cases to test (specific scenarios)
5) Reviewer checklist (5-10 checkboxes)
6) Questions to ask the author before merge (3-7)

Rules
- Cite evidence by quoting the relevant diff lines and naming file + function/class.
- If unsure, say what info you need.

Para cambios de alto riesgo (auth, pagos, permisos, migraciones), añade pensamiento explícito sobre fallos y rollback:

Extra focus for this review:
- Security/privacy risks, permission bypass, data leaks
- Money/credits/accounting correctness (double-charge, idempotency)
- Migration safety (locks, backfill, down path, runtime compatibility)
- Monitoring/alerts and rollback plan
Return a “stop-ship” section listing issues that should block merge.

Para refactors, convierte en regla que “no debe cambiar el comportamiento”:

This PR is a refactor. Assume behavior must be identical.
- Flag any behavior change, even if minor.
- List invariants that must remain true.
- Point to the exact diff hunks that could change behavior.
- Suggest a minimal test plan to confirm equivalence.

Si quieres un vistazo rápido, añade un límite como “Responde en menos de 200 palabras.” Si quieres profundidad, pide “hasta 10 hallazgos con razonamiento.”

Convierte la salida en una lista de verificación para el revisor

Las notas de Claude son útiles cuando las conviertes en una lista corta que un humano pueda cerrar. No repitas el diff. Captura riesgos y decisiones.

Separa los elementos en dos cubos para que el hilo no se convierta en debates de preferencias:

Debes arreglar (bloquea el merge)

• Corrección: el resultado esperado está escrito en una frase y coincide con el ticket
• Casos límite: entradas null/vacías y rutas de error están manejadas (o rechazadas) claramente
• Seguridad de datos: escrituras y migraciones son seguras para datos y código antiguos
• Tests: al menos un test cubre el comportamiento principal y otro cubre el fallo más riesgoso
• Observabilidad: logs/métricas suficientes para depurar rápido (request id, user id, job id)

Deseable (seguimiento)

• Legibilidad: renombrar el identificador más confuso o añadir un comentario corto del "porqué"
• Consistencia: coincidir con patrones existentes para errores, nombres y estructura de archivos
• Rendimiento: señalar cambios en caminos calientes y si importan a la escala actual
• Docs: actualizar docs inline si se añadió una opción/flag nueva

También captura la preparación para despliegue: orden más seguro de despliegue, qué vigilar después del release y cómo deshacer el cambio.

Preguntas para hacer antes de merge

Una pre-revisión solo ayuda si termina con un pequeño conjunto de preguntas que obliguen a clarificar.

Comportamiento y corrección

• ¿Qué cambia visible para el usuario y qué debe permanecer igual?
• Si esto es “sin cambio de comportamiento”, ¿qué evidencia muestra que las salidas son idénticas?
• ¿Cuál es la falla más probable en producción y dónde se manifestaría (UI, API, datos)?
• ¿Qué suposiciones hace el código sobre entradas, orden, tiempo o llamadas de red?
• ¿Se silencian errores o se convierten en valores por defecto silenciosos?

Casos límite, tests y operaciones

• ¿Cuáles son las peores entradas reales (vacías, enormes, malformadas, duplicadas) y qué debería pasar?
• ¿Qué flujo común podría disparar esto dos veces (reintentos, doble clic, jobs en background) y es seguro?
• ¿Qué test prueba el comportamiento principal y cuál cubre el caso límite más riesgoso?
• Si falta un test, ¿es difícil de escribir o el código es difícil de testear?
• ¿Qué necesitará ops: logs útiles, métricas, alertas, defaults de configuración y pasos de rollback?

Si no puedes responder estas en palabras sencillas, pausa el merge y ajusta el alcance o añade pruebas.

Trampas comunes (y cómo evitarlas)

La mayoría de fallos son problemas de proceso, no del modelo.

• Pegar diffs enormes sin foco. Pide revisión en 1 a 3 áreas de riesgo y pega solo los hunks relacionados más las firmas de las que dependen.
• Omitir intención y comportamiento esperado. Sin un objetivo, la revisión deriva. Añade dos líneas: qué cambia y qué no debe cambiar.
• Confiar en conjeturas seguras. Requiere citas del diff. Si no puede citar evidencia, trátalo como hipótesis a probar.
• Meterse en debates de estilo. Pide “Debes arreglar” vs “Deseable” y limita notas de estilo.
• Ignorar estándares del equipo. Si tu equipo tiene convenciones (returns tempranos, tipos de error, formato de logging), inclúyelas.

Si un PR añade un nuevo endpoint de checkout, no pegues todo el servicio. Pega el handler, validación, escritura en DB y cualquier cambio de esquema. Luego di: “Objetivo: evitar cargos duplicados. No objetivos: refactor de nombres.” Recibirás menos comentarios y los que lleguen serán más fáciles de verificar.

Un ejemplo realista: pre-revisar un PR pequeño

Un PR pequeño y realista: añadir un campo “display name” a una pantalla de ajustes. Toca validación (server) y texto UI (cliente). Es lo suficientemente pequeño para razonar, pero lleno de sitios donde se esconden bugs.

Aquí están los fragmentos de diff que pegarías (más 2–3 frases de contexto como comportamiento esperado y tickets relacionados):

- if len(name) == 0 { return error("name required") }
+ if len(displayName) < 3 { return error("display name too short") }
+ if len(displayName) > 30 { return error("display name too long") }

- <TextInput label="Name" value={name} />
+ <TextInput label="Display name" value={displayName} helperText="Shown on your profile" />

Ejemplos de hallazgos que querrías recibir:

• Legibilidad: "displayName" vs "name" está mezclado entre archivos. Elige un término para que futuros cambios no requieran traducción mental.
• Corrección: el servidor valida la longitud, pero el cliente no. Los usuarios pueden escribir 1–2 caracteres y solo ver el error tras enviar.
• Caso límite: cadenas solo con espacios pasan len(displayName) pero siguen pareciendo vacías. Recorta espacios antes de validar.

Convierte eso en una lista de verificación:

• Nombres consistentes entre API, campos de BD y etiquetas UI.
• Las comprobaciones del cliente coinciden con las reglas del servidor (mín/máx, requerido).
• La entrada se recorta (y el comportamiento con Unicode/emoji es aceptable).
• Mensajes de error claros y alineados entre servidor y UI.

Comprobaciones rápidas, medición y siguientes pasos

Una revisión de PR con Claude funciona mejor si termina con unas pocas comprobaciones rápidas:

• Comportamiento: qué cambia para el usuario y qué no debe cambiar
• Tests: qué se cubre, qué falta, qué puede fallar intermitentemente
• Logs y errores: las fallas son claras y los mensajes útiles
• Rendimiento: nuevos bucles, consultas N+1, payloads grandes, llamadas de red extra
• Seguridad: validación, comprobaciones de auth, secretos, defaults arriesgados

Para ver si compensa, mide dos métricas sencillas durante 2–4 semanas: tiempo de revisión (abierto a primer review significativo, y abierto a merge) y retrabajo (commits posteriores tras la revisión, o cuántos comentarios requirieron cambios de código).

La estandarización vence a los prompts perfectos. Elige una plantilla, exige un bloque de contexto corto (qué cambió, por qué, cómo probar) y acordad qué significa “hecho”.

Si tu equipo construye características mediante desarrollo por chat, puedes aplicar el mismo flujo dentro de Koder.ai: genera cambios, exporta el código fuente y luego adjunta la lista de pre-revisión al PR para que la revisión humana se centre en las partes de mayor riesgo.