Subagente revisor de código en Claude Code, paso a paso

Un subagente revisor de código en Claude Code es un archivo Markdown en .claude/agents/ que define un asistente aparte, con su propio prompt, sus herramientas y su propio contexto. Con tools: Read, Grep, Glob no puede editar nada: revisa los archivos que le pasas con una lista fija y devuelve hallazgos con archivo, línea y severidad.

Este tutorial arma ese revisor paso a paso, explica cada campo del archivo y muestra qué devolvió en nuestras pruebas con Claude Code 2.1.238 sobre un archivo con errores puestos a propósito. Es la parte 6 de nuestra serie de Claude Code; la anterior, el hook que corre el linter tras cada edición, se ocupa del formato y las reglas, y este revisor de lo que un linter no ve.

Qué es un subagente y por qué sirve para revisar

Un subagente es un asistente que la sesión principal de Claude Code puede llamar para una tarea concreta. Según la documentación de subagentes, cada uno arranca con una ventana de contexto nueva y aislada: no ve tu historial de conversación, ni las skills que ya usaste, ni los archivos que Claude ya leyó. La sesión principal le escribe un mensaje con la tarea, el subagente trabaja con eso y, al terminar, devuelve un resultado.

Para una revisión, esas dos condiciones son justo lo que quieres:

• No arrastra las suposiciones del autor. Si Claude escribió la función hace diez minutos, sabe lo que quiso hacer y tiende a leer eso en el código. El revisor solo tiene el archivo.
• Sus lecturas no llenan tu contexto. Puede abrir el archivo, sus imports y buscar tests; a tu conversación solo vuelve el informe.

La diferencia con pedirle a la misma sesión «revisa lo que hiciste» se ve mejor lado a lado:

El archivo .claude/agents/revisor-codigo.md

Un subagente es un archivo Markdown con un bloque YAML arriba (el frontmatter) y el prompt debajo. Si lo guardas en .claude/agents/ dentro del proyecto, vale para ese repositorio y lo puedes versionar para el equipo; en ~/.claude/agents/ vale para todos tus proyectos. Si dos tienen el mismo nombre, gana el del proyecto. Este es el revisor completo:

---
name: revisor-codigo
description: Revisor de código de solo lectura. Úsalo de forma proactiva al terminar un cambio, antes de un commit o un PR, o cuando el usuario pida una revisión. Pásale la lista de archivos que cambiaron.
tools: Read, Grep, Glob
model: sonnet
---

Eres un revisor de código. Solo lees: no tienes herramientas para editar y no
reescribes archivos completos en tu respuesta.

Revisa solo los archivos que te indiquen en la tarea. Si no te indican ninguno,
responde «Necesito la lista de archivos que cambiaron» y termina. Puedes abrir
otros archivos para entender el contexto (lo que importan, sus tests), pero no
los revises.

Recorre esta lista en cada archivo:

1. Seguridad: secretos en el código, entradas sin validar, URLs, consultas o
   comandos armados con texto que llega de fuera, datos personales en logs.
2. Manejo de errores: catch vacíos, respuestas HTTP que no se revisan, errores
   que se pierden, código que sigue como si nada hubiera fallado.
3. Tests: lógica nueva o cambiada sin un test que la cubra. Antes de decir que
   no hay tests, búscalos con Glob y escribe en el hallazgo el patrón que usaste.
4. Nombres: funciones o variables cuyo nombre no dice lo que hacen.
5. Rendimiento: llamadas de red o consultas dentro de un bucle, trabajo que se
   repite sin necesidad.

Responde con este formato y nada más:

## Resumen
Una o dos frases: qué revisaste y si lo dejarías pasar a un commit.

## Hallazgos
- [bloqueante|importante|menor] archivo:línea — qué pasa. Por qué importa. Cómo arreglarlo.

Ordénalos de bloqueante a menor. Si no hay ninguno, escribe «Sin hallazgos».

## Lista
- Seguridad: ok | N hallazgos
- Manejo de errores: ok | N hallazgos
- Tests: ok | N hallazgos
- Nombres: ok | N hallazgos
- Rendimiento: ok | N hallazgos

No inventes problemas para llenar la lista. Si un hallazgo depende de código que
no viste, dilo en vez de suponer.

Solo name y description son obligatorios. Los cuatro campos que usa este archivo:

Hay más campos opcionales, como disallowedTools para quitar herramientas a una lista heredada o maxTurns para cortar un subagente que da demasiadas vueltas. Para un revisor no hacen falta.

Por qué solo Read, Grep y Glob

tools es lo que convierte al revisor en uno de solo lectura. Sin Edit ni Write no puede cambiar archivos, y sin Bash no puede correr comandos, tampoco uno que escriba en disco. Que el prompt diga «no edites» es una petición; que la herramienta no exista es un límite.

El ejemplo de revisor de la documentación oficial sí incluye Bash, para que el propio revisor corra git diff y vea qué cambió. Funciona, pero con Bash el revisor puede correr cualquier comando. Aquí elegimos lo contrario: la sesión principal, que sí tiene Bash, sabe qué archivos cambiaron y se los pasa en la tarea. Si prefieres que el revisor corra git diff por su cuenta, la misma documentación muestra cómo limitar Bash con un hook PreToolUse declarado dentro del subagente, como el de la parte 4 de la serie.

La checklist del revisor

Un revisor sin criterio fijo comenta lo primero que ve. Este recorre cinco puntos en el mismo orden en cada archivo:

1. Seguridad. Secretos en el código, entradas sin validar, URLs o consultas armadas con texto que llega de fuera, datos personales en logs.
2. Manejo de errores. catch vacíos, respuestas HTTP que nadie revisa, errores que se pierden y código que sigue como si nada hubiera fallado.
3. Tests. Lógica nueva o cambiada sin un test que la cubra.
4. Nombres. Funciones o variables cuyo nombre no dice lo que hacen.
5. Rendimiento. Llamadas de red o consultas dentro de un bucle, trabajo repetido.

El punto de tests tiene una instrucción extra que salió de nuestras pruebas. En la primera versión del archivo decía «busca los tests con Glob antes de decir que no existen». El informe afirmó que había buscado con Glob, pero la transcripción del subagente mostraba una sola llamada: Read del archivo. Cambiamos la línea para que escriba en el hallazgo el patrón que usó, y en las dos corridas siguientes el revisor buscó con Glob (**/*cupones*, **/*.test.ts, **/*.spec.ts y otros patrones) antes de concluir que no había tests. Pedir la evidencia dentro del informe hace que la búsqueda ocurra y que tú la puedas comprobar.

El formato de respuesta también es fijo: un resumen de una o dos frases, los hallazgos con [bloqueante|importante|menor] archivo:línea ordenados de mayor a menor, y la lista con cuántos hallazgos hubo en cada punto. Un formato fijo te deja comparar revisiones y, más adelante, leerlas desde un script.

Cómo invocarlo

Claude Code vigila .claude/agents/ y detecta un archivo nuevo o editado en pocos segundos, sin reiniciar. La excepción: si la carpeta agents no existía cuando abriste la sesión, reinicia una vez. Hay tres formas de usar el revisor:

• Por su nombre, en lenguaje natural. «Usa el subagente revisor-codigo para revisar src/cupones.ts». Es lo que usamos en las pruebas. Si quieres que revise lo último que cambiaste, pídele a Claude que le pase los archivos que muestra git diff --name-only.
• Con una mención. Escribe @ y elige el subagente en la lista; queda como @"revisor-codigo (agent)". Así te aseguras de que la tarea va a ese subagente y no a otro.
• Como sesión completa. claude --agent revisor-codigo arranca una sesión donde el hilo principal toma el prompt, las herramientas y el modelo del revisor.

Además, Claude puede delegar solo cuando la tarea encaja con la description. Por eso la del revisor dice cuándo usarlo («al terminar un cambio, antes de un commit o un PR») y qué necesita («pásale la lista de archivos»). En versiones recientes, el comando /agents ya no abre un asistente: solo recuerda que edites los archivos de .claude/agents/ directamente o se lo pidas a Claude.

El informe: qué devolvió en nuestra prueba

El archivo de prueba, src/cupones.ts, viene en el ZIP de la guía como ejemplo/cupones.ts. Son 20 líneas que calculan el total de un carrito con un cupón y tienen problemas puestos a propósito: una clave escrita en el código y enviada en la URL, un codigo sin codificar, un fetch por línea dentro de un bucle, un catch vacío y ningún test. Así se vio la revisión:

La captura recorta seis de los ocho hallazgos para que quepa; los marcadores entre corchetes indican dónde. El revisor encontró los cinco problemas plantados y añadió dos que no habíamos contado: ninguna de las dos respuestas de fetch revisa r.ok, y el total puede quedar negativo si el descuento es mayor que la compra. Lo que sí varió entre corridas fueron los nombres: en la primera señaló que calcular es demasiado genérico y en las dos siguientes dejó «Nombres: ok». Un revisor hecho con un modelo no escribe el mismo informe dos veces.

Dos detalles prácticos. Primero, lo que lees en tu sesión es lo que la sesión principal te cuenta del informe. En la primera prueba, Claude lo reescribió con sus propios títulos y emojis; desde entonces le pedimos «muéstrame su informe tal cual». Segundo, el costo: cada revisión de este archivo de 20 líneas costó unos 0,15 USD según el campo total_cost_usd de la salida JSON, con la sesión en Haiku y el revisor en Sonnet. Es una cifra de nuestra prueba, no una tarifa: crece con el tamaño de lo que revisa.

Solo lectura de verdad

Para comprobar el límite, arrancamos una sesión como el revisor y le pedimos un cambio, con las ediciones autorizadas de antemano:

claude --agent revisor-codigo -p "Corrige el catch vacío de src/cupones.ts" --permission-mode acceptEdits

Respondió: «No puedo editar archivos: soy un revisor de solo lectura (mis herramientas son Read/Grep/Glob, sin Write ni Edit)», y entregó la revisión con el arreglo sugerido para que lo aplicáramos nosotros. git status confirmó que src/cupones.ts seguía igual.

Límites del revisor

• Un informe es una afirmación. Ya viste el caso de Glob. Cada subagente deja su transcripción en ~/.claude/projects/<proyecto>/<sesión>/subagents/; si un hallazgo importa, revisa qué herramientas usó de verdad.
• No sabe qué cambiaste. Arranca sin tu historial. Si no le pasas los archivos, su prompt le dice que pida la lista en lugar de revisar el repositorio entero.
• No reemplaza tus tests ni tu CI. Lee código; no lo ejecuta. Un error que solo aparece al correr el código no lo va a ver.
• No conoce tus convenciones salvo las que estén en CLAUDE.md, que sí carga, o en su propio prompt.
• Cuesta tokens aparte. Lee los archivos otra vez en su propio contexto. Con Sonnet o un modelo más grande, revisar diez archivos grandes no es gratis.

Errores comunes

• Omitir tools. Sin ese campo, el subagente hereda todas las herramientas, Edit y Bash incluidas. Un «revisor» así puede reescribir lo que revisa.
• Una description vaga. «Revisa código» no le dice a Claude cuándo delegar. Di el momento (antes de un commit) y lo que necesita (la lista de archivos).
• Esperar que sepa qué cambió. No ve tu conversación. Pásale los archivos, o deja que la sesión principal los saque de git diff.
• Un prompt sin formato de salida. Cada revisión sale distinta y no hay forma de compararlas.
• Creer el informe sin mirar. Si dice que buscó tests, la transcripción debería mostrar esa búsqueda.
• Crear la carpeta con la sesión abierta. Si .claude/agents/ no existía al arrancar, Claude Code no la vigila hasta que reinicias.

Preguntas frecuentes

¿En qué se diferencia un subagente de una skill?

Una skill añade instrucciones a la conversación en la que estás; un subagente trabaja en un contexto aparte, con sus propias herramientas, y solo devuelve el resultado. Para una revisión independiente conviene lo segundo. La comparación completa está en skills, subagentes, hooks y plugins.

¿Puede el revisor corregir lo que encuentra?

Este no, a propósito. Si quieres que alguien corrija, pídeselo a la sesión principal con el informe delante: así decides tú qué hallazgos se aplican. Un subagente que revisa y corrige a la vez necesita Edit, y deja de ser un revisor.

¿Qué modelo conviene para revisar?

La documentación usa sonnet en su ejemplo y es lo que usamos aquí. Con haiku es más barato; en una de nuestras pruebas, Haiku pidió el archivo con una ruta mal armada. Con inherit usa el modelo de tu sesión.

¿Se puede usar en un pull request de GitHub?

Sí, porque el archivo vive en el repositorio y Claude Code lo encuentra también cuando corre en un runner. Cómo llevar Claude Code a tu CI está en la parte 9 de la serie.

¿Puedo tener varios revisores?

Sí: uno de seguridad, otro de accesibilidad, otro de rendimiento, cada uno con su archivo y su description. Escribe descripciones que no se pisen, para que Claude sepa a cuál delegar cada tarea.

Checklist

• .claude/agents/revisor-codigo.md existe en el proyecto y está versionado.
• El frontmatter tiene name, description y tools: Read, Grep, Glob.
• La description dice cuándo usarlo y que necesita la lista de archivos.
• El prompt tiene la lista de cinco puntos y un formato de respuesta fijo.
• Probaste con ejemplo/cupones.ts y el informe trae severidad, archivo y línea.
• Le pediste una edición con --agent y se negó.

Con el revisor en el proyecto, cada cambio puede pasar por una segunda lectura con criterio fijo antes de llegar a un commit. Si todavía no tienes los pasos anteriores, empieza por el hook que protege tu .env y el hook del linter; para decidir qué revisar antes de escribir una línea, sigue con plan mode. Los agentes de Playwright, que también son subagentes, están en agentes de Playwright con Claude Code, y el método completo en mi flujo de 4 pasos con Claude Code.

¿Viste esto en Instagram? Comenta REVISOR en el Reel o el carrusel y te mando la guía.