SubAgentes en Claude Code

Contexto

Un subagente en Claude Code es un asistente especializado que corre una tarea en su propio contexto —con su propio system prompt, sus tools y sus permisos— y devuelve solo el resultado a la conversación principal. Sirve cuando una tarea secundaria (investigar el codebase, revisar un diff) inundaría tu contexto con archivos y logs que no vas a volver a mirar.

Ojo con un malentendido común: el subagente aísla contexto dentro de una sesión; no es "paralelismo" por sí mismo. Para correr muchas sesiones en paralelo de verdad, Claude Code tiene background agents y agent teams. El subagente es, sobre todo, una herramienta de gestión de contexto.

Configuración / setup

• Ad-hoc: pídelo explícito — "usa un subagente para investigar cómo funciona el refresh de tokens".
• Reutilizable: define un subagente en .claude/agents/<nombre>.md con frontmatter (name, description, tools, model) y un system prompt enfocado. Claude delega según la description.

---
name: security-reviewer
description: Revisa código en busca de vulnerabilidades
tools: Read, Grep, Glob, Bash
model: opus
---
Eres un ingeniero de seguridad senior. Revisa: inyección (SQL, XSS),
authz, secrets hardcodeados y manejo inseguro de datos. Da línea y fix.

Estado a julio 2026. La ubicación (.claude/agents/) y el formato del frontmatter pueden cambiar.

Ejemplos

Dos usos de alto valor:

1. Investigación sin ensuciar el contexto:
   "Usa subagentes para investigar cómo manejamos el estado de auth y si
    ya tenemos utilidades de OAuth para reusar."
   → el subagente lee 20 archivos en su contexto y te devuelve 1 resumen.
 
2. Revisión con ojos frescos:
   "Usa un subagente para revisar este diff buscando edge cases."
   → un modelo fresco juzga el resultado sin el sesgo de haberlo escrito.

El caso natural en el curso (testing): un subagente por función del dominio, cada uno genera sus tests con su propio contexto, sin contaminarse entre sí.

Particularidades

• Ventaja: preservas contexto (la exploración vive en otra ventana) y puedes limitar qué tools usa cada subagente.
• Ventaja: el revisor en subagente no arrastra el sesgo de quien escribió el código.
• Matiz clave: no es paralelismo entre sesiones — eso son background agents / agent teams. El subagente trabaja dentro de tu sesión.
• Cuándo NO: tareas que necesitan coordinación fuerte entre sí o que comparten fixtures complejos; ahí una secuencia en la sesión principal es más simple.