Skill de code review que solo reporta fallos demostrados

TL;DR

• La regla que la separa de la mayoría de las revisiones con IA: nada se reporta sin un fallo demostrado — cada hallazgo nombra la entrada, el estado o la secuencia que produce el resultado equivocado, y lo que no se liga a uno se descarta en silencio.
• Revisa en el orden en que revisa un senior: diseño, conformidad con la spec, corrección, complejidad, tests, nombres, radio de impacto — porque el problema de diseño es el caro.
• Lee los comentarios ya existentes en el PR después de su propia auditoría, nunca antes, para no quedar anclada al encuadre de otra persona.
• Es un archivo Markdown más una referencia cargada bajo demanda — unas 1.700 palabras de criterio, no una checklist de 2.000 ítems.

Qué es y para quién

Code Review Skill es una skill de revisión de código para agentes de IA — Claude Code, Cursor, Codex, Gemini CLI y cualquier cosa que lea SKILL.md. El README describe el objetivo en una línea: un agente, una pasada, unas 1.700 palabras.

Es para quien dejó de leer la salida de revisión de IA. El diagnóstico del README es que la mayor parte de la revisión automática produce un muro de hallazgos plausibles donde la mitad son reales y la mitad son conjeturas, y el lector no distingue cuál es cuál, así que deja de leer. Esta skill hace el intercambio opuesto.

Qué hace distinto

Evidencia o silencio. Sin escenario de fallo, sin hallazgo. No hay apéndice de "posibles problemas, sin verificar" — ese apéndice es el ruido que el lector evitaba, con otro nombre.

Nunca adivina donde puede leer. Un hallazgo condicionado a investigación sin terminar — "esto rompe a menos que el backend lo valide" — no vale cuando el backend está ahí en el repositorio.

Severidad honesta. Impacto por probabilidad, con piso explícito, porque una etiqueta Critical en un problema pequeño cuesta más credibilidad de la que valía el hallazgo.

Diseño antes que detalle. Y aplica un contra-test a todo refactor: cuenta los conceptos que el lector debe sostener. Si la versión "más limpia" deja esa cuenta igual, la complejidad se movió de sitio, no se redujo.

Ojos nuevos primero. Los comentarios ya existentes en el pull request se leen después de la auditoría, nunca antes, porque leerlos antes ancla al revisor y cuesta los hallazgos que solo ojos nuevos producen.

Solo el alcance del diff. Un problema previo en un archivo no tocado no es un hallazgo.

Las clases que se escapan. Autorización comprobada en el login pero no en este objeto concreto. Crecimiento de alcance reportado como hallazgo, no como bonus. Una migración que no es reversible a mitad del rollout. Una variable de entorno o puerto cambiado que rompe el build local de todos. Un bump masivo de dependencias sin leer el changelog.

Borra sus propios hallazgos débiles. Una pasada final descarta lo que el revisor no defendería en voz alta ante el autor — y el README dice que eso quita más hallazgos malos de los que cualquier checklist añade buenos.

Obedece a tu repositorio. CONTRIBUTING.md, CLAUDE.md, AGENTS.md, .cursor/rules/ y la config de lint superan a la skill, y lo que el linter o el type checker ya reporta queda fuera de la mesa.

Cómo usarla

En Claude Code, por el marketplace de plugins:

/plugin marketplace add artificialguybr/code-review-skill
/plugin install code-review

Para otro agente, la skill es un archivo Markdown sin dependencias, sin claves de API y sin servicio externo:

git clone https://github.com/artificialguybr/code-review-skill /tmp/crs
cp -r /tmp/crs/skills/code-review ~/.claude/skills/code-review   # o .claude/skills para un proyecto

Cursor lee .cursor/skills/, Codex .codex/skills/, Gemini CLI .gemini/skills/ — mismo directorio, destino distinto.

Después pide en la forma que ya usas:

review my changes
review this branch against main
review PR #418
is this safe to merge?
review my changes and fix what you find

Un número de PR pasa por gh. Si no, la skill fija el merge base con tu rama de seguimiento y revisa git diff <base>...HEAD con tres puntos, para que los commits que aterrizaron en la rama base no ensucien la revisión.

Por qué es corta

La skill entera son dos archivos: skills/code-review/SKILL.md, siempre cargado, y references/traps.md, con defectos por lenguaje más revisión de dependencias, que carga solo bajo demanda. El argumento del README es que las skills de revisión más pesadas no son las mejores, y que una checklist de 2.000 ítems hace que el modelo trabaje la lista en vez de leer el código.

Aprobar como un colega

Dos reglas cubren el criterio que las herramientas suelen equivocar. Aprueba cuando el cambio claramente mejora la salud del código, aunque sea imperfecto — "no es como yo lo habría escrito" no es un defecto. Pero sin sellos: un "LGTM" no ganado dice a todos los de abajo que el cambio se comprobó cuando no fue así.

Nunca corrige por supresión. Cuando se le pide corregir sus propios hallazgos, cada corrección lleva el test de regresión que habría atrapado el problema, y nada de catch más ancho, regla de lint desactivada o aserción aflojada.

Cuándo usarla, cuándo no

Úsala para revisión real de una rama o un pull request, sobre todo cuando quieres saber cuáles de los hallazgos son defectos de verdad, y cuando el diff toca autorización, migraciones o dependencias, donde las clases que se escapan son caras.

No la uses como sustituto de una suite de tests. La skill lee código y propone el test que habría atrapado cada hallazgo; no ejecuta tu suite. Y no esperes que atrape problemas previos en archivos que el cambio no toca — el límite de alcance es deliberado, y es lo que mantiene la revisión barata.

Sources

1. Code Review Skill — repositorio — reglas, orden de revisión, comandos de instalación, estructura de archivos y licencia citados arriba.
2. README.md — comandos de instalación y uso, licencia.

Página del proyecto: Code Review Skill

La skill tiene licencia MIT y acepta issues y pull requests; la preferencia declarada en el README es una regla que atrapó un bug real antes que una que suena exhaustiva.

FAQ

¿Cuánto dura la revisión? Una pasada, unas 1.700 palabras de criterio en SKILL.md, más un archivo de referencia que carga solo cuando aparece una duda de lenguaje o de dependencia.

¿Por qué descarta hallazgos? Porque un hallazgo que no se liga a un fallo demostrado es una conjetura; descartarlo mantiene el reporte legible, y el README dice que eso quita más hallazgos malos de los que una checklist añade buenos.

¿Lee los comentarios ya existentes del PR? Sí, pero solo después de su propia auditoría, para no quedar anclada al encuadre de otra persona.

¿Corrige lo que encuentra? Cuando se le pide, sí. Cada corrección lleva el test de regresión que habría atrapado el hallazgo, sin catch más ancho, regla de lint desactivada ni aserción aflojada.