CommunityProgramación y desarrollogithub.com

revisión-de-cambios-de-código

Revisa un cambio de código (diff local, cambios staged, rama, rango de commits o pull request) en cuanto a corrección, seguridad, rendimiento, fiabilidad, compatibilidad, altitud, duplicación, simplicidad y calidad de las pruebas, con comprobaciones específicas del idioma cargadas solo para los lenguajes que toca el cambio. Reporta cada hallazgo como un comentario etiquetado [CRÍTICO], [MAYOR], [MENOR] o [NIT] que indique el problema, por qué importa y una corrección sugerida. Úsalo siempre que el usuario pida revisar código o un pull request en cualquier forma.

¿Qué es revisión-de-cambios-de-código?

La habilidad 'Revisión de Cambios de Código' está diseñada para emular la rigurosa revisión de un ingeniero senior, priorizando defectos reales sobre ruido. Comienza identificando exactamente qué cambios revisar (diff local, staged, rama, rango de commits o PR) y obteniendo el contexto necesario, incluyendo la intención del cambio (descripción del PR, mensajes de commit). Luego carga guías de referencia solo para los lenguajes que aparecen en el cambio, utilizando un detector automático o una tabla de mapeo explícita. La revisión se estructura en ángulos priorizados: corrección, seguridad, calidad del código y verificación. Cada hallazgo debe ser verificado antes de reportarlo, y se presenta con una etiqueta de severidad ([CRÍTICO], [MAYOR], [MENOR], [NIT]) junto con un escenario de falla concreto y una sugerencia de corrección. La habilidad soporta GitHub (via `gh`) y GitLab (via `glab`), y puede integrarse con herramientas estructuradas de hallazgos. El objetivo es una revisión breve pero impactante, con un límite de ~10 hallazgos, evitando falsos positivos.

Compatible con✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/OMG-Software/code-change-review-skill/tree/HEAD/skills/code-change-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

Revisión de Cambios de Código

Revisa un cambio como lo haría un buen ingeniero senior: encuentra los defectos que realmente importan, pruébalos e infórmalos para que el autor pueda actuar rápido. Una revisión corta con tres errores reales vale más que una larga con treinta tal vez, porque cada falso positivo enseña al lector a pasar de largo.

Flujo de Trabajo

1. Determinar el conjunto de cambios

Averigua exactamente qué está bajo revisión antes de leer cualquier código. Si el usuario no lo dice, por defecto todo lo que aún no está en la rama base.

ObjetivoCómo obtenerlo
Trabajo sin commitgit diff HEAD (más git status para archivos sin seguimiento, luego léelos)
Solo stagedgit diff --cached
Rama actualgit diff $(git merge-base HEAD <base>) donde <base> suele ser main/master
Rango de commitsgit diff A..B
Pull request (número o URL)gh pr view <n-o-url> para la descripción, base y cabeza; gh pr diff <n-o-url> para el diff; gh pr diff <n-o-url> --name-only para la lista de archivos
Archivos específicosLéelos; pregunta de qué cambiaron si es relevante

Pull requests. "Revisa PR 123" o "revisa PR #123" significa PR 123 en el repositorio actual. Una URL (https://github.com/<propietario>/<repo>/pull/<n>) se puede pasar a gh tal cual, y funciona desde cualquier directorio, incluso para otro repositorio. Para un merge request de GitLab usa glab mr view / glab mr diff. El diff por sí solo no es suficiente contexto (paso 3), así que también lee las versiones de los archivos del PR:

  • Si el PR es del repositorio actual, fétchalo y su base sin cambiar de rama, en una ref dedicada que se fuerza a actualizar para que un PR rebasado reemplace cualquier copia de una revisión anterior. Fetchea desde el remoto que apunta al repositorio base del PR (comprueba git remote -v); en un fork suele ser upstream, no origin:

    git fetch <remoto> <base> +refs/pull/<n>/head:refs/review/pr-<n>
    git rev-parse refs/review/pr-<n>    # debe coincidir con: gh pr view <n> --json headRefOid --jq .headRefOid
    

    Si el fetch falla o el commit no coincide con headRefOid, detente y dilo en lugar de revisar una copia incorrecta o desactualizada. Luego lee archivos con git show refs/review/pr-<n>:<ruta> y compara con $(git merge-base refs/review/pr-<n> <remoto>/<base>). Usa gh pr checkout <n> solo si al usuario le parece bien cambiar su árbol de trabajo.

  • Para otro repositorio, lee los archivos en la cabeza del PR a través de gh api "repos/<propietario>/<repo>/contents/<ruta>?ref=<sha-cabeza>" (entre comillas, ya que ? es un carácter glob en zsh), o clónalo a un directorio temporal si la revisión necesita mucho contexto.

  • Lee los comentarios existentes para no repetir lo que ya se ha planteado, respondido o resuelto. gh pr view <n> --comments muestra solo comentarios de nivel superior; los hilos de revisión en línea, sus respuestas y si cada uno está resuelto vienen de GraphQL:

    gh api graphql --paginate -F owner=<propietario> -F repo=<repo> -F n=<n> -f query='query($owner:String!,$repo:String!,$n:Int!,$endCursor:String){repository(owner:$owner,name:$repo){pullRequest(number:$n){reviewThreads(first:100,after:$endCursor){pageInfo{hasNextPage endCursor} nodes{id isResolved isOutdated path line comments(first:100){totalCount nodes{author{login} body}}}}}}}'
    

    --paginate sigue los hilos más allá de los primeros 100. Un hilo cuyo comments.totalCount supere 100 tiene más respuestas; fétchalas con node(id:<id del hilo>){... on PullRequestReviewThread{comments(first:100,after:<cursor>){…}}} antes de confiar en él.

También obtén la intención: la descripción del PR, los mensajes de commit, el issue vinculado o pregúntale al usuario en una línea si no existe. No puedes juzgar si el código es correcto sin saber qué se supone que debe hacer.

Para cambios muy grandes (más de ~1,500 líneas modificadas), haz un triage primero. Clasifica los archivos por riesgo (autenticación, pagos, migraciones de datos, concurrencia, APIs públicas y cualquier cosa eliminada van antes que docs, código generado y archivos de bloqueo) y di qué archivos recibieron un pase más ligero.

2. Cargar guías de lenguaje para lo que toca el cambio

Carga solo los archivos de referencia para los lenguajes y tipos de archivo en el conjunto de cambios, nunca todos. Cada archivo añade contexto que desplaza el código que estás revisando.

Ejecuta el detector si Python está disponible (python o python3):

python <directorio-skill>/scripts/detect_languages.py --git <base>   # rama vs base
python <directorio-skill>/scripts/detect_languages.py --git HEAD     # trabajo sin commit
python <directorio-skill>/scripts/detect_languages.py --git <remoto>/<base> --head refs/review/pr-<n>   # PR fetcheado
git diff --name-only ... | python <directorio-skill>/scripts/detect_languages.py   # cualquier lista de archivos

Para un pull request, usa --head con la ref obtenida en el paso 1. El detector entonces lee los shebangs del commit del PR, no de tu árbol de trabajo, que puede carecer de los nuevos scripts del PR o contener versiones diferentes. Para un PR en otro repositorio, gh pr diff <url> --name-only | python <directorio-skill>/scripts/detect_languages.py da la lista de archivos, pero no puede ver el contenido de los archivos. Comprueba la primera línea de cada archivo sin extensión en la lista, mapeado o no (un script de Python en migrations/ ya está mapeado a sql.md pero aún necesita python.md): léelo en la cabeza del PR, o en la base si el PR lo elimina, y enrutalo con la tabla de shebangs a continuación.

Imprime los archivos de referencia a leer y qué archivos modificados activaron cada uno. Sin Python, usa esta tabla, que coincide exactamente con el detector. Los nombres de archivo coinciden sin distinguir mayúsculas/minúsculas.

Archivos modificadosLeer
.py, .pyi, .pyw, .ipynb, pyproject.toml, setup.py, setup.cfg, requirements.txt, Pipfile, Pipfile.lock, poetry.lock, uv.lockreferences/languages/python.md
.js, .jsx, .mjs, .cjs, .ts, .tsx, .mts, .cts, .vue, .svelte, .astro, package.json, package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb, tsconfig.jsonreferences/languages/javascript-typescript.md
.go, go.mod, go.sum, go.workreferences/languages/go.md
.rs, Cargo.toml, Cargo.lockreferences/languages/rust.md
.java, .kt, .kts, .scala, .sc, .groovy, .gradle, pom.xml, build.gradle, settings.gradle, gradle.propertiesreferences/languages/java-kotlin.md
.cs, .fs, .fsx, .vb, .csproj, .fsproj, .vbproj, .sln, .razor, .cshtml, Directory.Build.props, Directory.Packages.props, NuGet.config, global.jsonreferences/languages/csharp-dotnet.md
.c, .h, .cc, .cpp, .cxx, .c++, .hpp, .hh, .hxx, .inl, .ipp, .m, .mm, CMakeLists.txt, Makefile, meson.build, conanfile.txt, vcpkg.jsonreferences/languages/c-cpp.md
.rb, .erb, .rake, .gemspec, .ru, Gemfile, Gemfile.lock, Rakefile, config.rureferences/languages/ruby.md
.php, .phtml, composer.json, composer.lockreferences/languages/php.md
.swift, .pbxproj, Package.swift, Package.resolved, Podfilereferences/languages/swift.md
.sql, .psql, .pgsql, .ddl, y cualquier archivo en migration/, migrations/, migrate/, alembic/versions/, flyway/, liquibase/references/languages/sql.md
.sh, .bash, .zsh, .ksh, .fish, .ps1, .psm1, .psd1, .bat, .cmdreferences/languages/shell.md
.tf, .tfvars, .hcl, .dockerfile, Dockerfile, Dockerfile*, Containerfile, .dockerignore, compose*.yml, compose*.yaml, docker-compose*.yml, docker-compose*.yaml, Chart.yaml, values.yaml, kustomization.yaml, .gitlab-ci.yml, azure-pipelines.yml, bitbucket-pipelines.yml, Jenkinsfile, cualquier archivo en .circleci/, y YAML en .github/workflows/, .github/actions/, k8s/, kubernetes/, helm/, charts/, manifests/, deploy/, deployment/, kustomize/, argocd/references/languages/infrastructure.md

Un archivo sin extensión se enruta por el intérprete en su línea shebang (#!/usr/bin/env deno, #!/usr/bin/python3). Los sufijos de versión se ignoran.

Intérprete shebangLeer
pythonreferences/languages/python.md
node, deno, bun, ts-node, tsxreferences/languages/javascript-typescript.md
rubyreferences/languages/ruby.md
phpreferences/languages/php.md
sh, bash, zsh, ksh, dash, fish, pwshreferences/languages/shell.md

Un archivo puede necesitar dos referencias. Una migración de Rails o Alembic necesita su archivo de lenguaje y sql.md, y el detector lo informa. Un lenguaje sin archivo de referencia aún recibe una revisión completa. Los ángulos generales a continuación lo cubren, y debes aplicar lo que sepas sobre las trampas comunes de ese lenguaje. Los lenguajes incrustados también cuentan: las cadenas SQL en Python, o los comandos de shell construidos en Go, son una razón para cargar sql.md o shell.md.

3. Construir contexto más allá del diff

El diff muestra qué cambió, no qué afecta. Antes de juzgar nada:

  • Lee el código circundante de cada hunk, no solo las líneas modificadas. Muchos errores viven en cómo las líneas nuevas interactúan con las antiguas.
  • Encuentra los llamadores y dependientes de cada función, tipo, esquema, clave de configuración o endpoint modificado (grep, LSP find-references). El radio de explosión es invisible desde el diff.
  • Aprende las convenciones del proyecto: configuraciones de linter y formateador, CLAUDE.md/CONTRIBUTING.md, y cómo el código cercano maneja errores, registro y pruebas. Juzga la consistencia contra esta base de código, no contra el gusto general.
  • Busca helpers existentes antes de aceptar nuevo código de utilidad. Reimplementar algo que el repositorio ya tiene solo se descubre cuando miras fuera del diff.

4. Revisar por ángulo, en orden de prioridad

Trabaja desde arriba de esta lista hacia abajo. Un error en el nivel 1 importa más que cualquier cantidad de notas del nivel 3. references/review-angles.md tiene la lista de verificación completa para cada ángulo; léelo para cualquier revisión no trivial.

  1. ¿Es correcto? Corrección y casos límite, fidelidad a la intención (¿hace lo que afirma, completamente?), manejo de errores y modos de fallo, concurrencia y estado compartido, radio de explosión en los llamadores.
  2. ¿Es seguro enviarlo? Seguridad, compatibilidad de API/esquema/red, integridad de datos y migraciones, operatividad (despliegue, reversión, observabilidad), nuevas dependencias, privacidad.
  3. ¿Es buen código? Rendimiento y eficiencia, altitud (¿la corrección está en la capa correcta?), duplicación y reutilización, simplicidad frente a sobreingeniería, consistencia con las convenciones, legibilidad.
  4. ¿Está verificado? Pruebas que realmente fallarían sin el cambio, documentación y comentarios sincronizados.

Aplica las comprobaciones del archivo de lenguaje cargado dentro de estos ángulos. Son las formas específicas que toman estos problemas en ese lenguaje.

5. Verificar cada hallazgo antes de reportarlo

Para cada posible hallazgo:

  • Escribe el escenario de fallo: entrada o estado concreto, luego el resultado incorrecto. Si no puedes, probablemente no es un error.
  • Vuelve a leer el código para comprobar que el problema no ya está manejado: una guarda río arriba, un validador, un tipo que lo descarta, una prueba que lo cubre.
  • Ejecútalo cuando sea barato y seguro (una prueba unitaria, un fragmento en REPL, el verificador de tipos o linter) y el hallazgo sea incierto.
  • Clasifica la confianza: Confirmado (rastreado o reproducido) o Plausible (camino creíble que no pudiste probar completamente). Descarta cualquier cosa más débil. Si algo no está claro pero es inofensivo plantearlo, pregúntalo como una pregunta en lugar de afirmar un error.

6. Informar

Usa references/reporting.md para las etiquetas de severidad, el formato de comentario y la plantilla de salida. En resumen:

  • Comienza con un veredicto de una línea: si es seguro fusionar y el mayor problema, si lo hay.
  • Cada hallazgo comienza con su etiqueta de severidad: [CRÍTICO], [MAYOR], [MENOR] o [NIT], luego una afirmación de una línea y su archivo:línea. El cuerpo explica, en este orden, cuál es el problema, por qué es un problema (el escenario de fallo concreto) y una corrección o mejora sugerida siempre que puedas ofrecer una.
  • Lista los hallazgos comenzando por los más severos. Límite predeterminado de unos 10. Menciona cuántos elementos de menor severidad omitiste, y listalos si el usuario lo pide.
  • Mantén los [NIT] fuera a menos que no haya defectos reales, o el usuario haya pedido un pase exhaustivo.
  • Termina con lo que no cubriste (archivos hojeados, cosas que no pudiste ejecutar). Una nota honesta de alcance es parte de la revisión.

Usa el mismo formato de etiqueta primero para los comentarios publicados en un pull request, para que un hallazgo se lea igual en el informe y en el PR. Publica en el PR solo cuando el usuario te lo pida; references/reporting.md muestra cómo publicarlos como una sola revisión con comentarios en línea.

Si el host proporciona una herramienta estructurada de hallazgos, informa a través de ella en el mismo orden en lugar de imprimir la lista, y aún así comienza el resumen de cada hallazgo con su etiqueta.

Principios

  • Evidencia sobre opinión. Cada hallazgo cita código. "Considera X" sin una razón es ruido.
  • Revisa el cambio, no el código base. Señala problemas preexistentes solo cuando el cambio los empeora o depende de ellos, y etiquétalos como preexistentes.
  • Respeta las elecciones del autor. Un enfoque diferente pero igualmente válido no es un hallazgo. Discrepa solo cuando puedas nombrar un costo concreto.
  • No corrijas durante la revisión a menos que te lo pidan. Sugiere correcciones; deja que el usuario decida si aplicarlas.

Skills relacionados