Subagents en Claude Code: Guía Práctica (2026)

por Jasmine, una dev que usa Claude Code y subagents todos los días.

¿Qué son los subagents en Claude Code?

Un subagent es una instancia especializada de Claude que el agente principal puede lanzar para encargarse de una tarea concreta, corriendo en su propia ventana de contexto, con su propio system prompt y su propio conjunto de herramientas, y devolviendo luego un resultado condensado al agente principal. En resumen: en lugar de dejar que un solo Claude cargue con todo el trabajo dentro de una única conversación, repartes el trabajo entre pequeños asistentes, cada uno un agente de IA especializado en un único rol.

Imagina el agente principal como una líder técnica. Cuando llega un trabajo grande, digamos "revisa todo el código en busca de problemas de seguridad", la líder técnica no lee cada archivo en su propia cabeza. Se lo pasa a una especialista en seguridad que lee, resume y le trae el resultado. Un subagent es exactamente esa especialista: tiene una descripción de la tarea (el system prompt), recibe ciertos permisos (herramientas) y, cuando termina, devuelve solo la conclusión que de verdad necesitas.

La diferencia central respecto a solo escribir más instrucciones en la misma sesión: los subagents de Claude Code tienen un contexto aislado. Toda la información intermedia que un subagent necesita leer para hacer su trabajo vive en su "cabeza" y nunca se desborda de vuelta a la sesión principal. Declaras cada subagent con un simple archivo Markdown colocado en el directorio .claude/agents/, y Claude Code los detecta automáticamente.

¿Cómo funcionan los subagents? (aislamiento de contexto)

El mecanismo detrás de los subagents se llama aislamiento de contexto. Esa es la verdadera razón por la que vale la pena usar subagents, y no solo "levantar otra IA para lucirse".

Una ejecución típica se ve así:

1. El agente principal toma tu petición y decide qué tarea debe delegarse a un subagent.
2. Lanza el subagent correspondiente junto con una descripción específica de la tarea.
3. El subagent corre en su propia ventana de contexto, un "sandbox cognitivo". Lee archivos, ejecuta comandos y razona sobre el problema, todo en su propio espacio.
4. Al terminar, el subagent devuelve solo un resultado condensado (un resumen, una lista de bugs, un fragmento de código), en lugar de volcar todo el proceso en la sesión principal.

You
 └─► Main agent (main context, lean)
 ├─► subagent: test-runner ──► returns: 2 tests failing
 ├─► subagent: security-scan ──► returns: 1 SQLi vulnerability
 └─► subagent: style-checker ──► returns: 5 lint warnings
 (each subagent = its own context window)

Como un subagent "se traga" el contexto pesado (leer decenas de archivos, logs largos) y solo exhala la esencia, tu sesión principal conserva un contexto limpio que dura más. Esto es en parte ahorro de tokens (el contexto principal no se infla) y en parte una cuestión de calidad: el agente principal no se contamina con ruido intermedio, así que su razonamiento se mantiene más afilado. El mecanismo y el alcance los describe Anthropic en la documentación oficial de Subagents de Claude Code (consultada en 08/2026).

Ayuda distinguir esto de abrir una nueva pestaña de chat a mano. Cuando chateas manualmente en varias sesiones, eres tú quien copia resultados de un lado a otro: lento y fácil de que se te escape algo. Con subagents, el agente principal orquesta todo el flujo: decide qué delegar, a quién, y vuelve a coser los resultados automáticamente dentro de un único turno de trabajo. Nunca tienes que salir de la terminal.

Algo que la gente suele malinterpretar: el aislamiento de contexto no vuelve al subagent "más tonto". Sigue siendo la misma línea de modelo que elegiste, solo que enfocado en exactamente una tarea, con exactamente las herramientas que necesita. Acotar el alcance normalmente mejora el resultado, no lo empeora, como darle un trabajo claro a una especialista en vez de pedirle a una persona que haga diez cosas a la vez.

Crea tu primer subagent: el archivo .claude/agents

Esta es la parte central y práctica. Hay dos formas de crear un subagent: usar la interfaz /agents (recomendada la primera vez) o escribir el archivo Markdown a mano. Ambas producen lo mismo: un archivo en .claude/agents/.

Paso 1: Abre el gestor de agentes

Dentro de una sesión de Claude Code, escribe:

/agents

La interfaz lista tus agentes existentes y te deja crear uno nuevo, elegir un alcance, elegir un modelo y limitar herramientas mediante un menú. Si prefieres el control directo, puedes saltarte este paso y escribir el archivo tú misma: el resultado es idéntico.

Paso 2: Elige un alcance: proyecto o usuario

Hay dos lugares donde poner un archivo de agente, y elegir el correcto importa:

• Nivel de proyecto: .claude/agents/ dentro de la carpeta del proyecto. Aplica solo a este proyecto y puede subirse a Git para que todo el equipo lo comparta. Elige esto para agentes específicos del proyecto (por ejemplo, una revisora que entiende las convenciones de tu equipo).
• Nivel de usuario: ~/.claude/agents/ en tu directorio home. Aplica a todos tus proyectos. Elige esto para agentes que quieras tener a mano en todas partes (por ejemplo, una redactora de documentación general).

Cuando los nombres chocan, el agente de nivel de proyecto tiene prioridad sobre el de nivel de usuario.

Paso 3: Escribe el archivo del agente (un ejemplo real)

Crea el archivo .claude/agents/code-reviewer.md con el contenido de abajo. Arriba va el frontmatter YAML; el cuerpo es el system prompt del subagent:

---
name: code-reviewer
description: Review code for bugs, security, and maintainability. Use right after you write or change code.
tools: Read, Grep, Glob
model: sonnet
---

You are a senior-level code reviewer. Your job:
- Read the code that just changed (use Read/Grep/Glob, do NOT edit files).
- Find logic bugs, security holes, and hard-to-maintain spots.
- Rank findings by severity: critical / should-fix / suggestion.
- Return a short list with file paths and line numbers.
Do not run write commands, do not commit, do not change code.

Paso 4: Verifica

Ejecuta /agents otra vez para confirmar que code-reviewer aparece en la lista. Eso es todo: acabas de construir tu primer subagent. A partir de ahora, cada vez que acabes de cambiar código, Claude puede llamarlo automáticamente, o puedes llamarlo tú directamente: "usa el subagent code-reviewer para revisar lo que acabo de cambiar."

Los campos del frontmatter (name, description, tools, model)

El frontmatter decide cómo se comporta un subagent. Solo hay cuatro campos que recordar:

Dos consejos que valen su peso en oro: (1) Escribe una description clara, con verbos y situaciones ("Usa justo después de..."), porque es lo que Claude usa para llamar sola al agente correcto en el momento correcto. (2) Para un agente de solo lectura, limita las tools a Read, Grep, Glob: así el subagent queda físicamente incapaz de, por un descuido, editar o borrar un archivo.

Llamar y gestionar subagents

Hay tres formas de activar un subagent:

1. Autodelegación: Claude elige el subagent correcto según el campo description. Tú solo trabajas como siempre y, cuando el contexto encaja (por ejemplo, justo después de terminar de editar código), Claude le pasa el relevo a code-reviewer por su cuenta.
2. Llamada directa: nombra el agente en tu petición: "usa el subagent code-reviewer para revisar el módulo de pagos." Es la vía más segura cuando sabes exactamente qué necesitas.
3. Gestiona con /agents: abre la interfaz para listar, editar o borrar agentes; cambia modelos, añade o quita herramientas sin abrir archivos a mano.

Si un subagent "nunca se llama" aunque creas que debería, el culpable es casi siempre una description demasiado vaga. Reescribirla para que sea específica lo arregla.

Correr en paralelo y orquestar varios subagents

Aquí es donde los subagents brillan de verdad, y es la parte que la mayoría de las guías se salta. Como cada subagent corre en su propio contexto, el agente principal puede desplegar varios subagents a la vez sobre la misma base de código.

Ejemplo: tres subagents en paralelo

Digamos que acabas de terminar una funcionalidad y quieres una revisión completa antes de abrir un PR. En lugar de hacerlo de forma secuencial, pide:

Run 3 subagents in parallel on the current branch:
- test-runner: run the full test suite, report which tests fail
- security-scanner: scan the code that just changed for vulnerabilities
- style-checker: check lint and conventions
Combine all three into a single report.

Los tres agentes corren de forma independiente, cada uno leyendo lo que necesita, y luego el agente principal fusiona los tres informes ajustados. Ahorras tiempo y contexto.

Del lado de los tokens, entiende bien el mecanismo antes de esperar "un X por ciento de ahorro". Lo que ahorras no es el total de tokens: correr tres agentes sigue costando tokens por los tres. Lo que ahorras son los tokens de la sesión principal: cada log de test, cada rastro de scan de seguridad y cada aviso de lint se queda dentro del contexto de cada subagent, y solo vuelven unas pocas líneas de conclusión. Eso es lo que evita que la sesión principal se llene pronto y te deja mantener un hilo de pensamiento más largo. Ese es el beneficio real, no un porcentaje fijo.

Orquestación en varias capas

Un nivel más arriba: la salida de un subagent se convierte en la entrada del siguiente. Un flujo típico de explore -> plan -> implement:

1) subagent "explorer": survey the codebase, return a module map + spots to change.
2) Feed that result to subagent "planner": lay out a step-by-step plan.
3) Feed the plan to subagent "implementer": execute it step by step.

Es un patrón de orquestación potente, pero tienes que entender una limitación importante que lo sostiene por debajo.

La limitación que debes conocer

Los subagents no comparten contexto directamente entre sí y no "hablan" de igual a igual. Solo devuelven resultados al agente principal, y es el agente principal quien reenvía la información al siguiente subagent. Cada lanzamiento es una ida y vuelta de tokens. Así que la orquestación en varias capas tiene poder real, pero también un costo: no abuses de ella. Para entender exactamente en qué se diferencian los subagents de Skills/Hooks/MCP, lee la guía que compara Skills, Subagents, Hooks y MCP.

Algunas plantillas de subagent para usar ya mismo

Cuatro plantillas de copiar y pegar, ajusta un poco y adelante:

1. Revisor de solo lectura (absolutamente seguro)

---
name: safe-reviewer
description: Read-only code review that never edits files. Use to inspect before a merge.
tools: Read, Grep, Glob
model: sonnet
---
You only read and comment. Never run write commands. Return findings ranked by severity.

2. Test-runner

---
name: test-runner
description: Run the test suite and summarize failures. Use after editing code.
tools: Bash, Read, Grep
model: haiku
---
Run the project's tests, read the output, list failing tests with a short cause each.

3. Doc-writer

---
name: doc-writer
description: Write/update documentation and docstrings for new code.
tools: Read, Grep, Glob, Edit
model: sonnet
---
Read the code, write clear docs that match the repo's style. Do not change code logic.

4. Explorer

---
name: explorer
description: Survey an unfamiliar codebase, return an architecture map and entry points.
tools: Read, Grep, Glob
model: sonnet
---
Map out the modules, data flow, and the important files. Read only, never edit.

Fíjate en las cuatro plantillas: a todo agente que no necesita escribir no se le concede permiso de escritura. Ese es un hábito seguro que vale la pena mantener.

¿En qué se diferencian los subagents de Skills, Hooks y MCP?

Estos cuatro bloques de construcción se confunden mucho. Una forma rápida de distinguirlos:

En resumen: los subagents reparten el trabajo, los Skills enseñan un procedimiento, los Hooks automatizan eventos y el MCP amplía conexiones. La comparación completa de los cuatro bloques de construcción profundiza más si todavía dudas cuál usar.

Errores comunes y limitaciones reales

Pocos blogs se molestan en escribir esta sección, pero es justo la que te ayuda a usar subagents correctamente:

• Delegar de más. Dividir una tarea diminuta (renombrar una variable, arreglar una línea) en un subagent es contraproducente: la ida y vuelta de tokens y la latencia cuestan más que hacerlo tú misma. Los subagents son para trabajo "de contexto pesado y resultado ligero".
• Una description vaga significa que no hay llamada automática. Si la descripción es genérica, Claude no sabe cuándo delegar. Escribe la situación específica de uso.
• Olvidar limitar las tools. Una revisora que solo debería leer, pero que recibió acceso de escritura, puede editar el archivo equivocado. Concede siempre los permisos mínimos.
• Quemar tokens desplegando demasiados agentes. Correr 5-6 agentes en paralelo suena impresionante, pero cada uno es su propia sesión facturable. Despliega con intención.
• Cuándo NO dividir: cuando una tarea necesita el contexto completo de la conversación actual (por ejemplo, estás depurando un flujo largo en el que cada detalle previo importa). Un subagent no ve el contexto principal, así que separarla pierde justo el contexto que necesitas.

Sáltate la escritura: los 45 agentes prediseñados de AgentKit

Escribir un buen subagent cuesta esfuerzo, ajustando el prompt y probando una y otra vez. Si prefieres tener una biblioteca lista de agentes especializados en lugar de escribir desde cero, los 45 agentes prediseñados de AgentKit son un atajo opcional. Es un kit para Claude Code (no el AgentKit de OpenAI, solo una coincidencia de nombre), que incluye 45 agentes = 17 de Ingeniería + 28 de Marketing junto con más de 108 skills. Si quieres explorar el catálogo de agentes antes de decidir, lee la visión general de los 45 agentes prediseñados de AgentKit. El Engineer Kit cuesta 99 USD (el sitio no menciona un cargo recurrente). Dicho esto, escribir unos cuantos agentes que encajen con las convenciones de tu propio repositorio sigue siendo una habilidad fundamental que vale la pena aprender: el kit solo te ayuda a avanzar más rápido.

Preguntas frecuentes (FAQ)

¿Los subagents cuestan dinero extra?

Sí, indirectamente. Cada subagent es una sesión con su propio contexto, así que gasta sus propios tokens; correr varios en paralelo usa más tokens que una sola sesión. A cambio, como el contexto principal se mantiene más ligero, la ejecución en conjunto puede seguir siendo eficiente para trabajo de contexto pesado.

¿Cuántos subagents pueden correr en paralelo?

Puedes desplegar varios subagents a la vez, pero deberías limitarlo a la necesidad real (3-4 suele ser razonable para una tarea de revisión). Cuanto más despliegas, más tokens quemas y más difícil es seguirles el rastro.

¿Un subagent recuerda la conversación principal?

No. Cada subagent corre en una ventana de contexto aislada y no ve el historial de la sesión principal, salvo lo que el agente principal le pasa a propósito. Esa es su fortaleza (un contexto limpio), pero también una limitación a tener en cuenta.

¿En qué se diferencian los subagents de los Skills?

Los subagents son sub-IA especializadas a las que se les asigna trabajo y corren de forma independiente; los Skills son instrucciones/procedimientos empaquetados que se cargan para que Claude los siga. Uno "hace el trabajo por ti", el otro "enseña cómo hacerlo".

¿Debo poner un agente a nivel de proyecto o de usuario?

Ponlo a nivel de proyecto (.claude/agents/) para agentes específicos de un proyecto que quieras subir para el equipo; ponlo a nivel de usuario (~/.claude/agents/) para agentes que quieras en todos los proyectos. Cuando los nombres chocan, gana el de nivel de proyecto.

¿Necesito Claude Code Pro?

Los subagents son una función de Claude Code; los usas dentro del plan que ya tengas. Para detalles de planes (Pro a 20 USD/mes, Max, etc.), mira qué es Claude Code.

Conclusión y próximos pasos

Los subagents convierten Claude Code de asistente en solitario en un pequeño equipo: reparten el trabajo, corren en paralelo, mantienen el contexto limpio. Empieza simple con un code-reviewer de solo lectura y luego amplía hacia la orquestación en cuanto captes tanto su poder como sus límites. Lee a continuación qué son los Skills de Claude Code para combinar subagents con skills, o la comparación de los cuatro bloques de construcción para elegir la herramienta correcta. Y si prefieres no escribir desde cero, prueba el bundle de AgentKit — ahora 149 USD (antes 198 USD) con su biblioteca de agentes prediseñados.