Subagentes de Claude Code: configuración, configuración y cuándo usarlos

La mayoría de las sesiones de Claude Code se vuelven lentas y desordenadas por la misma razón: cada búsqueda exploratoria con grep, cada volcado de registros y cada “déjame revisar un archivo más” permanece en la conversación principal para siempre.

Los subagentes existen para solucionar exactamente ese problema. Son uno de los primitivos de agente incorporados en Claude Code para manejar trabajo ruidoso y paralelizable; una forma de empujar el desorden a una ventana aislada y devolver solo el resumen que importa.

Un subagente no es un Claude más inteligente, y no es lo mismo que una Skill (Habilidad). Es un agente de razonamiento separado con su propia ventana de contexto, su propia lista de herramientas permitidas y sin memoria de tu conversación actual a menos que lo bifurques explícitamente. Entender esa distinción es la diferencia entre una configuración de subagentes que te ahorra presupuesto de contexto silenciosamente y una que solo añade latencia sin beneficio alguno.

Subagentes vs Skills vs MCP

Claude Code te ofrece tres puntos de extensión que resuelven problemas diferentes, y se confunden constantemente porque los tres pueden técnicamente “ayudar con una tarea”.

Una regla práctica útil: un gancho (hook) impone una restricción dura de manera determinista, una Skill le da al agente principal una capacidad en línea, y un subagente es para trabajo que deseas delegar y mantener completamente fuera del contexto principal. Si el trabajo de una Skill es orquestar una herramienta que aún no existe, eso suele ser señal de que necesitas un servidor MCP, no un subagente. Claude Code no está solo en esta estructura — el ecosistema de OpenCode tiene una idea comparable en sus agentes especializados, que dividen la planificación, investigación y revisión entre roles dedicados de manera similar.

Qué es realmente un subagente

Tres propiedades definen a un subagente de Claude Code, y las tres importan para cómo lo utilizas:

• Contexto aislado. Un subagente comienza con una ventana fresca. No ve el historial de tu conversación a menos que lo bifurques explícitamente, lo que mantiene su salida libre de contaminación por lo que discutiste hace tres turnos.
• Una lista de herramientas permitidas restringida. Los subagentes solo pueden usar un subconjunto de lo que la sesión principal ya tiene; no pueden concederse nuevas capacidades, y un subagente bien diseñado debería obtener solo las herramientas que su trabajo requiere (herramientas de solo lectura para un agente de investigación, por ejemplo).
• Sin visibilidad entre subagentes. Los subagentes no pueden ver el trabajo en progreso de otros. Si la tarea B realmente necesita la salida de la tarea A, esa es una dependencia secuencial, no algo que puedas paralelizar entre dos subagentes.

El desencadenante para recurrir a uno no es “esta tarea es difícil”. Es “esta tarea es ruidosa”; el tipo de trabajo que genera mucha salida intermedia (decenas de lecturas de archivos, un registro largo, un grep exploratorio en todo el repositorio) donde ninguno de ese material intermedio necesita sobrevivir a tu siguiente turno de conversación.

Cuándo usar un subagente (y cuándo no)

Buenas aplicaciones: exploración de la base de código antes de un gran cambio, ejecuciones automatizadas de pruebas donde solo te importa el paso/fallo y los resúmenes de fallos, revisiones de seguridad o estilo, y cualquier tarea de investigación de múltiples pasos cuya salida cruda de otro modo inundaría tu sesión principal.

Malas aplicaciones: búsquedas de dos segundos ("¿qué devuelve esta función"), cualquier cosa que requiera refinamiento continuo de ida y vuelta, y tareas dependientes que te tentan a “paralelizar” aunque la segunda necesite la respuesta de la primera. Usar un subagente para una búsqueda trivial solo añade la sobrecarga de iniciar una ventana de contexto fresca sin ningún beneficio real de aislamiento.

Midiendo el beneficio: matemáticas de contexto y costo

La propuesta de los subagentes es abstracta hasta que pones números en una tarea real. Toma una común: hacer grep en un servicio de ~500 archivos para cada lugar donde aún se lee una clave de configuración obsoleta, y luego informar las coincidencias exactas de archivo:línea.

Eso es aproximadamente una reducción de 15-20x en lo que tu sesión principal tiene que llevar para ese paso, que es el mecanismo real detrás de “los subagentes mantienen las sesiones más rápidas”; no es magia, es contexto que nunca se carga en primer lugar.

El lado del costo se componde de la misma manera. Usando los precios de la desglose de precios de Claude Code, ejecutar esa misma pasada de exploración en Opus ($5/MTok entrada, $25/MTok salida) cuesta aproximadamente $0.20-0.25 solo por los ~40K tokens de entrada. Enrutándolo a Haiku ($1/MTok entrada, $5/MTok salida) reduce eso a $0.04-0.05 — y el presupuesto de Opus de la sesión principal nunca es tocado por los tokens de exploración en absoluto, ya que solo ve el resumen de ~2K tokens.

Definiendo un subagente personalizado

Los subagentes personalizados existen como archivos Markdown con frontmatter YAML, ya sea con alcance de proyecto en .claude/agents/ (comprometido en el repositorio, compartido por todo el equipo) o con alcance de usuario en ~/.claude/agents/ (herramientas personales que llevas a cada proyecto).

---
name: code-reviewer
description: >
  Revisa los cambios preparados en espera (staged) en busca de errores, problemas de seguridad y violaciones de estilo
  antes de confirmar. Úsalo cuando el usuario pida revisar, auditar o verificar
  cambios antes de confirmar o abrir un PR.  
tools: Read, Grep, Glob
model: sonnet
skills:
  - security-checklist
---
Eres un revisor de código cuidadoso. Lee el diff en espera, marca problemas
concretos con referencias a archivo:línea y termina con un breve resumen de paso/fallo.
No modifiques ningún archivo.

El campo description es la línea más importante del archivo. Es lo que la lógica de enrutamiento de la sesión principal lee para decidir si este subagente se ajusta a la tarea actual. Escríbela como un anuncio de trabajo: nombra la condición de desencadenante explícitamente, no un vago “ayuda con código”. Las descripciones vagas se saltan o se aplican mal por el despacho automático.

El campo tools es tu frontera de aislamiento. Dale a un subagente de investigación Read, Grep y Glob y nada más; darle cada herramienta disponible derrota el propósito entero de ejecutarlo en un sandbox restringido. El campo opcional skills precarga el contenido completo de las Skills nombradas en el contexto de inicio del subagente; útil cuando un subagente necesita conocimiento del dominio sin gastar un turno descubriéndolo y cargándolo en medio de la tarea.

Enrutamiento de modelos: modelos baratos para trabajo pesado

Los subagentes también son donde el control de costos se vuelve real. Enruta la descubrimiento de archivos, escaneo de registros y otro trabajo barato de verificar a Haiku, y reserva Sonnet u Opus para los pasos intensivos en razonamiento: decisiones de arquitectura, depuración ambigua, cualquier cosa donde equivocarse sea costoso. Haiku es aproximadamente 15 veces más barato por token que Opus, y en el tipo de exploración ruidosa para la que están diseñados los subagentes, esa brecha se acumula rápido en una sesión de trabajo real.

El patrón Explorar, Planificar, Ejecutar

Para trabajos complejos y de múltiples pasos, el patrón que resiste en la práctica es Explorar, Planificar, Ejecutar; usando subagentes baratos para las partes que generan ruido, y manteniendo la puerta de revisión humana en el único lugar donde realmente importa.

El detalle clave que la gente invierte es dónde pertenece la puerta de revisión. La exploración es barata, así que deja que un subagente lea libremente sin pedir permiso primero. La planificación es analítica, así que deja que el agente diseñe el enfoque por sí mismo. Pero antes de que cualquier agente modifique archivos, quieres ver el plan y aprobarlo; eso es para lo que está el modo plan de Claude Code (permissionMode: plan), y es el mismo principio discutido en las mejores prácticas de vibe coding sobre revisar cada diff antes de que se aplique.

Errores comunes

Un puñado de errores aparecen repetidamente una vez que los equipos comienzan a escribir subagentes personalizados:

• Descripciones vagas. “Ayuda con código” nunca enrutará correctamente. Nombra la condición de desencadenante exacta.
• Acceso a herramientas demasiado amplio. Dar acceso de escritura y bash a un subagente de investigación de solo lectura elimina la garantía de aislamiento que hizo que valiera la pena crearlo en primer lugar.
• Paralelizando tareas dependientes. Si la tarea B necesita la salida terminada de la tarea A, ejecútalas secuencialmente; los subagentes no pueden coordinarse en medio de la tarea como puede un orquestador compartido. Para flujos de trabajo que realmente necesitan agentes hablando entre sí en medio de la tarea, ese es un problema de diferente naturaleza; ver patrones de orquestación multi-agente si estás construyendo un sistema de producción en lugar de un flujo de trabajo de un solo repositorio.
• Usando un subagente para trabajo trivial. “Formatea este JSON” o “ejecuta este único comando” no necesita una ventana de contexto fresca; hazlo directamente.

Ejemplo resuelto: un subagente de revisión de código de principio a fin

Digamos que quieres que cada commit no trivial sea revisado antes de aplicarse. Deja caer la definición de code-reviewer mostrada anteriormente en .claude/agents/code-reviewer.md, comprométela para que todo el equipo comparta el mismo revisor, e invoquela con una solicitud natural como “revisa mis cambios en espera antes de confirmar”. Claude Code coincide tu solicitud con la description del subagente, lo inicia con acceso solo a Read, Grep y Glob, y regresa con hallazgos referenciados por archivo:línea y un resumen de paso/fallo; ninguno del ruido archivo por archivo para llegar allí toca nunca tu sesión principal.

Cómo se ve eso en la transcripción principal, anotado:

Tú:  revisa mis cambios en espera antes de confirmar

Principal: [despacha subagente code-reviewer — 6 archivos leídos, 1 pasada de grep,
       cero de eso mostrado aquí]

Principal: hallazgos de code-reviewer:
      - auth/session.go:142 — el camino de renovación del token no maneja tokens
        de renovación expirados; cae en referencia nula
      - auth/session.go:203 — estilo: error envuelto sin %w
      PASO/FALLO: FALLO (1 problema bloqueante)

Se hicieron seis lecturas de archivos y una pasada de grep, y tu sesión principal pagó exactamente por cuatro líneas de eso. Esa brecha — todo lo que hizo el subagente versus el resumen de tres líneas que realmente ves — es toda la propuesta de valor en una sola transcripción.

Si tu equipo también usa andamiajes de Desarrollo Guiado por Especificaciones (Spec-Driven Development), un subagente de revisión encaja naturalmente en el paso de validación; ver GitHub Spec Kit vs Kiro vs Flujos de Trabajo SDD de Claude Code para ver cómo esa puerta de revisión se compara en configuraciones SDD portátiles e integradas en IDE.

¿Vale la pena configurar subagentes personalizados?

No al principio. El subagente de propósito general integrado ya cubre la mayoría de la exploración y delegación de investigación sin que escribas un solo archivo YAML, y una sola pasada de Explorar-Planificar-Ejecutar es suficiente para la mayoría del trabajo diario. Escribe un archivo personalizado .claude/agents/*.md solo una vez que hayas delegado la misma tarea a mano tres veces: un revisor de código, un triajista de ejecutor de pruebas, un agente de búsqueda de documentación para una biblioteca interna específica. Los equipos que escriben cinco subagentes en su primera semana suelen terminar con cinco campos description obsoletos que nadie actualiza cuando la condición de desencadenante real deriva, lo que rompe silenciosamente el enrutamiento automático meses después. Comienza con cero subagentes personalizados, añade uno a la vez, y solo cuando la repetición — no la utilidad teórica — lo exija.

Limitaciones conocidas

Unas pocas asperezas vale la pena conocerlas antes de construir alrededor de subagentes:

• Sin delegación recursiva. Un subagente no puede generar sus propios subagentes. Si una tarea realmente necesita una segunda capa de delegación, eso es señal de que quieres una forma de orquestación diferente; ver patrones de orquestación multi-agente para ver cómo se ve eso fuera de una sesión única de Claude Code.
• Sin memoria entre invocaciones. Cada despacho comienza desde cero, incluso si llamaste al mismo subagente hace cinco minutos en una tarea relacionada. No hay mecanismo integrado para que un subagente recuerde su última ejecución.
• El aislamiento es una lista de herramientas permitidas, no un sandbox. Un subagente con acceso Bash aún puede tocar el sistema de archivos y la red como cualquier otra llamada de herramienta. Restringir tools reduce el radio de explosión; no crea una frontera de seguridad dura.

Solución de problemas

El subagente nunca se activa. El problema casi siempre es la descripción. Reescríbela alrededor de la condición de desencadenante específica en lugar de una declaración de capacidad general, y verifica dos veces que el archivo viva en .claude/agents/ (proyecto) o ~/.claude/agents/ (personal) con la extensión correcta.

El subagente consume demasiado contexto de todos modos. Verifica la lista de tools permitidas; un conjunto de herramientas demasiado amplio invita a una exploración demasiado amplia. También verifica si la tarea debería haberse dividido en dos subagentes en lugar de uno haciendo todo.

Una skill listada no carga dentro del subagente. Claude Code salta una skill faltante o deshabilitada nombrada en el campo skills en lugar de fallar la ejecución, y registra una línea al respecto en la salida de depuración (/debug desde la sesión principal, luego reproduce el despacho); algo como skill "security-checklist" not found, skipping. Ejecuta /doctor después para confirmar que el resto de tu configuración está saludable.

Los resultados parecen inconsistentes entre ejecuciones. Esto a menudo es un problema de enrutamiento de modelo, no de diseño de subagente; el trabajo intensivo en razonamiento asignado a un modelo barato variará más. Muévelo a Sonnet u Opus y mantén Haiku para los pasos deterministas y de baja ambigüidad.

Los subagentes son una pieza de un conjunto de herramientas mucho más grande; si estás comparando Claude Code contra el resto del ecosistema de herramientas de desarrollo de IA antes de comprometerte con este flujo de trabajo, ese resumen es una buena siguiente parada.

Enlaces útiles

• Instalación y configuración de Claude Code para Ollama, llama.cpp, precios
• Claude Skills y SKILL.md para Desarrolladores
• GitHub Spec Kit vs Kiro vs Flujos de Trabajo SDD de Claude Code
• ¿Qué es Vibe Coding?
• Patrones de Orquestación Multi-Agente: Una Guía Práctica
• Análisis Profundo de Agentes Especializados Oh My Opencode
• Herramientas de Desarrollo de IA: La Guía Completa