Cómo construir un subagente en Claude Code para revisión de PRs

Cómo construir tu primer subagente en Claude Code — Tutorial paso a paso con un caso útil: por ejemplo, un agente revisor de PRs o generador de tests

Tiempo estimado de lectura: 4 min

Patrón práctico: contexto acotado + reglas estrictas + output accionable para integrar IA en pipelines.
Dos casos: revisor de PRs (diff) y generador de tests (por archivo).
Implementación: scripts CLI que usan Claude Code, prompts versionados y hooks/CI para automatizar.
Precauciones: controlar tokens, contexto parcial y mantener revisión humana para decisiones críticas.

Entender cómo construir tu primer subagente en Claude Code — Tutorial paso a paso con un caso útil: por ejemplo, un agente revisor de PRs o generador de tests, es el salto práctico entre usar IA como chat y convertirla en un componente automatizado de tu pipeline de desarrollo. Aquí tienes un tutorial accionable, sin humo: código, prompts y reglas para que funcione de verdad.

Resumen rápido (lectores con prisa)

Un subagente es un script que envía contexto limitado (diff o archivo) a Claude Code con un prompt versionado. Úsalo cuando la tarea sea repetitiva y pueda expresarse con reglas claras. La clave: reducir contexto, reglas estrictas y automatizar en hooks/CI.

Cómo construir tu primer subagente en Claude Code — paso a paso

Requisitos mínimos

Node.js y npm.
Cuenta y credenciales de Anthropic (Claude Code).
Repositorio Git con cambios en una rama distinta a main.

Instalación rápida

Instala la CLI de Claude Code y autentica:

npm install -g @anthropic-ai/claude-code
claude auth

(Referencia: npm package @anthropic-ai/claude-code)

1. Define el System Prompt (qué puede y qué no puede hacer)

El System Prompt es la barrera entre ruido y valor. Guarda uno en la raíz: .claude-reviewer-prompt.md.

Contenido recomendado:

Eres un Staff Engineer realizando una revisión de código.
Recibirás un `git diff`. Tu objetivo es identificar problemas críticos.

Reglas:
1. Ignora formato y estilo (linters ya hacen eso).
2. Busca: vulnerabilidades, condiciones de carrera, mutaciones de estado no controladas y complejidad innecesaria.
3. Si hay nueva lógica sin tests, marca "Missing Tests" como error crítico.
4. Responde en Markdown. Si todo está correcto, responde solo: "✅ Código limpio. Listo para PR."

Sé explícito: lo que no está en las reglas, está fuera del subagente.

2. Script que orquesta el subagente (claude-pr-review.sh)

Extrae el diff y pásalo al modelo. Crea /scripts/claude-pr-review.sh:

#!/bin/bash
DIFF=$(git diff main...HEAD -- ':!**/package-lock.json' ':!**/dist/**')

if [ -z "$DIFF" ]; then
  echo "No hay cambios para revisar."
  exit 0
fi

PROMPT=$(cat .claude-reviewer-prompt.md)

claude --print --prompt "$PROMPT

Aquí tienes el diff:
\`\`\`diff
$DIFF
\`\`\`"

Notas:

Excluye archivos generados para ahorrar tokens (-- ':!path').
claude --print muestra la respuesta en terminal; puedes redirigirla a un archivo.

3. Variante: generador de tests por archivo

Mismo patrón, distinto input. Crea /scripts/claude-gen-tests.sh:

#!/bin/bash
FILE_PATH=$1
if [ ! -f "$FILE_PATH" ]; then
  echo "Archivo no encontrado: $FILE_PATH"
  exit 1
fi

claude --print --prompt "Actúa como SDET especializado en TypeScript.
Genera tests unitarios con Jest para el siguiente archivo. Usa mocking donde aplique. Devuelve solo el código del test.

Archivo:
$(cat $FILE_PATH)" > "${FILE_PATH%.*}.test.ts"

El resultado es un punto de partida. No lo aceptes ciegamente: revisa los mocks y aserciones.

4. Integración práctica: Hooks y CI

Un script manual se olvida. Integra el revisor en un hook pre-push (Husky) o como job en CI.

Ejemplo Husky (.husky/pre-push):

#!/bin/sh
./scripts/claude-pr-review.sh || exit 1

Si detecta un problema crítico, el script puede devolver exit 1 y bloquear el push.

En CI, ejecuta el script y falla el job si el output contiene palabras clave (ej. “Missing Tests” o “Error crítico”).

5. Limitaciones y buenas prácticas

Coste de tokens: pasar un diff enorme puede ser caro. Filtra archivos irrelevantes. Regla práctica: apunta a menos de ~20k tokens por invocación.
Contexto parcial: el subagente solo ve lo que le das (diff o archivo). Los falsos positivos aparecen cuando la lógica depende de archivos no incluidos.
No es reemplazo de humanos: automatiza lo repetitivo; deja decisiones arquitectónicas a desarrolladores senior.
Versiona prompts y scripts: audítalos como cualquier herramienta crítica.

6. Decisión rápida: cuándo usar un subagente local

Usa subagentes locales si:

La tarea es repetitiva y repite reglas claras (seguridad simple, checklists de arquitectura).
Tienes un disparador claro (push, PR, commit).
Puedes limitar el contexto para controlar coste y precisión.

Evítalos cuando:

Requieres análisis de arquitectura completa de un monorepo.
Necesitas pruebas end-to-end dependientes de infra externa.

Conclusión (y lo que sigue)

El patrón es simple y poderoso: reduce ruido dando contexto acotado y reglas firmes. Implementa el revisor y el generador de tests como base, obsérvalos un par de semanas, afina el prompt y automatiza su ejecución en hooks o CI. Esto no acaba aquí: un subagente bien definido se convierte en una pieza de infraestructura que reduce fricción y libera criterio humano para lo que realmente importa.

Dominicode Labs

Para equipos que investigan automatización y agentes en pipelines, puede ser útil explorar recursos y experimentos adicionales en Dominicode Labs. Considera esto como una continuación lógica para prototipar y versionar subagentes en un entorno experimental controlado.

FAQ

¿Qué es un subagente en este contexto?
¿Cómo protejo credenciales y datos sensibles?
¿Cuándo el subagente debe fallar un push?
¿Cómo controlo el coste de tokens?
¿Puedo usar otros modelos o proveedores?
¿Cómo versiono y audito prompts?

¿Qué es un subagente en este contexto?

Un subagente es un componente automatizado que envía contexto específico (por ejemplo, un git diff o el contenido de un archivo) a un modelo (Claude Code) junto con un prompt versionado y reglas, para producir output accionable usado en pipelines de desarrollo.

¿Cómo protejo credenciales y datos sensibles?

Almacena credenciales en entornos seguros (secrets en CI, variables de entorno en el sistema) y evita pasar archivos que contengan secretos en los diffs enviados al modelo. Versiona prompts pero no incluyas secretos en ellos.

¿Cuándo el subagente debe fallar un push?

Haz que falle cuando detecte errores críticos claramente definidos en el prompt (por ejemplo, “Missing Tests” o “Error crítico”). Mantén una lista pequeña y precisa de condiciones que realmente justifiquen bloquear un push.

¿Cómo controlo el coste de tokens?

Filtra archivos irrelevantes, limita el tamaño del diff y prioriza invocaciones por carpeta o por cambios significativos. Regla práctica: apunta a menos de ~20k tokens por invocación.

¿Puedo usar otros modelos o proveedores?

Sí. El patrón (contexto acotado + reglas estrictas + output accionable) es agnóstico al proveedor. Ajusta comandos y prompts según la API/CLI del proveedor seleccionado.

¿Cómo versiono y audito prompts?

Guarda prompts en el repositorio (por ejemplo, .claude-reviewer-prompt.md) y trata los cambios como código: revisiones, PRs y registro de cambios. Audítalos como cualquier herramienta crítica operativa.