Subagentes de Claude Code: una guía práctica (2026)

Un subagente es un segundo Claude, lanzado por tu sesión principal de Claude Code, que ejecuta una tarea en su propia ventana de contexto y devuelve un resultado. No comparte tu historial de conversación. No ve los archivos que ya has leído ni las decisiones que ya has tomado. Recibe un prompt, hace el trabajo, y devuelve.

Ese aislamiento es la funcionalidad entera. El paralelismo, la especialización, las restricciones de herramientas personalizadas, todo eso viene de un solo hecho: un subagente quema su propia ventana de contexto y solo la respuesta final vuelve a la tuya.

Corremos docenas de subagentes al día construyendo SkillProof, sobre todo para investigación en abanico y arreglos independientes a través de los archivos de datos del catálogo. Parte de lo que hemos aprendido es genuinamente útil. Parte lo aprendimos viendo a un agente reclamar una victoria sobre un trabajo que nunca hizo. Los dos tipos están en esta guía.

Qué es en realidad un subagente

En Claude Code, la sesión principal es un bucle: lee, piensa, actúa, observa, repite, con cada paso añadido a una conversación que crece. Un subagente es una instancia separada de ese mismo bucle, iniciada a mitad de sesión, con su propio historial que empieza vacío salvo por el prompt que le das.

Cuando el subagente termina, nada de su trabajo intermedio viaja de vuelta. Ni los archivos que leyó, ni los comandos que ejecutó, ni los callejones sin salida que exploró. Solo el texto que elige devolver llega a tu contexto principal. Si leyó 40 archivos para responder tu pregunta, tu sesión principal no paga por ninguna de esas 40 lecturas. Paga por un resumen.

Por eso se describe a los subagentes como una forma de preservar contexto: no porque el trabajo sea gratis (cuesta los mismos tokens en algún sitio), sino porque el coste queda en cuarentena en una ventana que se descarta, no una que sigues arrastrando por el resto de la sesión.

La contrapartida se sigue directamente. Un subagente que no sabe lo que ya intentaste puede repetir tus propios callejones sin salida, y no puede hacer una pregunta aclaratoria a mitad de tarea de la forma en que puede el bucle principal, o tiene suficiente en el prompt para avanzar o adivina. Delegar compra aislamiento y cuesta memoria compartida. Todo buen prompt de subagente lo escribe alguien que ha interiorizado ese trato.

Por qué el aislamiento de contexto es el punto

Imagina una sesión principal dos horas dentro de un refactor: cuarenta archivos leídos, una docena de llamadas a herramientas, una decisión de diseño revisada dos veces. Ese historial está haciendo trabajo real, es lo que hace coherente la próxima edición, pero también son cincuenta mil tokens de lastre.

Ahora necesitas saber cómo maneja los reintentos un subsistema que no tiene relación. Leer esos archivos en el bucle principal y cada uno se vuelve equipaje permanente, viajando en el contexto durante el resto de la sesión lo uses de nuevo o no, hasta que es parte de por qué el modelo empieza a perder el hilo del refactor real. Un subagente te deja hacer la pregunta, obtener la respuesta, y alejarte de la lectura. Los cuarenta archivos que leyó nunca entran en tu ventana. Recibes un párrafo de vuelta.

Ese es el mecanismo detrás de cada victoria legítima de subagente en esta guía: investigación, arreglos paralelos, exploración ruidosa. Todas son en realidad el mismo movimiento: haz la lectura cara en algún sitio desechable, mantén limpio el hilo principal.

Cuándo los subagentes ganan al bucle principal

Investigación a través de muchos archivos. "Cómo fluye la autenticación por esta base de código" toca rutas, middleware, almacenamiento de sesión y tres archivos de configuración. Responderlo en el bucle principal significa que todo eso llega a tu contexto de forma permanente. Un subagente lee los mismos archivos, devuelve una síntesis, y el material en crudo desaparece con él.

Tareas paralelas independientes. Cinco componentes necesitan la misma prop renombrada. Ninguno depende del otro. Cinco subagentes corriendo a la vez terminan en aproximadamente el tiempo que tarda uno, sin estado compartido que coordinar entre los cambios.

Exploración ruidosa. Buscar por grep un patrón en un repo grande, probar tres estrategias de búsqueda antes de que una acierte, leer archivos que resultan irrelevantes. Esto es exactamente el trabajo que quieres en cuarentena. Un subagente puede dar tumbos un rato y solo la parte útil vuelve.

Aislar una persona especializada. Un subagente revisor de código que solo revisa siempre, con un conjunto de herramientas más estrecho y un prompt ajustado para el escepticismo, se comporta de forma más consistente que pedirle a tu agente principal que cambie de contexto a "ahora sé crítico con tu propio trabajo" a mitad de sesión.

Cuándo los subagentes son peores

Bucles iterativos ajustados. Depurar un test que falla cambiando una línea, volviendo a ejecutar, leyendo el nuevo error, cambiando otra línea, necesita el historial completo de lo que ya intentaste. Entregarle eso a un subagente fresco en cada iteración significa volver a explicar toda la investigación cada vez, más lento y peor que quedarte en el bucle principal. Este es el terreno que cubren nuestras notas de depuración sistemática: depurar quiere continuidad, no delegación.

Tareas que necesitan la conversación completa. Si el usuario pasó diez mensajes afinando exactamente qué significa "limpia esta API", un subagente que solo ve la instrucción final la limpiará según su propia suposición de "limpia", no la que negociaron. Cualquier cosa donde los requisitos vivan en la conversación en vez de en un prompt que puedas reformular es mal encaje.

Ediciones simples de un solo archivo. Delegar "renombra esta variable en este archivo" a un subagente añade un viaje de ida y vuelta, una carga de contexto fresco, y un resultado que igual tienes que leer y confiar, por un trabajo que habría tomado quince segundos directamente. Lanzar un trabajador aislado solo compensa cuando el trabajo del que te protege es genuinamente grande.

El patrón en los tres: los subagentes son peores exactamente cuando el valor del contexto compartido supera el coste de cargarlo. El aislamiento deja de ser una funcionalidad en el momento en que la continuidad es lo que la tarea necesitaba.

Definiciones de agente personalizadas

Claude Code carga subagentes personalizados desde archivos markdown bajo .claude/agents/ (a nivel de proyecto, compartido a través de git) o ~/.claude/agents/ (personal, en cada proyecto). Cada archivo es un agente: frontmatter más un prompt de sistema, la misma forma que una skill pero describiendo una persona en vez de un procedimiento.

Aquí va un ejemplo completo y anotado, un revisor de código acotado a trabajo de revisión de solo lectura:

---
name: code-reviewer
description: Reviews a diff or pull request for correctness bugs,
  security issues, and missed edge cases. Use after a change is
  written and before it's committed, not while still drafting.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior engineer doing a pre-commit review. You did not
write this code and you have no attachment to it.

When given a diff or a set of changed files:

1. Read every changed file in full, not just the diff hunks.
   Bugs hide in the context around a change as often as in the
   change itself.
2. Check for: unhandled errors, off-by-one boundaries, null or
   undefined paths the type system doesn't catch, and any
   secret or credential that shouldn't be committed.
3. Do not comment on style or formatting unless it hides a bug.
   A linter's job is not your job.
4. For each finding, cite the file and line, and say what
   breaks and how you'd confirm it. If you're not sure something
   is a bug, say so explicitly instead of stating it as fact.
5. If you find nothing, say that plainly. Do not invent minor
   issues to look thorough.

Never run commands that modify files. You are reviewing, not fixing.

Algunas cosas importan aquí. El name es cómo lo invocas (Usa el agente code-reviewer para revisar este diff) o cómo Claude Code lo invoca automáticamente en una tarea que coincide. El campo description lleva el mismo peso que en una skill: condiciones de activación específicas ganan a un resumen vago.

tools es un límite de seguridad genuino, no una sugerencia. Listar solo Read, Grep, Glob, Bash significa que este agente físicamente no puede llamar a Edit ni a Write, aunque su propio razonamiento decida que un arreglo era obvio. Eso es deliberado: un agente de revisión que también puede parchear el código que está revisando es uno en el que no puedes confiar para que solo revise. model te deja enrutar un agente mecánico y bien especificado a un modelo más barato que tu sesión principal, ya que la tarea no necesita todo el peso de tu modelo principal.

El cuerpo es el mismo oficio que una skill: las restricciones negativas ("no comentes sobre estilo", "no inventes problemas menores") hacen más trabajo que las positivas, porque son las que impiden que un revisor rellene su output para parecer minucioso.

Patrones paralelos que realmente funcionan

Lecturas en abanico. Lanza varios subagentes a la vez, cada uno asignado a una parte distinta de la misma pregunta: uno lee el módulo de autenticación, otro la capa de datos, otro la suite de tests. Cada uno devuelve una síntesis corta. Obtienes tres respuestas en el tiempo que tomaría un pase secuencial, y el contenido en crudo de los archivos nunca toca tu contexto principal.

N arreglos independientes. Un lote de componentes necesita el mismo cambio mecánico idéntico, y ninguno importa del otro. Lanza un subagente por componente, cada uno con un prompt autocontenido: el cambio exacto, el archivo exacto, el chequeo de aceptación exacto. Este es el caso paralelo más limpio, ningún subagente necesita saber qué hizo otro.

Ambos patrones comparten un requisito que es fácil saltarse y caro cuando lo haces: cada prompt tiene que ser autocontenido. No tiene tu conversación. Si la tarea depende de una decisión tomada tres mensajes atrás, esa decisión tiene que reformularse en el prompt, o el subagente hará con confianza lo incorrecto.

Modos de fallo que realmente hemos encontrado

Esta es la parte que la mayoría de guías se saltan, escritas por alguien que corrió un subagente dos veces y funcionó. Nosotros los corremos a diario, y esto es lo que se rompe en la práctica.

Agentes que informan "hecho" sin haber hecho el trabajo. Un subagente vuelve con un resumen limpio y confiado: "Actualicé los tres archivos, los tests pasan, listo para hacer commit." Compruebas, y un archivo está intacto. Esto no es el modelo siendo deshonesto en ningún sentido deliberado, es que el resumen devuelto se aleja de lo que realmente pasó, sobre todo en tareas más largas donde el propio relato del agente de su trabajo se comprime. El arreglo es aburrido e innegociable: verifica por artefacto, no por informe. Lee el diff tú mismo. Ejecuta el test tú mismo. El resumen de un subagente es una afirmación, no un recibo.

Agentes que esperan notificaciones fantasma. Hemos tenido subagentes que se pausan a mitad de tarea esperando una devolución de llamada o una señal de otro proceso que nunca iba a llegar, porque el mecanismo de coordinación existía solo en la imaginación del prompt, no en nada realmente conectado. El arreglo es no diseñar nunca un prompt de subagente en torno a un evento que no has verificado que se dispare. Si el siguiente paso de un subagente depende del output de otro agente, entrégale ese output directamente cuando lo lances, no le pidas que detecte una señal de finalización que no has construido.

Ambos fallos se remontan a la misma disciplina: un prompt que no se apoya en contexto compartido o en una notificación asumida es uno que un agente puede completar correctamente de verdad, y un resultado que compruebas leyendo el archivo, no leyendo el relato del agente sobre el archivo, es la única forma de saber que lo hizo. Nada de esto es un argumento en contra de los subagentes. Es un argumento en contra de confiar en un resumen de texto de la forma en que confiarías en un diff. Los corremos constantemente. Simplemente no fusionamos nada solo por su palabra.

Las skills funcionan dentro de subagentes también

Un subagente sigue siendo una instancia de Claude, así que carga skills de la misma forma que tu sesión principal: comparando su tarea con las descripciones de skills instaladas y trayendo el cuerpo al activarse. Un subagente revisor de código con nuestra skill de checklist de revisión de código instalada recibe el mismo pase estructurado que tendría en el bucle principal, acotado al diff que le hayas dado.

Esto compone limpiamente. El subagente maneja dónde ocurre el trabajo, la skill maneja cómo se hace. Ninguno necesita saber del otro; se apilan automáticamente mientras ambos estén instalados donde el subagente pueda verlos, skills de proyecto en .claude/skills/, skills personales en ~/.claude/skills/. Nuestra página de mejores skills de programación clasifica las que vale la pena instalar antes de montar un agente de revisión o de investigación.

Subagentes vs hooks vs skills

Tres mecanismos distintos, tres trabajos distintos, y se confunden constantemente:

	Qué hace	Se dispara en	Corre donde
Skill	Enseña a Claude un procedimiento o estilo	Claude comparando tu petición con una descripción	Dentro del contexto actual
Hook	Ejecuta un comando de shell fijo automáticamente	Un evento del ciclo de vida (antes de una llamada a herramienta, después de una respuesta, inicio de sesión)	Fuera del modelo, determinista
Subagente	Delega una tarea a una instancia aislada de Claude	Una llamada explícita, tuya o del agente principal	Una ventana de contexto separada

Una skill cambia cómo Claude aborda algo que ya va a hacer. Un hook impone algo cada vez, incondicionalmente, sin pedirle al modelo que lo recuerde: ejecuta tests después de cada edición, bloquea un commit si se detectan secretos. Un subagente cambia dónde ocurre el trabajo, moviéndolo a una ventana desechable en vez de la tuya principal. Cubrimos los hooks a fondo, incluyendo el mismo tipo de cicatrices que arriba, en nuestra guía de hooks de Claude Code.

Se apilan. La configuración de un equipo podría usar un hook para hacer lint después de cada escritura, una skill para enseñar el estilo de código de la casa, y un subagente para ejecutar el pase de revisión completo antes de fusionar, tres capas, ninguna redundante. Si todavía estás montando el resto de tu configuración, nuestra guía de configuración 2026 recorre dónde va cada pieza, y nuestra guía de coste en tokens cubre lo que cuestan los tres en reposo.

Preguntas frecuentes

¿Los subagentes comparten el contexto de mi sesión principal?

No, y ese es todo el punto. Un subagente arranca con un historial vacío salvo por el prompt que le des. Nada de tu conversación principal se traslada automáticamente, y nada de lo que el subagente lea o haga vuelve salvo el texto final que devuelve. Si necesita antecedentes de tu conversación, pon esos antecedentes en el prompt.

¿Los subagentes pueden correr en paralelo?

Sí. Lanzar varios a la vez es el patrón estándar para investigación en abanico y para arreglos independientes que no se solapan. Cada uno tiene su propia ventana de contexto, así que no interfieren entre sí, pero tampoco pueden coordinarse a mitad de tarea a menos que hayas alimentado explícitamente el output de uno en el prompt de otro.

¿Cómo sé si un subagente realmente hizo lo que afirmó?

Comprueba el artefacto, no el resumen. Lee el diff, ejecuta el test, abre el archivo. Hemos tenido subagentes que reportan éxito limpio en un trabajo que estaba parcialmente deshecho, no por deshonestidad sino porque un resumen es una reconstrucción, y las reconstrucciones se desvían. Trata cada informe de subagente como una afirmación a verificar.

¿Dónde viven las definiciones de agente personalizadas?

.claude/agents/*.md para agentes a nivel de proyecto que viajan con el repo a través de git, y ~/.claude/agents/*.md para los personales disponibles en cada proyecto. Cada archivo necesita name y description en su frontmatter como mínimo; tools y model son opcionales pero vale la pena configurarlos deliberadamente en vez de dejarlos en sus valores por defecto.

¿Debería restringir qué herramientas puede usar un subagente?

Sí, siempre que el agente tenga un trabajo estrecho. Un agente de revisión que no puede llamar a Edit no puede parchear accidentalmente lo que se supone que está criticando. Un agente de investigación de solo lectura que no puede llamar a Bash no puede ejecutar algo destructivo por error mientras curiosea. El campo tools en el frontmatter de un agente es el mecanismo, y configurarlo es más barato que depurar lo que un agente sobrepoderoso hizo con el tiempo que le quedaba.