Cap 3: Sub-Agents

Qué son los Sub-Agents

Los sub-agents son agentes especializados que Claude Code puede invocar para delegar tareas. Cada agente tiene su propio contexto, herramientas permitidas y sistema de permisos.

Cómo funciona

Claude Code usa internamente la herramienta Agent (también llamada Task) para lanzar sub-agentes. Cada sub-agente:

1. Recibe un prompt específico
2. Opera con herramientas restringidas
3. Retorna un resultado al agente principal
4. Puede ejecutarse en background o en un worktree aislado

Ubicaciones

Ruta	Alcance
.claude/agents/	Proyecto (commiteable)
~/.claude/agents/	Global (usuario)

Cada agente es un archivo Markdown con frontmatter de configuración.

Crear un sub-agent

<!-- .claude/agents/code-reviewer.md -->
---
name: code-reviewer
description: "Revisa código enfocándose en calidad, seguridad y best practices"
tools: ["Read", "Grep", "Glob", "Bash"]
model: sonnet
maxTurns: 10
---

Eres un revisor de código senior. Analiza el código proporcionado enfocándote en:

1. **Seguridad**: inyecciones, XSS, secretos expuestos
2. **Calidad**: funciones pequeñas, DRY, naming
3. **Performance**: queries N+1, loops innecesarios
4. **Tests**: cobertura adecuada

Reporta hallazgos con severidad (crítico/alto/medio/bajo).

Frontmatter completo

Campo	Tipo	Descripción
name	string	Nombre del agente
description	string	Cuándo invocar este agente
tools	string[]	Herramientas permitidas
disallowedTools	string[]	Herramientas explícitamente denegadas
model	string	sonnet, opus, haiku, inherit
permissionMode	string	Modo de permisos del agente
maxTurns	number	Máximo de turnos agentic
skills	string[]	Skills precargados en el contexto
mcpServers	array	Servidores MCP disponibles
hooks	object	Hooks específicos del agente
memory	boolean	Si puede acceder a auto-memory
background	boolean	Ejecutar en background
isolation	string	"worktree" para aislamiento git
color	string	Color en la interfaz

Invocación

Los sub-agents se invocan automáticamente cuando Claude Code determina que una tarea coincide con la descripción del agente. También puedes forzar la invocación:

# Listar agentes disponibles
claude agents

# Iniciar sesión con agente específico
claude --agent code-reviewer

Agentes vía CLI flag

Puedes definir agentes dinámicamente con --agents:

claude --agents '{
  "reviewer": {
    "description": "Expert code reviewer",
    "prompt": "You are a senior code reviewer. Focus on quality and security.",
    "tools": ["Read", "Grep", "Glob"],
    "model": "sonnet"
  }
}'

Restricción de herramientas

Herramientas disponibles

tools:
  - Read          # Leer archivos
  - Edit          # Editar archivos
  - Write         # Crear archivos
  - Bash          # Ejecutar comandos
  - Glob          # Buscar archivos
  - Grep          # Buscar contenido
  - Agent         # Lanzar sub-agentes
  - WebFetch      # Obtener contenido web
  - WebSearch     # Buscar en la web

Restringir qué agentes pueden spawnearse

tools:
  - Read
  - Grep
  - "Agent(code-reviewer)"  # Solo puede lanzar code-reviewer

Scopes de agentes

Los agentes siguen el mismo sistema de scopes que settings:

• User scope (~/.claude/agents/): disponibles en todos los proyectos
• Project scope (.claude/agents/): específicos del proyecto

Los agentes del proyecto tienen prioridad sobre los globales si tienen el mismo nombre.

Agentes builtin

Claude Code incluye agentes internos predefinidos:

Agente	Función
Explore	Exploración rápida del codebase
Plan	Diseño de planes de implementación
general-purpose	Investigación y tareas multi-paso

Ejemplo: Agente de testing

<!-- .claude/agents/test-writer.md -->
---
name: test-writer
description: "Crea tests unitarios y de integración para código nuevo"
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
model: sonnet
maxTurns: 15
---

Eres un ingeniero de QA experto. Cuando recibas código:

1. Analiza la función/componente
2. Identifica casos de prueba (happy path, edge cases, errores)
3. Escribe tests usando el framework del proyecto
4. Ejecuta los tests y corrige fallos
5. Verifica cobertura mínima del 80%

---

Siguiente: Skills