CommunityProgramación y desarrollogithub.com

revisión

Juzga un cambio según si construyó lo correcto (especificación) y si está bien construido (calidad), con una mirada fresca, hallazgos respaldados por evidencia y gravedad del impacto en el usuario real. Luego actúa con rigor técnico, no por deferencia.

¿Qué es revisión?

Esta habilidad de agente de IA, disponible en herramientas como Claude Code, Cursor o Codex, proporciona un proceso completo de revisión de código estructurado en dos ejes independientes: especificación (¿se construyó lo correcto?) y calidad (¿está bien construido?). El agente revisa el alcance del cambio (PR, rama, confirmaciones o cambios sin confirmar), recopila la intención a partir de especificaciones, planes y estándares del repositorio (como CONTRIBUTING.md o CLAUDE.md), y luego realiza una revisión con contexto fresco, idealmente utilizando herramientas de subagente para evitar el sesgo del autor. Genera hallazgos clasificados por gravedad (Crítico, Importante, Menor, Nit, FYI), cada uno respaldado por evidencia concreta como una prueba fallida o un script de reproducción. El veredicto final puede ser Aprobar, Aprobar con correcciones o Solicitar cambios, siguiendo una definición de "hecho" antes de la fusión que incluye pruebas completas, ausencia de hallazgos críticos y verificación de que se cumplan todos los criterios de éxito.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/hesedcasa/frankenskills/tree/main/skills/review

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace revisión?

Juzga un cambio en dos ejes separados, ¿construyó lo correcto? (especificación) y ¿está bien construido? (calidad), con una mirada fresca, hallazgos respaldados por evidencia y gravedad clasificada según lo que encontraría un usuario real. Luego actúa con rigor técnico, no por deferencia.

Principio fundamental: Aprueba un cambio cuando definitivamente mejora la salud del código base y hace lo que se pidió, incluso si no es como lo habrías escrito. Nunca apruebes uno que no hayas leído y verificado realmente.

Posición en el pipeline: especificación → plan → construir (+ probar) → revisión → fusionar.

Paso 1: Delimitar el alcance

  • El usuario nombra el alcance (PR, rama, rango de confirmaciones, archivos). De lo contrario: la rama actual contra su base de fusión con la rama predeterminada, más los cambios sin confirmar.
  • Resuelve el punto fijo y confirma que el alcance no está vacío antes de hacer cualquier otra cosa: git rev-parse <ref>, git log <ref>..HEAD --oneline, git diff <ref>...HEAD --stat para trabajo confirmado, y git diff --cached --stat (preparado), git diff --stat (no preparado) y git status --short (sin seguimiento) para cambios sin confirmar. Revisa la unión de ambos, y cuando los cambios sin confirmar estén en el alcance, informa a cada revisor (el prompt del revisor tiene una línea para ello). Una referencia incorrecta, o un alcance vacío en ambos aspectos, falla aquí.
  • Para un PR, lee su descripción y los problemas vinculados.

Paso 2: Recopilar la intención

Encuentra, en orden: la especificación y el plan que implementa el cambio (specs/<slug>/, enlaces en confirmaciones/PR, una ruta que el usuario proporcionó), las líneas Ruling: del registro de construcción y el problema que cierra. Reformula la intención en dos o tres oraciones. Si no hay especificación, dímelo: entonces el eje de especificación juzga según la descripción del PR y las expectativas razonables de un usuario.

También encuentra los estándares: CONTRIBUTING.md, CODING_STANDARDS.md, CLAUDE.md/AGENTS.md, configuraciones de linter, ADR, el glosario.

Verificación de tamaño. ~100 líneas cambiadas es ideal, ~300 está bien para un cambio lógico único, ~1000 es demasiado grande para revisarlo bien: recomienda una división (apilada, por grupo de archivos o en cortes verticales) como un hallazgo. La refactorización mezclada con trabajo de características son dos cambios.

Paso 3: Revisión con contexto fresco

El autor es ciego a sus propias suposiciones, y también lo es la sesión que escribió el código. Cuando una herramienta de subagente esté disponible, despacha revisores con contexto fresco usando reviewer-prompt.md: dales el diff (como archivo o comando exacto), las rutas de la especificación/plan, los archivos de estándares y las decisiones del registro de construcción. Nunca tu historial de sesión. Los revisores son de solo lectura y no generan sus propios revisores.

Ejecuta en paralelo, para que un eje no pueda enmascarar al otro:

  • Revisor de especificación: faltante, adicional, malinterpretado.
  • Revisor de calidad: corrección, pruebas, diseño, seguridad, rendimiento.
  • (Opcional, para cambios riesgosos o amplios) Revisor de radio de explosión: qué rompe esto donde grep no lo mostrará.

Usa el modelo más capaz disponible para una revisión de rama completa. Sin una herramienta de subagente, haz cada eje tú mismo como una pasada separada y etiqueta el resultado como una autorevisión: más débil que un revisor nuevo, y el usuario decide si es suficiente.

Revisar tu propia rama que acabas de terminar en línea no sustituye este paso.

El eje de especificación

Compara el diff con lo que se pidió:

  • Faltante: requisitos o criterios de éxito omitidos, parciales o reclamados pero no implementados. Cita la línea de la especificación.
  • Adicional: comportamiento que nadie pidió, opciones especulativas, enlaces o abstracciones (desviación del alcance, YAGNI).
  • Malinterpretado: característica correcta construida de manera incorrecta, o el problema equivocado resuelto.
  • No verificable desde el diff: requisitos que viven en código no cambiado o abarcan cambios. Enumera qué verificar en lugar de adivinar.

La especificación es un documento de visión, no una lista exhaustiva. Donde calla, la expectativa razonable de un usuario es el requisito. El silencio sobre una entrada no es permiso para que falle.

El eje de calidad

Lee las pruebas primero: revelan intención y cobertura.

Pruebas

  • ¿Cada nuevo comportamiento tiene una prueba que fallaría si el comportamiento se rompiera? Responde mediante experimento cuando puedas: invierte una condición que el cambio agrega y ejecuta el conjunto de pruebas, en un árbol de trabajo desechable o copia para que el checkout revisado nunca cambie. Una mutación que permanece en verde es un hallazgo: nombra la prueba faltante.
  • Comportamiento a través de costuras públicas, no internos; sin aserciones sobre simulacros; sin valores esperados calculados por el código bajo prueba; simulacros solo en los límites del sistema.
  • Las correcciones de errores tienen una prueba de regresión. Nada omitido o deshabilitado. Salida de pruebas limpia.

Corrección

  • Coincide con la especificación; casos extremos (nulo, vacío, cero, máximo, unicode, concurrente); rutas de error, no solo el camino feliz; errores de uno por uno, condiciones de carrera, estado que puede desincronizarse.

Legibilidad y simplicidad

  • Los nombres dicen qué son y hacen las cosas. El flujo de control es directo. ¿Podría tener menos líneas? ¿Cada abstracción se justifica (no generalizar antes del tercer uso)?
  • Código muerto, variables sin efecto, comentarios // removed, shims de compatibilidad que nadie necesita.
  • Los comentarios explican por qué, no qué. Un comentario que narra una solución alternativa a menudo marca una causa raíz no corregida.

Diseño

  • Se ajusta a los patrones existentes; un nuevo patrón necesita una razón.
  • ¿Una refactorización reduce los conceptos que un lector debe retener, o solo los mueve? Prefiere la versión donde ramas, modos o capas desaparecen.
  • Lógica de características filtrándose en un módulo compartido; un casi duplicado de un helper existente; un condicional añadido a un flujo no relacionado; conmutadores repetidos en la misma forma (un modelo o despachador faltante); un segundo booleano que debe mantenerse sincronizado con el primero (una máquina de estado faltante).
  • Envoltorios de un solo llamador y capas de paso directo (en línea). Estado mutable más amplio de lo necesario.
  • Validación en los límites, confianza en el interior. Sin retrocesos silenciosos que oculten un invariante poco claro; sin any/casts gratuitos.
  • Crecimiento de archivos: un cambio que empuja un archivo mucho más allá de un tamaño saludable debe descomponerse primero.

Seguridad

  • Entrada no confiable (HTTP, CLI, archivos, env, salida de LLM, respuestas de terceros) validada en el límite. Consultas parametrizadas. Salida codificada. Authn/authz verificados donde sea necesario. Secretos fuera del código, registros y VCS. Nuevas dependencias justificadas, mantenidas, con licencia compatible; diff del archivo de bloqueo revisado.

Rendimiento

  • Consultas N+1, bucles o recuperaciones ilimitados, paginación faltante, trabajo síncrono que bloquea, asignaciones grandes en rutas críticas, re-renderizaciones innecesarias. Cuantifica cuando puedas ("~50ms por fila en 1k filas").

Línea base de olores (juicios; los estándares documentados del repositorio anulan): Nombre Misterioso, Código Duplicado, Envidia de Características, Grupos de Datos, Obsesión por Primitivos, Conmutadores Repetidos, Cirugía con Escopeta, Cambio Divergente, Generalidad Especulativa, Cadenas de Mensajes, Hombre del Medio.

El eje de radio de explosión (cambios riesgosos o amplios)

Enumerar llamadores no es el trabajo; grep hace eso en un segundo. El trabajo es la rotura que grep no mostrará:

  • Encuentra el único hecho por el cual el cambio es seguro ("esta llamada solo elimina entradas que ya están muertas"). Pruébalo ejecutando código: un script que importe la biblioteca real en la versión fijada y llame a la función exacta en cuestión.
  • Mira donde se detiene la búsqueda de símbolos: código fuente de la biblioteca y parches locales, sincronización de ejecución (ordenamiento asíncrono, desmontaje), formatos serializados (formas JSON, columnas DB, protocolos de cable, otros lenguajes leyendo los mismos bytes), banderas de características, consumidores a tres saltos de distancia.
  • Para cada riesgo: cómo se rompe, archivo:línea, probabilidad, costo y la verificación más barata. Enumera los riesgos verificados y descartados por separado.

Paso 4: Verificar cada hallazgo

Un hallazgo que suena correcto no es un hallazgo hasta que se verifica.

  • Verifícalo contra los llamadores, guardias y pruebas que alcanzan el código. Deséchalo si lo descartan.
  • Prueba los importantes: una prueba fallida, un script de reproducción o la salida de un comando que muestre el comportamiento incorrecto. Prefiere hallazgos probados por una ejecución sobre los plausibles.
  • Etiqueta los defectos preexistentes por separado de las regresiones que introduce este cambio.
  • Fusiona hallazgos que comparten una causa raíz.
  • Cero hallazgos es un resultado válido. No inventes uno para parecer exhaustivo.

El límite para bloquear una fusión

Un hallazgo puede ser Crítico o Importante, y por lo tanto bloquear la fusión, solo cuando se establece mediante evidencia:

  • una ejecución (prueba, script o comando) que muestre el comportamiento incorrecto, o
  • una entrada concreta trazada paso a paso a través del código hasta una salida incorrecta, con archivo:línea en cada paso.

Una preocupación plausible que no pudiste establecer de esta manera ("esto podría romper X", "los casos extremos pueden no manejarse") se clasifica como Menor y se etiqueta como no verificado. No bloquea. Enumérala para que el autor pueda verificarla.

Paso 5: Clasificar e informar

Clasifica por efecto en una persona razonable que usa el software si se publica, no por si la especificación menciona el desencadenante.

GravedadSignificadoAcción requerida
CríticoAgujero de seguridad, pérdida de datos, funcionalidad principal rotaBloquea la fusión
ImportanteComportamiento incorrecto o frágil, requisito omitido, comportamiento no probado, errores tragados, duplicación o diseño dañinoCorregir antes de fusionar
MenorPulido, pequeñas simplificaciones, cobertura más ampliaDecisión del autor; registrar si se aplaza
NitPreferencia de estiloOpcional
FYIContexto, sin acciónNinguna

Lidera con apalancamiento: primero corrección y seguridad, luego problemas estructurales y simplificaciones omitidas, luego el resto. Si hay un problema estructural y diez nits, el problema estructural es la revisión. Propón el movimiento, no solo el problema: "reemplaza esta cadena if con una búsqueda clave por kind", "incluye este envoltorio de un solo llamador", "reutiliza formatDate de utils/date.ts".

Sé honesto: sin "LGTM" de cajón, sin suavizar un error real a "podría ser una preocupación menor", sin inflar nits a Crítico. Reconoce lo que está bien hecho, de manera específica.

Usa el formato en reviewer-prompt.md: veredicto de especificación, fortalezas, problemas por gravedad (cada uno con archivo:línea, qué está mal, por qué importa, cómo corregir, evidencia), notas de radio de explosión, declinado juzgar (comportamientos considerados y descartados, con por qué), y un veredicto: Aprobar, Aprobar con correcciones o Solicitar cambios. Mantén las secciones de especificación y calidad separadas; no reordenes entre ellas.

Regla de veredicto: solicita cambios solo cuando al menos un hallazgo Crítico o Importante cumpla con el límite de evidencia anterior. Un cambio que hace lo que se pidió y tiene solo preocupaciones Menores o no verificadas se aprueba, con esas preocupaciones listadas. Rechazar un cambio correcto le cuesta al autor tanto como aprobar uno roto.

Paso 6: Actuar sobre los hallazgos (cuando eres el autor)

La retroalimentación de revisión es información para evaluar, no órdenes para ejecutar.

  1. Lee todo antes de reaccionar. Si algún elemento no está claro, pregunta al respecto antes de implementar nada: los elementos a menudo están relacionados.
  2. Reformula cada elemento como un requisito técnico y verifícalo contra el código. ¿Es correcto para este código base? ¿Rompe algo? ¿Había una razón para el código actual? ¿El revisor tiene el contexto completo?
  3. Responde con evidencia cuando esté equivocado: una prueba, un archivo:línea, una medición. Si una sugerencia agrega una característica "adecuada" no utilizada, verifica el uso; YAGNI también se aplica a los revisores. Escala al usuario cualquier cosa que entre en conflicto con sus decisiones anteriores.
  4. Corrige en orden: Crítico/bloqueante → simple → complejo. Cada corrección obtiene una prueba fallida que reproduce el hallazgo primero (a través de test), luego la corrección, luego una suite completa en verde. Una pasada de corrección enfocada, no un bucle infinito.
  5. Los Menores que no corrijas van en una lista "Aplazados" en tu mensaje final. Un hallazgo que decidas no corregir es una decisión registrada con una razón.
  6. Sin acuerdo de actuación. Sin "¡Tienes toda la razón!", "¡Gran descubrimiento!" ni agradecimientos. Indica lo que cambiaste ("Corregido: las filas vacías ahora emiten un CSV solo con encabezado; prueba exports header for empty view") o por qué el código se mantiene. Si respondiste y estabas equivocado, dilo en una línea y corrígelo.

En GitHub, responde en el hilo de comentarios en línea, no como un comentario de nivel superior.

Antes de fusionar (Definición de Hecho)

  • Cada criterio de éxito de la especificación se cumple y verifica en el sistema en ejecución
  • El nuevo comportamiento tiene pruebas que fallan sin el cambio; suite completa en verde, salida limpia
  • No hay hallazgos Críticos o Importantes abiertos; aplazamientos registrados con razones
  • Sin código muerto, salida de depuración o bloques comentados; cambios limitados a la tarea
  • Lint, typecheck, construcción pasan
  • Migraciones, configuración y banderas consideradas; existe una ruta de reversión para cambios riesgosos
  • Interfaces públicas y comportamiento visible para el usuario documentados; ADR para decisiones difíciles de revertir
  • Los mensajes de confirmación y la descripción del PR dicen qué cambió y por qué, en términos independientes
  • El humano aprobó donde el proyecto lo requiere

Racionalizaciones comunes

PensamientoRealidad
"Las pruebas pasan, así que está bien"Las pruebas no detectan diseño incorrecto, agujeros de seguridad o una especificación mal leída.
"Lo escribí, sé que está bien"Mismo autor, mismos puntos ciegos. Obtén una mirada fresca.
"El código generado por IA probablemente está bien"Es seguro y plausible cuando está equivocado. Necesita más escrutinio, no menos.
"La refactorización es más limpia"Si el lector retiene el mismo número de conceptos, solo se movió.
"Lo limpiaremos después"Después rara vez llega. Corrígelo ahora o regístralo explícitamente.
"La especificación no mencionó esa entrada"El silencio no es permiso. Clasifica por lo que obtiene el usuario.
"El revisor dijo Menor, así que es Menor"Reclasifica por efecto.
"La corrección es obvia, no se necesita prueba"La prueba fallida es la única prueba de que el hallazgo era real y ahora ha desaparecido.
"El revisor probablemente tiene razón"Verifica contra el código primero.

Banderas rojas

  • "LGTM" sin evidencia de lectura
  • Hallazgos sin archivo:línea, o reclamados sin verificar llamadores y guardias
  • Hallazgos de especificación y calidad fusionados en una lista clasificada
  • Nits enterrados sobre un error de corrección
  • Un revisor que recibió el historial de sesión del autor
  • Corrección de hallazgos de revisión sin una prueba fallida primero
  • Implementación de algunos elementos de retroalimentación mientras otros están...

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Skills relacionados