Subagentes en Claude Code: qué son y cómo crear los tuyos

Cuando le pides a Claude Code que busque algo en todo un proyecto o que corra la suite de pruebas, el resultado puede inundar tu conversación con resultados de búsqueda, logs o contenido de archivos que no vas a volver a mirar. Un subagente evita eso: hace ese trabajo en su propio contexto y solo devuelve el resumen.

Los subagentes son asistentes de IA especializados en un tipo de tarea. Cada uno corre en su propia ventana de contexto, con su propio system prompt, acceso a herramientas específicas y permisos independientes. Ojo con un detalle: cada subagente hace sus propias peticiones, que cuentan para los mismos límites de uso que tu conversación principal.

Si todavía no usas Claude Code, empieza por la guía de inicio.

Para qué sirven

Según la documentación oficial, los subagentes te ayudan a:

• Preservar contexto: mantienen la exploración y la implementación fuera de tu conversación principal.
• Imponer restricciones: limitas qué herramientas puede usar cada uno.
• Reutilizar configuraciones entre proyectos, con subagentes a nivel de usuario.
• Especializar el comportamiento con instrucciones enfocadas en un dominio.
• Controlar costos enviando tareas a modelos más rápidos y baratos, como Haiku.

Claude decide cuándo delegar a partir de la description de cada subagente, así que conviene escribirla con cuidado.

Los que ya vienen incluidos

Claude Code trae subagentes integrados que usa automáticamente cuando corresponde:

Explore y Plan omiten tus archivos CLAUDE.md y la instantánea de git status para que la investigación sea rápida y barata. Cuando Claude invoca a Explore, indica un nivel de profundidad: quick para búsquedas puntuales, medium para una exploración equilibrada y very thorough para un análisis exhaustivo.

También hay ayudantes para casos específicos, como statusline-setup (cuando ejecutas /statusline) y claude-code-guide (cuando preguntas por funciones de Claude Code).

Crea tu primer subagente

Un subagente es un archivo Markdown con frontmatter YAML. Puedes escribirlo tú o pedirle a Claude que lo cree. Este es el ejemplo de la documentación; dentro de Claude Code escribe:

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

Claude escribe el archivo con name, description, tools, model y el prompt. Abre ~/.claude/agents/code-improver.md y verifica que el frontmatter coincide con lo que pediste. El resultado se ve así:

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Como vive en ~/.claude/agents/, está disponible en todos tus proyectos. Para probarlo:

Use the code-improver agent to suggest improvements in this project

En la conversación verás la delegación como una fila con el nombre del subagente y una descripción corta de la tarea, por ejemplo code-improver(Suggest code improvements).

Un detalle de la documentación: desde la versión v2.1.198, el comando /agents ya no abre el asistente interactivo de creación; ahora te recuerda que le pidas a Claude que lo cree o que edites .claude/agents/ directamente. Y si Claude no encuentra el subagente nuevo, reinicia Claude Code: eso solo pasa cuando ~/.claude/agents/ no existía al empezar la sesión.

Dónde se guardan

Cuando dos subagentes tienen el mismo nombre, Claude Code usa el de mayor prioridad:

Los subagentes de proyecto (.claude/agents/) son ideales para lo específico de un código; súbelos al repositorio para que tu equipo los use y los mejore. Los de usuario (~/.claude/agents/) son personales.

El frontmatter: los campos que importan

Solo name y description son obligatorios. Los nombres de campos con varias palabras usan camelCase (maxTurns, disallowedTools) y deben coincidir exactamente con la tabla: Claude Code ignora sin avisar un campo que no reconoce.

Hay más campos (memory, background, effort, color, entre otros); están en la documentación oficial.

Un aviso de seguridad de la documentación: los subagentes que vienen de un plugin no admiten los campos hooks, mcpServers ni permissionMode; se ignoran.

Cómo pedir que se use un subagente

Hay tres formas, de menos a más control:

1. Lenguaje natural: nombra al subagente en tu prompt y Claude decide si delega.

   Use the test-runner subagent to fix failing tests
   Have the code-reviewer subagent look at my recent changes

2. @-mención: garantiza que ese subagente corra para una tarea. Escribe @ y elígelo del listado:

   @"code-reviewer (agent)" look at the auth changes

3. Toda la sesión: con el flag --agent, el hilo principal adopta las restricciones de herramientas y el modelo de ese subagente:

   claude --agent code-reviewer

   Para que sea el predeterminado de un proyecto, agrega en .claude/settings.json:

   {
     "agent": "code-reviewer"
   }

Para animar a Claude a delegar de forma proactiva, la documentación sugiere incluir frases como “use proactively” en la description.

Primer plano o segundo plano

• Los subagentes en primer plano bloquean la conversación hasta terminar, y los avisos de permisos te llegan a ti.
• Los subagentes en segundo plano corren mientras sigues trabajando. Si necesitan un permiso, Claude Code muestra el aviso en tu sesión principal indicando qué subagente lo pide.

Puedes pasar una tarea a segundo plano con Ctrl+B. Las reglas exactas de cuándo se usa cada modo dependen de si el modo fork está activo y de tus variables de entorno; están descritas en la documentación.

Patrones que funcionan

Aislar operaciones con mucha salida. Pruebas, documentación o logs que consumen mucho contexto:

Use a subagent to run the test suite and report only the failing tests with their error messages

Investigación en paralelo. Investigaciones independientes entre sí:

Research the authentication, database, and API modules in parallel using separate subagents

Encadenar subagentes. Uno termina y Claude pasa el contexto relevante al siguiente:

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

La documentación advierte que muchos subagentes que devuelven resultados detallados pueden consumir bastante contexto, y que cada uno gasta sus propios tokens.

¿Subagente o conversación principal?

Usa la conversación principal cuando la tarea necesita ir y venir con frecuencia, cuando varias fases comparten mucho contexto (planear, implementar, probar), para un cambio rápido y puntual, o cuando la latencia importa (un subagente empieza de cero y puede tardar en reunir contexto).

Usa subagentes cuando la tarea produce salida larga que no necesitas, cuando quieres restringir herramientas o permisos, o cuando el trabajo es autocontenido y puede devolver un resumen. Y si lo que quieres es un procedimiento reutilizable que corra dentro de tu conversación, considera un skill.

Un ejemplo pensado para Shopify

Este es un ejemplo mío, no de la documentación: un subagente de solo lectura que revisa archivos Liquid de un tema. Adáptalo a tu proyecto.

Guárdalo en .claude/agents/liquid-reviewer.md:

---
name: liquid-reviewer
description: Revisa archivos Liquid de un tema de Shopify. Úsalo proactivamente después de modificar secciones o snippets.
tools: Read, Grep, Glob
model: inherit
---

Eres un revisor de temas de Shopify. Al ser invocado:
1. Identifica los archivos .liquid modificados.
2. Revisa claridad, nombres, código duplicado y accesibilidad del marcado.
3. Reporta los hallazgos ordenados por prioridad: críticos, advertencias y sugerencias.
No modifiques archivos.

Como solo tiene Read, Grep y Glob, no puede editar nada: es una revisión segura que le devuelve a tu conversación únicamente el resumen.

Consejos

• Diseña subagentes enfocados: cada uno debería destacar en una tarea concreta.
• Escribe descripciones que distingan a un solo subagente. Claude las usa para decidir a quién delegar. Además, si la suma de las descripciones de tus subagentes (sin contar los integrados) supera 15,000 tokens, Claude Code muestra una advertencia al iniciar.
• Limita las herramientas a lo necesario.
• Súbelos al repositorio para que tu equipo trabaje igual.

Conclusión

Un subagente es un archivo Markdown con instrucciones, herramientas y un modelo, que hace el trabajo pesado fuera de tu conversación y te devuelve solo lo importante. Empieza por uno de solo lectura para revisar código, y crece desde ahí.

Fuentes

• Create custom subagents (documentación oficial)