Agentes de IA en Claude Code: la guía práctica para usar subagentes

Un subagente es una función a la que se delega una tarea: Claude le encarga un trabajo, lo ejecuta en una ventana independiente que usted no ve y entrega una respuesta depurada. Bien utilizado, es la herramienta más eficaz para que Claude Code conserve la coherencia durante una sesión de varias horas. Mal utilizado, solo consume tokens y añade latencia sin aportar nada. Esta guía explica ambos lados: cómo funciona exactamente, qué archivo lo define y la regla práctica para saber cuándo realmente vale la pena.

La versión en 20 segundos

Un subagente ejecuta una tarea secundaria y autónoma en un contexto aislado; al terminar, envía un resumen breve a la conversación principal. Esa es toda la idea. Su razón de ser es resolver un problema concreto: las sesiones largas con agentes acumulan ruido —resultados de grep, registros de compilación, archivos consultados una sola vez— hasta que el modelo dedica más atención a ordenar el desorden que a realizar el trabajo.

Al trasladar esa labor ruidosa a un subagente, todo ese material se queda fuera del hilo principal. La conversación solo recibe la conclusión. Por eso, el modelo mental correcto no es «un equipo de ingenieros de IA que colabora», sino higiene de contexto con un valor de retorno. Con esta idea clara, todas las demás decisiones sobre subagentes resultan más sencillas.

Qué son realmente los subagentes: agentes de IA aislados

Un subagente se ejecuta en su propia ventana de contexto, con un prompt de sistema personalizado, acceso específico a herramientas y permisos independientes. Cuando Claude detecta una tarea que coincide con la función declarada del subagente, la delega; el subagente trabaja por su cuenta y devuelve el resultado. Esa es la definición oficial, y las dos partes decisivas son su propia ventana de contexto y devuelve el resultado.

Aquí aparece el detalle que muchas explicaciones describen mal: un subagente comienza desde cero. No ve el historial de la conversación, los archivos que Claude ya leyó ni las skills que ya se invocaron. Claude redacta un mensaje breve de delegación que resume la tarea, y el subagente trabaja únicamente con su propio prompt de sistema y algunos datos básicos del entorno, como el directorio de trabajo; no recibe todo el prompt de sistema de Claude Code. Cuando termina, solo regresa su resumen.

Ese aislamiento tiene ventajas y costos; entender esa compensación es esencial:

• La ventaja: todo el proceso intermedio y extenso —los doce archivos consultados, la búsqueda fallida con grep, el registro revisado— nunca ocupa el contexto principal. Se obtiene la respuesta sin cargar con el desorden.
• El costo: el subagente debe volver a recopilar un contexto que ya estaba disponible. Si la tarea solo se entiende con el historial de la conversación, un subagente que parte de cero tendrá dificultades.

El archivo que define un subagente

Un subagente personalizado se define en un archivo Markdown con frontmatter YAML. El frontmatter contiene la configuración; el cuerpo en Markdown se convierte en el prompt de sistema del subagente. Solo hay dos campos obligatorios: name y description.

---
name: code-reviewer
description: Reviews code for quality and best practices. Use immediately after writing or modifying code.
tools: Read, Glob, Grep
model: sonnet
---

You are a senior code reviewer. When invoked, run git diff to see recent
changes, focus on modified files, and review for clarity, naming, error
handling, exposed secrets, input validation, and test coverage. Group your
feedback by priority: critical issues, warnings, then suggestions.

Eso basta para tener un subagente completamente funcional. description no es un adorno: Claude la lee para decidir cuándo delegar. Una descripción como «revisa el código; úsalo inmediatamente después de escribirlo o modificarlo» activa al subagente en el momento adecuado, mientras que un impreciso «asistente de código» puede dejarlo sin uso. Conviene redactarla como la oferta de trabajo de un especialista.

No es necesario escribir el archivo a mano. El comando /agents de Claude Code abre una interfaz con pestañas para administrar subagentes: Running muestra los que están activos o terminaron recientemente —y permite abrirlos o detenerlos—, mientras que Library sirve para crearlos, editarlos y organizarlos. Hay un detalle importante: los subagentes se cargan al iniciar la sesión. Si se modifica un archivo directamente en el disco, hay que reiniciar la sesión para aplicar el cambio. En cambio, los subagentes creados o editados desde la interfaz /agents entran en vigor de inmediato.

Dónde se guardan los subagentes y qué definición prevalece

El mismo archivo de subagente se comporta de forma distinta según su ubicación. Esa ubicación determina quién puede usarlo y qué definición prevalece cuando hay nombres duplicados.

Cuando dos subagentes tienen el mismo nombre, gana la ubicación de mayor prioridad: las definiciones administradas prevalecen sobre las del proyecto, y las del proyecto sobre las del usuario. Los subagentes del proyecto se descubren recorriendo los directorios superiores desde el directorio de trabajo y, desde la versión v2.1.178, en caso de conflicto prevalece la definición más cercana al directorio de trabajo. También existe una opción válida solo durante la sesión: se pueden pasar los subagentes como JSON mediante --agents al iniciar Claude Code. Así existen durante esa sesión sin guardarse en el disco, algo útil para scripts de automatización y pruebas rápidas.

La regla práctica es sencilla: un subagente que codifica la forma de revisar o probar este repositorio debe vivir en .claude/agents/ y formar parte del control de versiones, para que todo el equipo pueda usarlo. Si refleja una preferencia de trabajo personal, debe guardarse en ~/.claude/agents/ para acompañar al usuario entre proyectos.

Modelo y herramientas: los dos controles importantes

Dos campos del frontmatter concentran casi todo el valor práctico. Configurarlos bien es lo que convierte a los subagentes de una curiosidad interesante en una herramienta realmente rentable.

Modelo. El campo model acepta un alias (sonnet, opus, haiku, fable), un identificador completo como claude-opus-4-8 o inherit. Si se omite, el valor predeterminado es inherit: el subagente usa el mismo modelo que la conversación principal. Aquí se esconde una palanca de presupuesto. Un subagente cuya única misión sea «buscar con grep en el repositorio y resumir los hallazgos» no necesita un modelo de frontera. Con model: haiku, el trabajo mecánico se ejecuta en un modelo más rápido y económico, mientras la sesión principal conserva Opus para el razonamiento.

Herramientas. De forma predeterminada, un subagente hereda todas las herramientas internas y MCP disponibles en la conversación principal. Hay dos campos para limitar ese acceso: tools funciona como lista de permitidas —solo esas herramientas— y disallowedTools como lista de denegadas —todas salvo esas—. Un subagente de investigación que nunca deba modificar archivos puede recibir tools: Read, Grep, Glob, Bash; así, editar queda físicamente fuera de sus posibilidades. No se trata solo de orden. Es una barrera de seguridad real: un revisor de solo lectura no puede reescribir accidentalmente el archivo que está evaluando.

Hay otro control que conviene conocer: isolation: worktree ejecuta el subagente en un worktree temporal de git, es decir, en una copia aislada del repositorio que se elimina automáticamente si el subagente no hace cambios. Resulta útil cuando se quiere que pruebe algo arriesgado sin interferir con el árbol de trabajo actual.

Cuándo conviene usar un subagente y cuándo no

Esta es la sección que suelen omitir los repositorios de configuraciones en GitHub, aunque es la que realmente permite ahorrar tiempo y dinero. Un subagente tiene un costo, así que la pregunta nunca debería ser «¿podría usar uno aquí?», sino «¿el aislamiento compensa su costo?».

Estos son los casos en los que un subagente no es la herramienta adecuada, de acuerdo con el propio diseño de la función:

• Idas y vueltas continuas. Si la tarea exige ajustes frecuentes y sus decisiones durante el proceso, conviene mantenerla en la conversación principal. Delegarla interrumpe ese ciclo.
• Fases que comparten contexto. Un flujo de planificación, implementación y pruebas en el que cada fase depende de la anterior debe permanecer en un solo hilo, no repartirse entre tres subagentes aislados que empiezan a ciegas.
• Cambios rápidos y puntuales. Activar un subagente para corregir una errata cuesta más que hacer la corrección.
• Trabajo sensible a la latencia. Los subagentes parten de cero y necesitan tiempo para reunir contexto. Cuando se busca una respuesta inmediata, trabajar en el hilo principal es más rápido.

Subagente, skill, fork o equipo de agentes

Claude Code ofrece ahora cuatro maneras de estructurar el trabajo, y es fácil confundirlas. La diferencia está por completo en el contexto.

La distinción que más confusión provoca es skill frente a subagente, porque ambos pueden parecer «conocimiento guardado». Una skill contiene instrucciones reutilizables que se ejecutan dentro del contexto de la conversación principal, por lo que conoce todo lo que está ocurriendo. Un subagente hace lo contrario: está aislado por diseño y solo conoce la tarea que recibe. Para que Claude aplique un estilo propio mientras sigue trabajando en la misma conversación, corresponde usar una skill. Para que una investigación ruidosa ocurra fuera de la vista y luego entregue sus conclusiones, corresponde usar un subagente.

El fork ocupa el punto intermedio: hereda toda la conversación acumulada —el mismo prompt de sistema, las herramientas, el modelo y el historial de mensajes—, por lo que no hace falta volver a explicar nada. Aun así, sus llamadas a herramientas permanecen fuera del contexto principal y solo regresa el resultado final. Es la opción adecuada cuando un subagente con nombre necesitaría demasiados antecedentes para resultar útil. El modo fork está sujeto a la variable de entorno CLAUDE_CODE_FORK_SUBAGENT.

Las funciones avanzadas y sus límites

Dos capacidades recientes vuelven mucho más potentes a los subagentes, y cada una impone un límite que conviene respetar.

Anidamiento. Desde Claude Code v2.1.172, un subagente puede iniciar sus propios subagentes. Un revisor puede asignar un verificador a cada hallazgo y mantener oculto todo ese material intermedio; solo el resumen del subagente de nivel superior llega a la conversación principal. El límite es fijo: el anidamiento alcanza cinco niveles, no se puede configurar y un subagente situado en el quinto nivel no recibe la herramienta Agent, por lo que ya no puede iniciar otro. Ese techo tiene una razón. Una expansión profunda puede crear un enjambre por accidente y disparar el consumo de tokens; trate la profundidad como un presupuesto, no como una meta.

Memoria. Al añadir memory: project —o user, o local—, el subagente obtiene un directorio de memoria persistente que puede leer y modificar entre sesiones. Un revisor de código con memoria de proyecto va acumulando las convenciones y los problemas recurrentes, de modo que mejora cuanto más se utiliza. project es el valor predeterminado recomendado porque puede compartirse mediante el control de versiones. Cuando la memoria está habilitada, Claude Code inyecta al arrancar las primeras 200 líneas —o 25KB— del archivo MEMORY.md del subagente en su prompt de sistema, así que conviene mantenerlo bien depurado.

Un buen primer paso es crear un único subagente especializado —un code-reviewer de solo lectura es el ejemplo clásico—, guardarlo en .claude/agents/ e invocarlo después de cada cambio. Cuando demuestre su utilidad, se puede añadir un subagente de investigación con un modelo más económico. Los equipos que aprovechan bien esta función no ejecutan treinta agentes, sino tres que cumplen muy bien una tarea cada uno. Si la decisión pendiente es qué herramienta de programación adoptar, el tema es otro: está explicado en Codex vs Claude Code vs Cursor y en el análisis más amplio de los mejores agentes de IA para programar.

Si está integrando Claude Code en su forma real de entregar software, eso resume buena parte de lo que publico. Suscríbase al boletín para conocer configuraciones de trabajo, no solo la novedad del día del lanzamiento.