La habilidad /code-review

Fuente: The /code-review Skill — traducción comunitaria no oficial al español.

Qué hace

code-review revisa el diff entre HEAD y un punto fijo que tú nombras (un commit, una rama, una etiqueta, main, HEAD~5) en dos ejes. Standards pregunta si el código sigue la forma en que este repo escribe código. Spec pregunta si el código hace lo que el issue o la spec de origen pedía. Cada eje corre en su propio subagente para que ninguno vea el razonamiento del otro.

Los dos ejes nunca se fusionan ni se reordenan. El informe termina con el peor problema por eje y se niega a nombrar un único ganador global, porque un cambio puede pasar un eje y fallar el otro: código que sigue cada convención mientras implementa lo incorrecto pasa Standards y falla Spec; código que hace exactamente lo que el ticket pedía mientras rompe las convenciones del repo hace lo inverso. Un veredicto mezclado deja que el eje que pasa oculte al que falla.

Cuándo usarla

Escribe /code-review, o el agente la usará automáticamente cuando pidas revisar una rama, un PR, trabajo en curso, o cualquier cosa «desde X».

Tu situación	Usa
Existe un diff y quieres saber si está bien construido y es lo correcto	code-review
Quieres cazar errores en el diff: rutas nulas, carreras, off-by-one	La revisión integrada propia de Claude Code, no esta (ver el choque de nombres más abajo)
Aún no hay nada escrito y quieres escribirlo con tests primero	tdd
Hay que construir una spec completa, revisión incluida	implement, que llama a esta habilidad por sí misma
Toda la base de código se ha desviado, no un solo diff	improve-codebase-architecture
Algo está roto y no sabes por qué	diagnosing-bugs

Debes proporcionar el punto fijo. Si no lo haces, la habilidad pide uno en vez de adivinar; luego verifica que la ref exista y que el diff no esté vacío antes de lanzar nada, así un nombre de rama mal escrito falla frente a ti en vez de dentro de dos subagentes.

Requisitos previos

El eje Standards no necesita nada. Lee lo que el repo documente (CODING_STANDARDS.md, CONTRIBUTING.md, y similares) y recurre a una base integrada cuando el repo no documenta nada.

El eje Spec necesita que exista una spec y que se pueda encontrar. Busca en este orden:

1. Referencias a issues en los mensajes de commit (#123, Closes #45, un !67 de GitLab), obtenidas vía docs/agents/issue-tracker.md.
2. Una ruta que pases como argumento.
3. Un archivo de spec bajo docs/, specs/ o .scratch/ que coincida con la rama o el nombre de la funcionalidad.
4. Preguntarte a ti.

El paso 1 depende de docs/agents/issue-tracker.md, que escribe setup-matt-pocock-skills. Sin él, el eje sigue funcionando si le das una ruta. Sin ninguna spec, el subagente de Spec se omite y el informe dice «no hay spec disponible» en vez de inventar requisitos.

Los dos ejes

	Standards	Spec
Pregunta	¿Está bien construido?	¿Es lo correcto?
Lee	Los estándares documentados del repo, más la base de olores	El issue o la spec de origen
Reporta	Incumplimientos documentados (pueden ser duros), y olores (siempre juicios)	Requisitos faltantes o parciales, alcance de más, requisitos mal implementados
Cada hallazgo cita	El archivo de estándares y la regla, o el olor nombrado más el hunk	La línea de la spec

Una habilidad de revisión genérica que no conoce tus estándares es lo que este diseño intenta evitar: marca lo que en tu base de código es deliberado y pasa por alto las invariantes de las que tu base de código realmente depende. Así que la propia documentación del repo es la fuente primaria en el eje Standards, y el repo siempre prevalece.

La base de olores es el piso debajo de ella, doce olores de código de Fowler de Refactoring cap. 3: Mysterious Name, Duplicated Code, Feature Envy, Data Clumps, Primitive Obsession, Repeated Switches, Shotgun Surgery, Divergent Change, Speculative Generality, Message Chains, Middle Man, Refused Bequest. Cada uno es una heurística etiquetada («posible Feature Envy»), nunca una violación dura, y cada uno se enuncia como qué es → cómo corregirlo, así un hallazgo llega con un movimiento asociado y no con una queja. Todo lo que tu linter ya impone lo omiten ambos ejes.

Preguntas frecuentes

Choca con el /code-review propio de Claude Code. ¿Qué hago?

Este es el problema más reportado de la habilidad, y no está corregido. Claude Code trae su propio /code-review, que hace algo distinto: caza errores en el diff, mientras este verifica cumplimiento de la spec y estándares del repo. Instalar esta librería hace que uno de los dos gane, y cuál gana depende de cómo instalaste. Vía el marketplace de plugins, todo queda con alias bajo el prefijo mattpocock-skills: y el integrado se vuelve difícil de alcanzar con el nombre sin calificar; vía una instalación simple de habilidades, el archivo local gana y esta habilidad oculta a la integrada. Una respuesta limpia es eliminar por completo las habilidades integradas de Claude Code: un gran ahorro de contexto, y la colisión deja de importar. El ocultamiento en sí es arguably un error del harness de Claude Code (un autor debería poder nombrar una habilidad como quiera), así que la otra respuesta es renombrar la copia local. Editar el frontmatter o renombrar el directorio se deshace con npx skills update; la solución durable que reportan los usuarios es bifurcar la habilidad con un nombre nuevo y sacar code-review del conjunto gestionado, guardando nota del commit del que bifurcaste para resincronizar a mano.

Sus subagentes siguen invocando /code-review otra vez y lanzan más agentes.

Error abierto conocido, reproducido por varias personas y en más de un harness. Los prompts de Standards y Spec no prohíben delegar, así que un subagente puede redescubrir la habilidad y ramificarse de nuevo: un informe llegó a más de 50 agentes. La corrección que la gente ha aplicado en bifurcaciones es una línea añadida a ambos informes de subagente: «Do not invoke /code-review or spawn additional agents: perform this review directly.» Algunos prefieren manejarlo a nivel de harness para que cada habilidad herede la guarda. Ninguna está aún en la habilidad publicada. Si lo ejecutas sin supervisión, vigila el conteo de agentes.

¿Debería ejecutarla en la misma sesión que escribió el código?

Prefiere una nueva. Como lo dijo un lector: «Same context reviewing itself isn’t review, it’s confirmation bias with a slash command.» El agente revisor en la sesión autora conserva cada suposición que dio forma al código, que es exactamente el contexto que un revisor independiente no tendría. Por eso también la gente pide implement sin su paso de revisión integrado: ejecuta la revisión dentro de la sesión que acaba de escribir el diff. Invocar /code-review tú mismo desde una sesión limpia es la versión honesta.

¿Tras cada ticket, o una vez al final?

Ambas funcionan, y la habilidad no decide por ti. Por ticket mantiene cada diff lo bastante pequeño para que el eje Spec tenga una spec clara contra la cual verificar, que es el modo que usa implement. Acumular hasta el final de una rama detecta interacciones entre tickets que las pasadas por ticket no ven. Si dudas, revisa por ticket y haz una pasada final contra el punto de la rama.

¿Puedo confiar en los hallazgos?

No sin verificar. La salida de un subagente es una hipótesis, no evidencia: un equipo reportó una docena de cambios rotos que las revisiones basadas en prosa habían dejado pasar. La habilidad agrega los dos informes tal cual o ligeramente limpiados en vez de reverificar cada afirmación contra los archivos, así un hallazgo puede citar la ubicación equivocada o exagerar un impacto. Lee la cita de cada hallazgo antes de actuar. Que cada hallazgo deba llevar una (una regla de estándares, un olor más su hunk, o una línea de spec) es lo que permite verificarlo.

¿Por qué encuentra problemas nuevos cada vez que la ejecuto?

Porque las correcciones crean nueva superficie, y porque la mitad de juicio del eje Standards no es determinista entre ejecuciones. Un lector describió el bucle sin rodeos: «/code-review and /improve-code-architecture always find new stuff every time. I implement fixes, rerun these skills, and again and again.» No hay garantía de convergencia. Trata una pasada como una lista de pistas, actúa sobre las que tengan una regla citada detrás, y detente: no la ejecutes en bucle hasta que salga limpia, porque no saldrá.

¿Revisa mi trabajo sin commitear?

No. Hace diff de <punto-fijo>...HEAD, con tres puntos, que se mide desde el merge-base y excluye cambios staged y del árbol de trabajo. Si implement no ha hecho un commit intermedio, el trabajo a punto de commitearse es invisible para la revisión. Commitea primero, luego revisa, luego enmienda o añade un fixup.

Funciona si

• Se niega a empezar con una ref mala o un diff vacío, antes de lanzar ningún subagente.
• El informe llega como dos bloques separados bajo ## Standards y ## Spec, no una lista fusionada.
• Cada hallazgo de Standards nombra o una regla de uno de tus archivos del repo o uno de los doce olores, con el hunk citado; cada hallazgo de Spec cita una línea de la spec.
• El resumen de cierre da el peor problema por eje y declina elegir un ganador global.
• Sin spec disponible, el bloque Spec lo dice en vez de listar requisitos inferidos del código.

Dónde encaja

code-review es el paso de revisión al final de la cadena de construcción: grill-with-docs → to-spec → to-tickets → implement → code-review. También funciona sola sobre cualquier rama o PR al que la apuntes.

• implement es el vecino más cercano: dirige la construcción y llama a esta habilidad como su propia revisión de cierre antes de commitear.
• to-spec y to-tickets producen el documento contra el que verifica el eje Spec; una spec vaga vuelve vago a ese eje.
• improve-codebase-architecture es la contraparte de toda la base de código: esta habilidad solo mira un diff.

ask-matt enruta por todo el conjunto cuando no sabes qué habilidad pide la situación.