Claude Code subagents: cómo separar contexto, permisos y trabajo paralelo sin perder control
Claude Code subagents prometen contexto limpio y trabajo paralelo. La diferencia entre aceleración y caos está en herramientas, permisos, memoria y handoffs.
Claude Code subagents prometen contexto limpio y trabajo paralelo. La diferencia entre aceleración y caos está en herramientas, permisos, memoria y handoffs.
Claude Code subagents son agentes especializados que trabajan en una ventana de contexto aislada, con su propio prompt de sistema, lista de herramientas, modelo, permisos y, si lo configuras, memoria o MCP propios. Sirven para delegar trabajo acotado sin llenar la conversación principal con búsquedas, logs y lecturas de archivos.
Recibe una lectura semanal de herramientas IA para devs
Si estás montando Claude Code con subagents, Skills, hooks y MCP, DevAI Semanal te resume cada semana lo importante en un email de 5 minutos para devs.
Suscribirme gratisChecklist
Cuándo sí merece la pena usar subagents
La señal más clara es volumen de contexto. Si una tarea requiere leer muchos archivos, comparar patrones, revisar logs largos o investigar opciones que luego se reducen a una recomendación, un subagent encaja bien. Por ejemplo: auditoría de seguridad de un módulo, investigación de una migración, revisión de un PR grande, diagnóstico de un fallo intermitente o recopilación de impacto antes de refactorizar.
También encajan cuando quieres restringir capacidades. Un `code-reviewer` puede tener solo `Read`, `Grep` y `Glob`. Un `test-runner` puede tener `Read`, `Grep`, `Glob` y comandos de test concretos. Un `docs-writer` puede editar documentación pero no tocar migraciones ni deployment. La gracia es que la frontera sea técnica, no decorativa.
No los usaría para cambios pequeños ni para tareas que requieren conversación constante. Claude Code también recomienda mantener la tarea en la conversación principal cuando hay refinamiento frecuente, latencia sensible o varias fases que comparten mucho contexto. Lanzar subagents por costumbre añade overhead y puede fragmentar decisiones.
La salida importa más que el rol. Pide que devuelva una tabla corta con severidad, archivo, evidencia, impacto y recomendación. Si el subagent vuelve con una narración genérica, no has ganado señal; solo has movido ruido a otro sitio.
Permisos: tools, disallowedTools y permissionMode
El campo `tools` funciona como allowlist. Si lo omites, el subagent hereda herramientas disponibles en la sesión principal, incluidos MCP configurados. Esa herencia es cómoda y peligrosa: un reviewer que solo debía leer puede terminar con Bash, editores o herramientas externas si no lo acotas.
Puntos a revisar
Lo que conviene comprobar
`disallowedTools` sirve para heredar casi todo salvo una parte concreta, por ejemplo bloquear `Write` y `Edit`. Si defines ambos, Claude Code aplica primero la denylist y luego resuelve la allowlist contra lo que queda. En equipos, prefiero allowlists pequeñas para roles críticos y denylist solo cuando el rol necesita muchas herramientas normales salvo una familia concreta.
`permissionMode` cambia cómo se gestionan aprobaciones dentro del subagent: `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions` o `plan`. El valor más tentador es también el más delicado. `bypassPermissions` salta prompts y puede permitir operaciones con impacto alto. Úsalo solo en entornos muy acotados, no como solución a la fatiga de aprobar comandos.
Handoffs, hooks y trazabilidad
El punto débil de cualquier flujo multiagente es el handoff. El agente principal delega una tarea; el subagent vuelve con una respuesta; alguien decide si actuar. Si esa respuesta no trae evidencia verificable, el aislamiento de contexto se convierte en una caja negra.
Para tareas críticas, exige formato de retorno: objetivo interpretado, archivos inspeccionados, comandos ejecutados, hallazgos, confianza, cambios propuestos y límites de la investigación. Si hay acciones de escritura, pide diff separado y pruebas ejecutadas. Un subagent que no puede explicar su ruta no debería desbloquear una decisión.
Claude Code permite hooks para eventos de subagent como inicio y parada. Eso abre controles útiles: preparar entorno temporal para un agente de base de datos, limpiar credenciales después de una sesión, registrar qué subagent se ejecutó o validar que un rol no arranca fuera de su directorio esperado. Los hooks no reemplazan revisión humana, pero sí convierten parte de la disciplina en control repetible.
Checklist
Trabajo paralelo sin mezclar diffs
Los subagents invitan a paralelizar, pero el paralelismo bueno separa investigación y evidencia, no criterio técnico. Un patrón sano sería lanzar un subagent de impacto, otro de tests y otro de documentación, mientras la persona o la sesión principal decide el diseño. El patrón malo es lanzar tres implementadores contra la misma zona del repo y esperar que Git resuelva la arquitectura.
Si un subagent va a modificar archivos, considera `isolation: worktree`. Claude Code documenta que esta opción ejecuta el subagent en un worktree temporal con una copia aislada del repositorio. Eso ayuda a evitar que un worker pise el estado de la sesión principal y hace más clara la revisión de cambios.
No mezcles salidas de varios subagents en un commit gigante. Revisa por rol: primero investigación, luego tests, luego implementación, luego documentación. Si dos agentes tocaron los mismos archivos, pausa la integración y decide manualmente qué intención gana.
Después de dos semanas, mira qué roles se activaron de verdad, cuáles devolvieron señal y cuáles generaron ruido. Borra o fusiona los que no tengan uso claro. La madurez no se mide por número de agentes, sino por menos contexto desperdiciado y revisiones más claras.
Errores comunes
El primer error es heredar todas las herramientas. Si un subagent de revisión puede editar, ejecutar comandos amplios y llamar a MCP externos, no estás limitando nada. Estás confiando en que el prompt se porte bien.
Puntos a revisar
Lo que conviene comprobar
El segundo error es usar subagents para ocultar incertidumbre. Si el agente principal no sabe qué quiere, delegar no arregla el problema. El subagent necesita una frontera: investiga esto, revisa estos archivos, ejecuta estos tests, devuelve esta evidencia.
El tercer error es confundir auto mode o bypass con seguridad. El artículo técnico de Anthropic sobre auto mode deja claro que los clasificadores reducen fatiga y capturan parte del riesgo, pero no sustituyen juicio humano en infraestructura crítica. En subagents, esa advertencia pesa más porque el worker opera fuera de tu vista inmediata.
Preguntas frecuentes
¿Qué son Claude Code subagents?
Claude Code subagents son agentes especializados que Claude Code puede invocar para trabajar en un contexto aislado con prompt, herramientas, modelo y permisos propios.
¿Dónde se guardan los subagents de Claude Code?
Los subagents de proyecto suelen vivir en `.claude/agents/` y los personales en `~/.claude/agents/`, definidos como archivos Markdown con frontmatter YAML.
¿Qué diferencia hay entre subagents y Skills?
Un Skill empaqueta instrucciones reutilizables dentro del contexto del agente; un subagent crea un contexto separado para una tarea delegada y devuelve un resumen o resultado.
¿Un subagent puede usar MCP?
Sí. Puede heredar MCP de la sesión principal o declarar `mcpServers` en su frontmatter para conectar herramientas específicas al arrancar.
¿Es seguro usar permissionMode bypassPermissions en subagents?
Solo en entornos muy acotados y revisables. Para trabajo normal conviene usar allowlists, permisos conservadores, hooks y revisión humana antes de mezclar cambios.
Fuentes y referencias
También te puede interesar
Claude Code: guía completaClaude Code Skills y SKILL.mdHooks para agentes de códigoAGENTS.md y CLAUDE.md: memoria de proyectoCoordinar Codex, Claude Code y CursorRecibe una lectura semanal de herramientas IA para devs
Cada semana te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.
Suscribirme gratis
