Cómo usar subagentes en Claude Code

Un subagente es una instancia especializada de Claude que el agente principal invoca para una tarea concreta. Tiene tres propiedades clave: su propia ventana de contexto (no ensucia la conversación principal), su propio prompt de sistema y su propia lista de herramientas permitidas. Cuando termina, devuelve solo un resumen al hilo principal. Esto es lo que lo hace valioso en proyectos grandes: puedes mandar a un subagente a leer 40 archivos y el contexto principal solo recibe las conclusiones. Primero asegúrate de tener una versión reciente de Claude Code. Si lo instalaste con el instalador nativo, se actualiza solo, pero puedes forzarlo. Si aún lo tienes instalado vía npm de hace tiempo, migra al instalador nativo: es el método recomendado y evita problemas de permisos en macOS y Linux. En Windows usa el instalador de PowerShell que indica la documentación oficial. Después entra en tu repo y arranca una sesión para comprobar que todo responde.

# macOS / Linux / WSL: instalador nativo
curl -fsSL https://claude.ai/install.sh | bash

# Comprueba versión y estado de la instalación
claude --version
claude doctor

# Entra en tu proyecto y arranca una sesión
cd ~/proyectos/mi-api
claude

Los subagentes son archivos Markdown con frontmatter YAML. Los de proyecto viven en .claude/agents/ dentro del repo y los personales en ~/.claude/agents/; si hay dos con el mismo nombre, gana el de proyecto. El frontmatter define name (identificador en minúsculas con guiones), description (cuándo debe usarse), tools (lista separada por comas; si la omites, hereda todas las herramientas de la sesión, incluidas las de MCP) y model (un alias como sonnet, opus o haiku, o inherit para usar el mismo modelo que la sesión principal, que por defecto es claude-opus-5-5). Todo lo que va debajo del frontmatter es el prompt de sistema. Vamos a crear un revisor de código de solo lectura más Bash, para que pueda ejecutar git diff pero no editar archivos. Fíjate en que el prompt da un procedimiento concreto y un formato de salida: eso es lo que convierte un subagente mediocre en uno fiable.

mkdir -p .claude/agents
cat > .claude/agents/code-reviewer.md <<'EOF'
---
name: code-reviewer
description: Revisor de código senior. Úsalo PROACTIVAMENTE justo después de escribir o modificar código, y siempre antes de un commit, para revisar calidad, seguridad y mantenibilidad.
tools: Read, Grep, Glob, Bash
model: inherit
---
Eres un revisor de código senior con foco en seguridad y mantenibilidad.

Cuando te invoquen:
1. Ejecuta `git diff HEAD` para ver los cambios recientes.
2. Céntrate solo en los archivos modificados.
3. Revisa: legibilidad, nombres, duplicación, manejo de errores, secretos expuestos, validación de entradas y cobertura de tests.

No modifiques archivos. Devuelve el resultado con este formato:

## Crítico (bloquea el merge)
## Advertencias
## Sugerencias

Cada punto con archivo:línea y un ejemplo de cómo corregirlo.
Si no hay cambios, dilo en una línea y termina.
EOF

Dentro de una sesión de Claude Code escribe /agents. Se abre un panel interactivo donde ves los subagentes disponibles, separados por origen (proyecto, usuario y los que aporten plugins), y desde el que puedes crear uno nuevo, editarlo o borrarlo. La opción de crear con ayuda de Claude es buena para arrancar: describes qué quieres y genera un borrador del prompt, que luego conviene recortar y endurecer a mano. Lo más útil del panel es el selector de herramientas: muestra la lista completa de herramientas disponibles en tu sesión, incluidas las de servidores MCP, así que es la forma más segura de restringir permisos sin equivocarte con los nombres. Comprueba que code-reviewer aparece en la sección de proyecto. Si editaste el archivo a mano con la sesión abierta y no ves los cambios, cierra y vuelve a abrir Claude Code para forzar la recarga.

Hay dos maneras de usar un subagente. La automática: Claude lee las descriptions de todos los subagentes y, si la tarea encaja, delega por su cuenta. Pídele que implemente algo y, si la description del revisor está bien escrita, al terminar lanzará code-reviewer sin que lo menciones. La explícita: nombras el subagente en tu prompt. Es la que debes usar cuando necesites determinismo, por ejemplo en scripts o en el modo no interactivo con -p, que es útil para pipelines de CI. Mientras el subagente trabaja verás en la interfaz que se está ejecutando una tarea delegada; al terminar, solo su resumen entra en el contexto principal. Observa la diferencia de consumo: una revisión que leería una docena de archivos en el hilo principal llega ahora como un informe de una pantalla. Prueba ambos modos con el siguiente bloque.

# Modo interactivo: invocación explícita dentro de la sesión
# > Usa el subagente code-reviewer para revisar mis cambios antes del commit

# Modo no interactivo (útil en scripts o CI)
claude -p "Usa el subagente code-reviewer para revisar los cambios actuales y devuelve solo la sección Crítico"

# Prueba la delegación automática: no menciones el subagente
claude -p "Añade validación del campo email en src/users/create.ts y deja el código listo para commit"

El potencial real aparece con varios subagentes especializados. Vamos a añadir un explorador de solo lectura con un modelo rápido y barato (haiku) para investigar el código, y un test-runner con permisos de edición que ejecuta tests y corrige fallos. Con eso puedes encadenar: explorador para entender, implementación en el hilo principal, test-runner para validar y code-reviewer para cerrar. También puedes paralelizar: pide a Claude que lance varios exploradores a la vez sobre módulos distintos; cada uno trabaja en su propio contexto y el principal recibe los resúmenes. En monorepos esto reduce drásticamente el tiempo de investigación. Ajusta el comando de tests del prompt a tu stack (pytest, npm test, go test…). Usar haiku para exploración y reservar opus para el hilo principal también reduce el gasto de uso, algo que se nota en equipos de España y LATAM que facturan en dólares.

cat > .claude/agents/explorer.md <<'EOF'
---
name: explorer
description: Investigador de código de solo lectura. Úsalo para localizar dónde se implementa algo, mapear dependencias o entender un módulo antes de modificarlo.
tools: Read, Grep, Glob
model: haiku
---
Investiga el código sin modificar nada. Devuelve:
- Archivos relevantes con ruta y propósito en una línea
- Flujo de llamadas principal
- Riesgos o acoplamientos detectados
Máximo 40 líneas. Nada de volcar archivos completos.
EOF

cat > .claude/agents/test-runner.md <<'EOF'
---
name: test-runner
description: Especialista en tests. Úsalo PROACTIVAMENTE tras cualquier cambio de código para ejecutar la suite y corregir los fallos sin cambiar la intención de los tests.
tools: Read, Edit, Bash, Grep, Glob
model: sonnet
---
1. Ejecuta `npm test` (adáptalo a tu stack).
2. Si algo falla, localiza la causa raíz y corrige el código de producción.
3. Solo modifica un test si es claramente incorrecto, y justifícalo.
4. Repite hasta que todo pase o hasta 3 intentos.
Devuelve: tests ejecutados, fallos encontrados, cambios hechos.
EOF

# Dentro de la sesión, prueba la paralelización:
# > Lanza tres subagentes explorer en paralelo: uno para src/auth, otro para src/billing y otro para src/notifications. Luego resume cómo se comunican entre sí.

Los subagentes de proyecto son código: súbelos al repo para que todo el equipo comparta el mismo revisor, el mismo test-runner y los mismos criterios. Revisa los cambios en los prompts igual que revisas código, porque un cambio en una description altera cuándo se delega. Complementa con una línea en CLAUDE.md que indique el flujo esperado (explorar, implementar, testear, revisar). Para depurar, aplica esta lista: si no se delega, reescribe la description centrada en el cuándo; si el subagente no hace algo, revisa su campo tools en /agents; si la respuesta llega pobre, recuerda que el subagente arranca sin el historial de tu conversación, así que el hilo principal debe pasarle contexto suficiente en la petición; si la tarea es trivial, no delegues: arrancar un subagente tiene latencia y a veces es más rápido hacerlo en el hilo principal.

# Añade el flujo al CLAUDE.md del proyecto
cat >> CLAUDE.md <<'EOF'

## Flujo con subagentes
- Antes de tocar un módulo desconocido: subagente explorer.
- Tras cualquier cambio: test-runner y después code-reviewer.
- No hagas commit si code-reviewer reporta algo en Crítico.
EOF

# Versiona los subagentes con el resto del proyecto
git add .claude/agents CLAUDE.md
git commit -m "chore: añade subagentes explorer, test-runner y code-reviewer"
git push