CommunityProgramación y desarrollogithub.com

revision-basada-en-evidencia

Revisión profunda de código basada en evidencia de cualquier cosa: un proyecto completo sin diff, una ruta, cambios no confirmados, una rama o un PR de GitHub / MR de GitLab. Reproduce hallazgos en lugar de adivinar, juzga la elección de capa y la reutilización como un mantenedor estricto, y escribe un informe estructurado con ID, gravedad, estado y verificación.

¿Qué es revision-basada-en-evidencia?

Esta habilidad transforma la revisión de código en un proceso riguroso y basado en evidencia, similar al de un ingeniero senior responsable de lo que se envía. No se limita a adivinar: reproduce hallazgos serios con scripts desechables, ejecuta compilaciones y pruebas, y aplica una escala de gravedad clara. Soporta múltiples modos de alcance: proyecto completo, ruta específica, cambios no confirmados (diff), una rama frente a su base, o un PR/MR de GitHub o GitLab. Cada modo tiene un flujo de trabajo específico: por ejemplo, para un PR, usa un worktree separado para no ensuciar el árbol de trabajo del usuario. El informe resultante incluye identificadores, estado y verificación de cada hallazgo, separando los bloqueantes de los no bloqueantes y documentando honestamente lo que no se pudo verificar. La habilidad también integra la lectura de reglas del proyecto (como `CLAUDE.md` o `AGENTS.md`), la auditoría de dependencias y el mapeo de la superficie de ataque, todo para garantizar que la revisión sea profunda y no solo superficial.

Compatible con✓Claude Code✓Codex CLI✓Cursor
npx skills add https://github.com/avi-dev-user/evidence-review/tree/HEAD

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

Revisión basada en evidencia

Estás haciendo la revisión que un ingeniero senior hace cuando es responsable de lo que se envía: lee lo que está en alcance, ejecuta las herramientas, reproduce lo que sospecha y dice claramente lo que no pudo verificar. Dos estándares definen el listón:

  • La auditoría del proyecto. El código en alcance se lee completo, se ejecutan la compilación y las pruebas, cada hallazgo serio se reproduce con un script desechable, se usa una escala de gravedad clara, estados que evolucionan a medida que se corrigen los fallos, y una sección honesta de "lo que está en buen estado".
  • El mantenedor estricto. Primero pregunta si el cambio pertenece a esta capa, señala el helper existente o punto de extensión por archivo y línea, rastrea a cada lector de estado compartido antes de llamar algo seguro, separa lo bloqueante de lo no bloqueante, y fija los contratos antes de que algo dependa de ellos.

La profundidad proviene de la evidencia, no del volumen. Un informe corto donde cada hallazgo es real supera a uno largo inflado para parecer exhaustivo.

1. Resolver el alcance

Argumentos dados: "$ARGUMENTS" (comillas vacías significan que no hay argumentos). Si eso sigue leyéndose como un marcador de posición literal, tu agente no sustituye argumentos: tómalos de la solicitud del usuario.

ArgumentoAlcanceModoSalida
ningunoTodo el repositorio, árbol de trabajo tal cualproyectoArchivo de informe
una rutaEsa ruta completa, más las definiciones que llama a un nivel de profundidadproyectoArchivo de informe
diffCambios staged + unstaged: git diff HEADcambioEn el chat
branch [base]git diff <base>...HEAD (tres puntos: desde la merge-base)cambioEn el chat
`pr <nurl>`La cabeza del PR/MR contra su rama objetivocambio
--update <file>Re-verificar un informe existente; solo modo proyecto, con o sin rutaactualizaciónEdita ese archivo
  • Rama base para branch: git symbolic-ref --short refs/remotes/origin/HEAD; si falla, main, luego master; si ninguna existe, es una pregunta abierta (sección 2).
  • Árbol sucio en modo proyecto: revisa el árbol de trabajo tal cual, y registra HEAD <sha> + cambios no confirmados como la revisión. Los archivos modificados obtienen path:line, no enlaces fijos.
  • Sin argumentos y árbol sucio: eso es una pregunta abierta (¿proyecto o diff?).
  • Monorepo: para una ruta, ejecuta los comandos del paquete que la posee (el package.json / pyproject.toml / go.mod / Cargo.toml / *.csproj más cercano) y lee los archivos de reglas desde la raíz del repositorio hacia abajo hasta ese paquete.

El modo cambio aún revisa el código circundante. La unidad de revisión son los hunks modificados más las funciones completas en las que se encuentran, cada llamador de un símbolo modificado, cada lector y escritor de cualquier estado que toque el cambio, las pruebas que lo cubren y los documentos que lo describen. Un diff leído de forma aislada es cómo se aprueban los errores costosos.

Obtener un PR o MR

Nunca te revises sobre el árbol de trabajo del usuario. Siempre usa un worktree separado en una ubicación temporal:

  • GitHub: git fetch origin pull/<n>/head:pr-<n>; GitLab: git fetch origin merge-requests/<n>/head:mr-<n>. Luego git worktree add <scratch>/pr-<n> pr-<n>.
  • Metadatos: gh pr view <n> --json title,body,comments,reviews,baseRefName,headRefName o glab mr view <n> --comments. Si ninguna CLI está disponible o iniciada sesión, revisa solo el diff y declara en el encabezado que no se leyó el historial de discusión.
  • Para ejecutar la base de comparación (sección 4), agrega un segundo worktree en la merge-base. Nunca intercambies el worktree de la cabeza de un lado a otro.
  • Elimina los worktrees al final (git worktree remove).

2. Contexto y una ronda de preguntas

Recopila y guarda para el encabezado del informe:

  • Revisión (SHA completo), rama, URL remota. Sin remoto, salta el resto de este punto y usa path:line. De lo contrario, ejecuta git fetch --quiet primero, luego git branch -r --contains <sha>; si falla la búsqueda, trata el SHA como no enviado. Los enlaces se fijan al SHA solo cuando está enviado y el host es GitHub o GitLab (convierte remotos SSH a https):
    • GitHub https://github.com/<o>/<r>/blob/<sha>/<path>#L<a>-L<b>
    • GitLab https://<host>/<group>/<repo>/-/blob/<sha>/<path>#L<a>-<b>
    • cualquier otra cosa: path:line.
  • Reglas del proyecto: CLAUDE.md, AGENTS.md, CONTRIBUTING.md, configuraciones de lint/tipos, plantillas de PR y archivos de reglas en directorios padres. Los hallazgos se juzgan primero contra las reglas del propio proyecto, después por el gusto general.
  • Para qué sirve el sistema: README, documentos, manifiestos de despliegue, configuración de CI, puntos de entrada.
  • Para un PR: su descripción, issues vinculados, comentarios de revisión existentes y su resolución, y la rama objetivo. Lee rondas anteriores de revisión para no volver a plantear puntos resueltos, y verifica que los cambios solicitados se hayan realizado realmente.
  • Intención. Declara en una oración qué problema está resolviendo el código o cambio. Si no puedes, eso es una pregunta abierta, porque la respuesta puede cambiar cómo debería estar conectado.

Idioma del informe, el primer acierto gana: la solicitud explícita del usuario; el archivo de reglas del proyecto; reglas en un directorio padre; la audiencia (un PR de código abierto ascendente obtiene inglés); el idioma de los documentos existentes del proyecto. Si ninguno aplica, es una pregunta abierta.

Preguntas abiertas. Reúne cada pregunta abierta de las secciones 1 y 2 (alcance, rama base, audiencia, una preocupación que el solicitante quiere cubierta, idioma, intención) y pregúntalas juntas, en un solo mensaje. No preguntes nada que puedas encontrar por ti mismo. Si nadie puede responder (una ejecución no interactiva, o el usuario dijo que no preguntes), usa estos valores predeterminados y enumera cada uno bajo "Suposiciones" en el encabezado del informe: modo proyecto sin argumentos; mantenedores como audiencia; inglés; ninguna preocupación nombrada; intención como se indica en la descripción del PR o el README.

Una preocupación que el solicitante nombre obtiene su propia sección al principio del informe, sea cual sea su gravedad.

3. Presupuesto y triaje

Decide qué significa "en alcance" antes de leer nada línea por línea.

  • Excluir de la lectura línea por línea: lockfiles, vendor/, node_modules/, dist//build/, código generado, archivos minificados, binarios, instantáneas, fixtures grandes, colecciones de API. Búscalos o examínalos para lo que importa (una versión vulnerable fijada, un secreto, una lista de endpoints).
  • Cuenta lo que queda, contando solo archivos fuente que no sean de prueba. Por encima de aproximadamente 40 archivos o 8,000 líneas, divide el código en áreas y despliega subagentes de solo lectura, uno por área, para recopilar hallazgos candidatos con archivo:línea y razonamiento. Esto es obligatorio en ese tamaño, no opcional: un contexto no puede leerlo todo, y un examen superficial silencioso es peor que una división honesta. Cada candidato se verifica en el hilo principal (sección 7). Si tu agente no tiene subagentes, revisa un área por pase, mantén una lista escrita de candidatos entre pases y di en Alcance cómo se dividió el trabajo.
  • Pruebas: lee completamente las pruebas que cubren las rutas más riesgosas y cada prueba de cuyos mocks depende un hallazgo; examina el resto para configuración y cobertura, y dímelo en Alcance.
  • Orden por riesgo: puntos de entrada y autenticación primero, luego todo lo que escribe en un almacén de datos, luego llamadas salientes, luego el resto.
  • Registra la cobertura honestamente. El Alcance del informe dice qué se leyó completo, qué se examinó y qué se saltó. Nunca afirmes una lectura completa que no hiciste.

4. Salud base

Seguridad antes de ejecutar cualquier cosa

  • Código que no escribiste (un PR de un fork o un colaborador desconocido, un repositorio que te acaban de dar): instalar, compilar y probar lo ejecuta, incluidos los hooks de instalación y la configuración de pruebas. Enumera los comandos que planeas ejecutar y qué ejecutan, y pregunta primero. Si nadie puede responder, no ejecutes: revisa estáticamente y dílo en el encabezado.
  • Verifica a dónde apuntan las pruebas. Lee la configuración de las pruebas y los archivos de entorno. Si el conjunto de pruebas alcanzara algo más allá de localhost (una base de datos compartida, una API de staging, una cola real), no lo ejecutes; registra por qué.
  • Mantén el checkout limpio. Instala con comandos que respeten el lockfile (npm ci, pip install -r con hashes cuando estén disponibles, uv sync --frozen). Envía la salida de compilación y cobertura fuera del checkout, o confirma que está en gitignore (los ejecutores de pruebas a menudo escriben cobertura en el repositorio por defecto: pasa el directorio de salida, por ej., jest --coverageDirectory <scratch>). Al final, git status no debe mostrar ningún cambio que hayas hecho.
  • Nunca ejecutes nada contra entornos de producción o compartidos. Las comprobaciones de producción se convierten en recomendaciones con el comando exacto a ejecutar (por ejemplo, un plan de consulta en la base de datos en vivo).

Qué ejecutar

Encuentra los comandos reales en los scripts de package.json / pyproject.toml / Makefile / configuración de CI, luego ejecuta y registra cada uno con su resultado exacto: typecheck, lint, compilación, pruebas con cobertura por archivo, y la auditoría de dependencias del ecosistema (npm audit, pip-audit, cargo audit, govulncheck, bundle audit, dotnet list package --vulnerable; osv-scanner como alternativa). Las auditorías necesitan red y un lockfile; si falta alguno, regístralo. La mayoría de las herramientas de auditoría salen con código no cero cuando encuentran avisos: eso es un resultado, no un comando fallido.

  • Un proyecto sin pruebas, compilación o linter: registra "ninguno configurado" una vez. Es un hallazgo, no uno por archivo.
  • Las dependencias desactualizadas se reportan solo cuando tienen una vulnerabilidad conocida, están más allá del final de su vida útil o bloquean una actualización necesaria.
  • Una dependencia privada que no puedes instalar: regístrala, revisa contra el código disponible (una copia instalada, una copia vendida), y di qué comportamiento de la librería quedó sin verificar.

En modo cambio, ejecuta el conjunto de pruebas en la cabeza, y donde algo falle también en la base (en su propio worktree), para que cada fallo se etiquete como nuevo o preexistente.

5. Mapear el sistema

Antes de leer línea por línea, escribe para ti mismo:

  • Puntos de entrada: rutas HTTP, manejadores de protocolo (WebSocket, gRPC, telefonía y similares), comandos CLI, consumidores de colas, trabajos cron, migraciones, inicio.
  • Límites de confianza: quién puede alcanzar cada punto de entrada, cómo se autentica el llamador y de dónde proviene la identidad del tenant/usuario.
  • Almacenes de datos, sus índices y qué rutas leen y escriben cada colección o tabla.
  • Llamadas salientes: timeouts, TLS, reintentos, qué significa un fallo ambiguo.
  • Operaciones de múltiples pasos cuyo medio puede fallar.
  • Las formas reales de los datos. Recopila valores de ejemplo del README, documentos de API, fixtures, datos de semilla y colecciones de API: formatos de ruta, formatos de fecha, formatos de ID, uso de mayúsculas. Cada analizador y helper de ruta se ejecuta posteriormente contra todos ellos.

En modo cambio, mapea el radio de explosión en su lugar: busca cada llamador y cada lector de lo que toca el cambio, con archivo:línea.

6. Lectura profunda

Lee reviewer-lens.md ahora. Es una lista de verificación de preguntas, no una cuota: la mayoría de las secciones no tienen nada que decir sobre la mayoría de los archivos, y una sección sin nada que decir no dice nada. Reporta solo candidatos con un escenario desencadenante concreto.

Lee cada archivo en alcance completamente, no extractos. Incluye las partes de las librerías de las que depende el código donde el comportamiento en el límite importa (cómo se comporta una librería cliente después de que el par se desconecta, cómo un framework maneja un error después de que se envió la respuesta). Muchos errores reales viven allí.

No eximas el código bueno. Las partes que parecen bien diseñadas reciben las mismas comprobaciones mecánicas que el resto: planes de consulta para sus consultas calientes, las formas reales de los datos a través de sus analizadores, lectores de su estado compartido. El código que parece cuidadoso oculta los errores que nadie buscó.

Mantén una lista en ejecución de candidatos, cada uno con: ubicación, qué sale mal, el escenario concreto (entradas y estado que lo desencadenan) y cómo lo probarías.

También mantén una lista de las cosas que están bien hechas, con la evidencia. Las afirmaciones de "confirmado funcionando" necesitan el mismo rigor que los hallazgos: verificaste los lectores, ejecutaste la prueba, leíste el código de la librería.

7. Verificar

Para cada candidato que podría ser Alto o Crítico, y cualquier Medio donde sea barato:

  • Reprodúcelo con un script desechable en un directorio temporal, nunca en el repositorio. Prefiere dependencias reales a pequeña escala (una base de datos en memoria o contenedorizada, un upstream simulado en el límite HTTP) sobre mocks del código bajo revisión.
  • Para afirmaciones de rendimiento, mide: planes de consulta (explain(), EXPLAIN ANALYZE), tiempos antes y después, en un tamaño de datos donde el problema se muestre.
  • Para afirmaciones de "esto es seguro" sobre estado compartido, enumera cada lector y escritor.
  • Limita el esfuerzo: alrededor de 15 minutos o 5 intentos por candidato. Pasado eso, etiquétalo y continúa con la razón. Deja de reproducir una vez que cada candidato Crítico/Alto tenga una etiqueta.

Etiqueta la evidencia de cada hallazgo:

  • sí: reproducido ejecutando código.
  • parcialmente: parte de la afirmación reproducida; la sección dice qué parte.
  • artefacto: mostrado por un archivo, manifiesto, capa de imagen o commit, donde ejecutarlo no es posible aquí (una variable de despliegue faltante, un secreto en el historial).
  • no: intentado y no se pudo reproducir; di por qué se sigue reportando, o elimínalo.
  • no intentado: solo razonamiento.

Luego sé honesto:

  • Un candidato sin un desencadenante plausible en este despliegue se descarta, no se archiva como Bajo.
  • Una inferencia permanece etiquetada como inferencia ("probablemente", "no pude verificar esto desde aquí").
  • Una prueba que pasa solo porque un mock devuelve algo que el código real nunca devuelve es un hallazgo sobre la prueba, no evidencia sobre el código.

8. Clasificar

Gravedad, juzgada por impacto y alcanzabilidad en este despliegue. Cuando la alcanzabilidad depende de algo que no puedes verificar (ACLs de red, quién puede alcanzar un puerto), archiva la gravedad como si fuera alcanzable y declara al lado qué la reduciría.

  • Crítico: explotable ahora, con impacto grave.
  • Alto: pérdida de datos, acceso entre tenants o usuarios, o una característica central rota.
  • Medio: un error real o riesgo que necesita condiciones específicas.
  • Bajo: higiene, mantenibilidad, documentación, desviación de dependencias.

Para una librería, juzga por el impacto en un consumidor típico. Para una herramienta de un solo usuario, la pérdida de datos sigue siendo Alta, y un hallazgo de seguridad necesita un atacante realista.

En modo cambio, también etiqueta cada hallazgo:

  • nuevo si está introducido por el cambio.
  • preexistente si ya estaba en la base.

9. Reportar

Encabezado del informe (cada informe)

  • Revisión (<sha>, limpio o no, rama, remoto).
  • Alcance (qué se leyó, qué no).
  • Herramientas ejecutadas y sus resultados (typecheck: ok; lint: 3 advertencias; pruebas: 142 pasan, 2 fallan: nuevo; auditoría: 1 CVE alta en [email protected]).
  • Suposiciones de la sección 2.
  • Enlaces a los archivos revisados (formato de enlace de la sección 2).

Cuerpo del informe

Dos secciones principales, en este orden:

Hallazgos. Cada hallazgo tiene un ID (F-001, etc.), gravedad, estado (Abierto, Confirmado, Solucionado, No Aceptado), evidencia (sí, parcialmente, artefacto, no, no intentado) y una explicación que da el escenario desencadenante completo.

  • Un hallazgo es solo un hallazgo: no dos hallazgos separados para el mismo síntoma en lugares diferentes, a menos que sean desencadenados de forma independiente.
  • Las soluciones son solo soluciones: no archivo un hallazgo "optar por xxx en lugar de yyy" y otro "todo lo demás está bien".

Lo que está en buen estado. Sección corta, basada en evidencia, con referencias a archivos y líneas. "La función validate() maneja todos los casos borde conocidos; verificamos contra la especificación" es bueno. "El código se ve limpio" no lo es.

Al final (solo informe de proyecto)

git status limpio, listo. Elimina todos los worktrees temporales.

10. Pautas de manejo

  • Las preferencias del usuario anulan las reglas de la habilidad. Si el usuario dice "revisa solo los cambios", la sección 1 se anula. Si el usuario dice "ignora las pruebas", la sección 4 se anula. Registra la anulación en el encabezado.
  • Los informes son para el usuario, no para la máquina. Los hallazgos están escritos para un desarrollador que arreglará el código: da el contexto, no solo la conclusión.
  • Mantén el informe actualizado. Cuando te pidan que actualices un informe, re-verifica los hallazgos marcados y actualiza el estado. Mantén el informe completo, no solo los cambios.
  • Si el cambio rompe pruebas existentes, eso es un hallazgo. Si las pruebas existentes ya estaban rotas, escribe ese deterioro en el encabezado, pero no lo archivos como un hallazgo del cambio (a menos que el cambio lo empeore).

Skills relacionados