Subagentes de Claude Code — división de roles vía la herramienta Task

La fortaleza de Claude Code que la mayoría de los usuarios adoptan al final son los subagentes (la herramienta Task). Hacerlo todo en una sola sesión llena el contexto del agente padre rápidamente, y los trabajos grandes quedan embotellados en un único hilo. Tratar los subagentes como una capa de abstracción — Explorer busca y resume, Reviewer solo ve el diff — permite gestionar el doble de trabajo en el mismo tiempo.

Esta guía está orientada a Claude Code 1.x. Lleva el flujo de trabajo diario un nivel más alto más allá de la configuración de Claude Code y los hooks.

TL;DR

1. El padre gestiona ediciones directas + builds/tests: trabajo corto y rápido
2. Subagente Explorer: "¿Dónde está X en este codebase?" Busca y resume. No arrastra grandes resultados al padre
3. Subagente Plan: devuelve solo un plan paso a paso para cambios grandes
4. Subagente Reviewer: revisión de segunda opinión del diff del padre
5. Specialist: subagentes específicos de dominio como claude-api / security-review

Principio fundamental: protección de contexto + paralelismo.

Requisitos previos

• Claude Code 1.x instalado — Configuración de Claude Code
• Elementos básicos del proyecto en su lugar: CLAUDE.md + .claude/settings.json
• (Opcional) línea base de hooks — algunos hooks del padre también se aplican a los subagentes

1. Modelo de llamada de la herramienta Task (cómo funciona)

Dentro de Claude Code, la herramienta Task lanza un nuevo agente con un único prompt. El subagente tiene su propia ventana de contexto: no comparte mensajes con el padre, y solo el mensaje de resultado final regresa.

Agente padre
   │
   ├─ Task("Explore", "encontrar la lógica de validación de tokens en src/auth/; devolver solo nombres de función + rutas de archivo")
   │   ↓ (contexto separado, hasta 100k tokens libres)
   │   ↑ "validateToken: src/auth/verify.ts:42"  ← el padre recibe solo el resultado
   │
   └─ Task("Reviewer", "escanear el diff del último commit en busca de problemas de seguridad")
       ↓
       ↑ "1 hallazgo: src/api/user.ts:88 — posible inyección SQL"

Solo un resumen final se añade al contexto del padre. El subagente puede haber leído 200 archivos; el padre recibe una única línea.

2. Cuatro patrones principales

2.1 Explorer: aislar grandes resultados de búsqueda

El patrón más común. Delegar preguntas de "¿dónde está X definido?" a un subagente.

"Delegar a un subagente Explorer:
'Encontrar la definición del hook useAuth + todos sus usos en src/. Devolver
- def: archivo:línea
- usos: archivo:línea × todos
Limitar a un resumen de 30 líneas. No incluir cuerpos de código.'"

El padre recibe 30 líneas. Si se hiciera directamente, habría consumido 5–20K tokens vía grep + lecturas de múltiples archivos.

Cuándo usar:

• Al entrar por primera vez a un codebase desconocido
• "¿Dónde está definida esta función?"
• "¿Cómo estamos usando esta biblioteca?"
• Análisis de impacto de dependencias

Uso incorrecto:

• Búsquedas pequeñas: el padre puede hacer grep en una línea
• Resultados que el padre necesita leer completos: leer directamente es más rápido

2.2 Plan: solo el plan paso a paso para cambios grandes

Para cambios de 5+ archivos / nuevos módulos / cambios de arquitectura, el subagente Plan hace investigación + análisis de tradeoffs y devuelve solo el plan.

"Delegar a un subagente Plan:
'Devolver solo un plan de ejecución paso a paso.
Requisito: expandir seeds de ~7/categoría a 10.
Restricciones: build en menos de 1 min, verify:assets 100%.
Salida: tabla de categoría · tema · tiene-asset · líneas estimadas + orden de escritura.
No escribir código.'"

El padre recibe el plan; la ejecución ocurre en el padre o se reparte entre otros subagentes.

2.3 Reviewer: segunda opinión

Un agente con contexto independiente revisa el diff del padre. Los ojos frescos detectan lo que el padre pasa por alto.

"Delegar a un subagente Reviewer:
'Revisar el diff del commit 4d2f0 desde un ángulo de seguridad.
Específicamente: inyección SQL, XSS, secretos hardcodeados, condiciones de carrera.
Salida: N hallazgos + archivo:línea + nota de 1 línea cada uno. O "limpio".'"

El agente padre pasa por alto problemas en su propio código porque lo conoce. El Reviewer aborda el mismo problema desde una perspectiva diferente.

2.4 Specialist: específico de dominio

Subagentes para áreas específicas (claude-api, security-review, code-reviewer, build-validator, etc.) con conocimiento de dominio profundo y formatos de salida apropiados para cada área.

"Delegar a security-review:
'Evaluación de seguridad completa de los cambios de la rama actual.
Alcance: authn / authz / validación de entrada / secretos / sesiones / CSRF.'"

Los specialists suelen tener system prompts ajustados a su área, lo que mejora la calidad del resultado.

3. Escribir el prompt de delegación (autónomo)

El subagente no ve el contexto del padre. El prompt debe ser autónomo y completo por sí mismo.

Buen prompt

"Encontrar estos patrones en src/:
- llamadas `fetch(...)` donde baseURL está hardcodeada
- Resultado: archivo:línea + 1 línea de código + dominio baseURL inferido
- Límite 30; si hay más, añadir '+N más'
- No adjuntar cuerpos de código — solo línea"

Prompts incorrectos

"Revisar esa cosa de fetch de antes"   ← sin contexto, vago

"Encontrar todas las llamadas fetch"   ← sin formato de salida, riesgo de output enorme

Lista de verificación para redactar el prompt

• Objetivo: qué se quiere saber
• Ámbito: dónde buscar (directorio/archivo/rango)
• Formato de salida: tabla / a nivel de línea / longitud del resumen
• Exclusiones: qué NO devolver (cuerpos de código, diffs grandes)
• Condición de parada: N hallazgos y luego parar
• Caso desconocido: "si no lo sabes, dilo; sin adivinar"

4. Ejecución en paralelo: enviar delegaciones independientes juntas

El trabajo independiente puede incluirse en una única respuesta con múltiples llamadas Task. Claude Code las lanza en paralelo.

"Tres delegaciones a la vez:
1) Explorer — resumir dónde viven los archivos de autenticación
2) Explorer — resumir el historial de migraciones de BD
3) Reviewer — revisión de seguridad de los últimos 5 commits

Después de recibir las tres, hacer un análisis integrado."

El padre recibe las tres simultáneamente. Tiempo total dividido entre 3.

No paralelizar cuando:

• La salida de A es la entrada de B: deben ser secuenciales
• Dos tareas editan el mismo archivo: riesgo de condición de carrera

5. Gestión de contexto: delegar vs. directo

Regla general: si la tarea consumiría el 20 % del contexto del padre, considerar delegarla.

6. Escenarios reales de uso

A. Entrar a un codebase desconocido

1. Explorer — resumen de estructura de carpetas + 5 módulos clave
2. Explorer — puntos clave de README + CLAUDE.md (si existe)
3. Explorer — resumen de los últimos 10 commits
↓
4. Padre — sintetizar en "un párrafo sobre este repositorio"

B. Cambio de 5+ archivos

1. Plan — alcance del cambio + pasos + tabla de riesgos
2. Padre — revisar el plan, proceder paso a paso
3. Después de cada paso, Reviewer — revisión del diff
4. Antes del commit final, Reviewer — segunda opinión del cambio completo

C. Depuración

1. Padre — definir log de error + ruta de reproducción
2. Explorer — rastrear rutas de código relacionadas (desde el stack trace)
3. Padre — hipotizar + intentar corrección
4. Padre — verificar con build/test

D. Justo antes del merge del PR

1. Reviewer — revisión de seguridad/rendimiento del diff
2. Reviewer — consistencia de convenciones con el código existente
3. Specialist (security-review) — evaluación completa
4. Padre — consolidar hallazgos en comentarios del PR o correcciones

7. Combinación con Hooks

Los hooks PreToolUse de Claude Code también pueden interceptar las llamadas Task.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Task",
        "hooks": [
          {
            "type": "command",
            "command": "/bin/bash -lc 'echo \"[delegado] $(jq -r .tool_input.description)\" >> ~/.claude/delegate.log'"
          }
        ]
      }
    ]
  }
}

Registrar los conteos y el contenido de las delegaciones permite revisar qué se delegó frente a qué se hizo directamente. Útil para el seguimiento de costes y el aprendizaje de patrones.

8. Antipatrones: mal uso de la delegación

8.1 Delegar todo

"Delegar incluso una edición de 1 archivo"   ← solo añade sobrecarga

Las llamadas a subagentes tienen coste en tokens y tiempo. Convertir un trabajo de 1 segundo en una delegación de 30 segundos es un desperdicio.

8.2 El padre vuelve a buscar después de delegar

"Explorer resume las ubicaciones de archivos de auth → el padre luego hace grep de los mismos archivos"

→ La delegación es inútil. Confiar en el resultado y pasar al siguiente paso.

8.3 Pedir demasiado output

"Traer el código completo de cada archivo + explicación de 5 líneas + cuerpos de uso"

→ La delegación no reduce el contexto del padre. Limitar el tamaño del output en el prompt.

8.4 Delegación en paralelo con dependencias

"El resultado de A alimenta a B, pero ambos se delegan al mismo tiempo"

→ B no conoce el resultado de A y produce suposiciones erróneas. Lo secuencial es lo correcto.

9. Matriz de distribución: quién hace qué

Pasos siguientes

• Configuración de Claude Code — base del agente padre
• Hooks de Claude Code — registrar/validar delegaciones
• Flujo de trabajo multi-agente — escenarios de integración multi-herramienta/agente
• Agent runner — ejecuciones autónomas + subagentes combinados

Referencias

• Claude Code oficial — herramienta Task
• Anthropic — Patrones de diseño de agentes — principios generales

Registro de cambios

• 2026-05-12 — Borrador inicial (devAlice M3 seed expansion)