Subagentes de Claude Code: lo que aprendimos ejecutando 18 en producción

Subagentes de Claude Code: lo que aprendimos ejecutando 18 en producción

Dieciocho subagentes de Claude Code publican cada post de este sitio, incluido este. Seis corren en Opus, once en Sonnet, uno en Haiku. Solo el agente researcher ha acumulado 74 archivos de memoria desde que empezamos. Ninguno habla con los demás. Eso es lo que más nos sorprendió: un subagente nunca ve tu conversación, y tampoco ve la conversación de otro subagente. Así que todo el pipeline se construye alrededor de archivos en disco. Aquí está la flota, el reparto de modelos, la configuración de memoria y lo que se rompió por el camino.

La versión corta:

• Un subagente corre en su propia ventana de contexto, con su propio system prompt, herramientas y permisos.
• Ejecutamos 18 subagentes: 6 en Opus, 11 en Sonnet, 1 en Haiku.
• Los agentes se pasan el trabajo a través de archivos en disco, nunca compartiendo contexto.
• Desde v2.1.198 el asistente de creación de /agents desapareció. Escribe el archivo tú mismo.

¿Qué es un subagente de Claude Code?

Un subagente de Claude Code es un asistente especializado que corre en su propia ventana de contexto, con un system prompt propio, acceso concreto a herramientas y permisos independientes. Se encarga de una tarea paralela sin llenar tu conversación principal, y luego solo devuelve su resumen. Las definiciones viven como archivos Markdown con frontmatter YAML en .claude/agents/, documentadas en la referencia de subagentes de Anthropic.

Claude delega en uno automáticamente. Lee el campo description de cada subagente que tiene visible, y cuando una tarea encaja, le pasa el trabajo sin preguntarte antes. Desde v2.1.198 esos subagentes corren en segundo plano por defecto, así que la delegación suele pasar mientras tú sigues escribiendo. También puedes invocar uno por nombre cuando quieras un worker concreto para un trabajo concreto.

Claude Code viene con tres subagentes integrados: Explore para búsquedas de solo lectura en el código, Plan para planificar el trabajo, y general-purpose para todo lo demás.

Un detalle de nomenclatura que confunde a guías y archivos de configuración antiguos: la herramienta que lanza un subagente se llama Agent, no Task. Se renombró en v2.1.63, y la documentación confirma que las referencias Task(...) existentes siguen funcionando como alias. En este post usamos Agent.

El resto de este post no es una referencia. La documentación de Anthropic ya hace ese trabajo mejor de lo que podríamos hacerlo nosotros, con unas 8.000 palabras y anotaciones de versión hasta v2.1.212. Lo que sigue es cómo se ven dieciocho de estos agentes cuando corren cada día.

Nuestra flota de 18 agentes: cómo es una instalación real en disco

Nuestro directorio .claude/agents/ guarda 18 archivos de definición de subagentes, cada uno un Markdown con frontmatter YAML. Juntos ejecutan todo el pipeline de contenido de este sitio: investigación, brief, redacción, validación, traducción a nueve idiomas, generación de imágenes y publicación. Seis corren en Opus, once en Sonnet, uno en Haiku.

Todas las guías de subagentes en la primera página de Google usan el mismo ejemplo de code-reviewer copiado de la documentación. Así es como se ven dieciocho de ellos cuando de verdad entregan trabajo.

.claude/agents/
├── abc-link-checker.md
├── brief-creator.md
├── content-gap-finder.md
├── content-refresher.md
├── content-writer.md
├── image-handler.md
├── language-translator.md
├── payload-publisher.md
├── pipeline-manager.md
├── rank-checker.md
├── rescue-diagnoser.md
├── rescue-prioritizer.md
├── researcher.md
├── sanity-publisher.md
├── seo-auditor.md
├── sitemap-checker.md
├── translation-coordinator.md
└── validator.md

Se agrupan en cuatro funciones. La producción de contenido pasa de researcher a brief-creator, de ahí a content-writer y luego a validator. La distribución cubre translation-coordinator, language-translator, image-handler, payload-publisher y sanity-publisher. El mantenimiento corresponde a content-refresher, rank-checker, rescue-diagnoser, rescue-prioritizer, seo-auditor, sitemap-checker y abc-link-checker. La coordinación queda en manos de pipeline-manager y content-gap-finder.

Dos de esos archivos, copiados tal cual desde disco, resumen todo el argumento del coste:

# .claude/agents/researcher.md
name: researcher
tools: Read, Write, Glob, Grep, WebSearch, WebFetch, Bash
model: opus
memory: project
skills:
  - seo
  - competitor-analysis

# .claude/agents/sitemap-checker.md
name: sitemap-checker
tools: Read, Write, Edit, Glob, Grep, WebFetch
model: haiku

Mismo mecanismo, unas diez veces más coste por token. Uno es un agente Opus con acceso a la web y memoria persistente que decide qué debe argumentar un post. El otro es un agente Haiku que descarga un sitemap y escribe un archivo JSON. Nada en el formato de subagente te obliga a pagar tarifas de Opus por el segundo trabajo, y la mayoría de las flotas que hemos visto hacen justo eso por defecto.

El campo skills: de researcher precarga dos definiciones de skill en el system prompt de ese subagente al lanzarlo, y así es como conoce nuestras convenciones de SEO sin que se lo digamos en cada ejecución. Si todavía no has escrito una, ya cubrimos cómo escribir una Claude skill en otro post, y aquí no lo repetimos.

Si quieres un catálogo navegable de definiciones para copiar, la colección de la comunidad awesome-claude-code-subagents es la que la gente busca de verdad. Léela para ver formas, no para verificar que esté actualizada: algunas entradas son anteriores al cambio de nombre a Agent.

¿Cómo se crea un subagente? (El asistente de /agents desapareció)

Creas un subagente de Claude Code escribiendo tú mismo un archivo Markdown en .claude/agents/, o pidiéndole a Claude que lo escriba por ti. Desde v2.1.198 el comando /agents ya no abre el asistente interactivo de creación. Ejecutarlo ahora solo imprime un recordatorio que te señala el directorio.

1. Crea el archivo. .claude/agents/{name}.md para un subagente de proyecto que se versiona con git, o ~/.claude/agents/{name}.md para uno que te acompañe entre proyectos.
2. Escribe name y description. El campo description decide más que cualquier otra cosa en el archivo, porque es lo que Claude compara para elegir si delega. Escríbelo como una regla de enrutamiento, no como un título de puesto.
3. Define tools y model. tools es una lista de permitidos; si lo omites, el subagente hereda las herramientas de la conversación principal. model anula el modelo de tu sesión.
4. Escribe el system prompt como el cuerpo Markdown debajo del frontmatter. Los subagentes reciben solo este prompt más detalles básicos del entorno, no el system prompt completo de Claude Code.
5. Invócalo. De forma automática, dejando que la description haga match, o de forma explícita pidiéndolo por nombre.

---
name: changelog-writer
description: Writes release notes from merged pull requests. Use when the user asks for a changelog, release notes, or a summary of what shipped.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You write release notes. Read the merged PRs since the last tag with `git log`,
group them into Added / Changed / Fixed, and write one line per change in past
tense. Never invent a change that is not in the log. Return only the markdown.

Varias guías que todavía posicionan bien siguen diciendo que ejecutes /agents para abrir la interfaz de gestión. Esa instrucción ya no vale. Otro detalle que la documentación deja claro: el file watcher solo cubre los directorios que ya existían cuando arrancó la sesión, así que el primer archivo de agente en un directorio agents/ recién creado necesita un reinicio de Claude Code antes de cargar.

Subagente vs skill vs agent team vs fork: ¿cuál necesitas de verdad?

Elige un subagente cuando una tarea paralela llenaría tu conversación principal y solo necesitas el resumen de vuelta. Elige una skill cuando quieras enseñarle a Claude un procedimiento que corra dentro de tu contexto actual. Elige un agent team cuando los workers deban coordinarse entre sí. Elige un fork cuando la tarea paralela necesite tu historial de conversación.

Los subagentes te reportan a ti y nunca entre sí. Los agent teams se envían mensajes directamente entre ellos. Esa única diferencia decide qué primitiva necesitas.

Nuestra opción por defecto es el subagente, y nunca hemos necesitado un team. La coordinación en nuestro pipeline es secuencial, no conversacional, así que una lista de tareas compartida no aportaría nada y solo costaría tokens. Los teams además siguen siendo experimentales y están desactivados por defecto, lo cual es un límite duro para cualquier cosa que corramos sin supervisión. Las skills están en una capa completamente distinta: son instrucciones que se cargan en el contexto que ya esté corriendo, incluido el de un subagente, y por eso researcher declara dos en vez de delegar en ellas.

Selección de modelo: qué agentes van en Haiku, Sonnet y Opus

Define model en el frontmatter de un subagente como haiku, sonnet, opus, o un ID de modelo concreto, y ese subagente anula el modelo de tu sesión. Nuestro reparto real entre los 18 agentes es seis en Opus, once en Sonnet, uno en Haiku, asignado según cuánto criterio exige de verdad la salida de cada agente.

Tres reglas que le daríamos a cualquiera que tenga que repartir modelos en una flota. Pon un agente en Haiku cuando su salida es determinista y su entrada es pequeña: descargar, parsear, contar, reformatear. Pon un agente en Sonnet cuando la tarea es larga y está bien especificada, pero alguien ya decidió cómo se ve una respuesta "correcta", lo cual cubre la mayor parte del trabajo de ejecución, incluidos los nueve workers de traducción. Reserva Opus para los agentes cuya salida nadie más adelante va a cuestionar.

Esa última regla es la razón por la que validator está en Opus aunque produzca un informe corto. Nadie revisa al revisor.

Una nota de versión que cambia la cuenta: desde v2.1.198 el subagente integrado Explore ya no corre siempre en Haiku, hereda el modelo de la sesión. Un subagente de usuario o de proyecto llamado Explore anula al integrado y conserva su propio campo model, así que define uno con model: haiku si quieres mantener la exploración en un modelo barato.

Contratos de archivo: cómo nuestros agentes se pasan el trabajo sin compartir contexto

Un subagente no ve tu historial de conversación, y tampoco ve el de ningún otro subagente. Por eso los traspasos en memoria entre agentes son estructuralmente imposibles. La solución es convertir cada traspaso en un artefacto en disco, para que el siguiente agente lea un archivo en lugar de heredar un contexto que nunca podrá tener.

techsy.community/posts/claude-code-subagents/
├── research.md      # researcher       → SERP analysis, keyword data, gaps
├── brief.md         # brief-creator    → section-by-section spec
├── en.md            # content-writer   → the post you are reading
├── de.md            # language-translator (one subagent per language)
├── hero.webp        # image-handler
├── validation.md    # validator
└── meta.json        # pipeline stage, updated by a PostToolUse hook

Cinco artefactos, cada uno escrito por un agente distinto, cada uno leído por el siguiente, todos legibles por un humano y versionados en git. El pipeline sobrevive a los límites de contexto porque ningún agente necesita nunca el contexto de otro agente. Solo necesita el archivo del agente anterior.

El beneficio más claro se ve en la traducción. translation-coordinator lee en.md, y luego lanza un subagente language-translator por idioma, nueve o diez a la vez. En nuestro repo, la concurrencia depende de emitir todas las llamadas de lanzamiento en un solo mensaje: eso es un comportamiento observado en nuestra instalación, no algo que diga la documentación, pero ha sido lo bastante consistente como para que el coordinador esté escrito para hacerlo a propósito. Cada traductor escribe su propio {lang}.md y ninguno puede ver el trabajo de los demás, lo cual no es un problema, porque el contrato es el archivo, y el archivo ya está completo.

Aquí también es donde los subagentes se acaban y empieza otra cosa. Los subagentes trabajan dentro de una sola sesión. Si quieres espacios de trabajo genuinamente independientes con su propio historial, lo que necesitas es ejecutar varias sesiones de Claude Code, o recurrir a isolation: worktree para darle a un subagente su propia copia del repositorio.

¿Cómo recuerdan los subagentes cosas entre sesiones?

Solo si defines el campo memory, que admite tres ámbitos: user escribe en ~/.claude/agent-memory/<name>/, project escribe en .claude/agent-memory/<name>/, y local escribe en .claude/agent-memory-local/<name>/. Sin él, cada invocación arranca en blanco. Doce de nuestros dieciocho agentes declaran memory: project.

Después de unos cuarenta posts, esos directorios ya pesan. researcher guarda 74 archivos de memoria, validator 66, brief-creator 65. No son registros. Son decisiones acumuladas: qué patrones de H1 rindieron mal, qué afirmaciones sobre clientes no podemos hacer, qué formas de SERP premian una tabla en vez de prosa.

Aquí está la restricción que le da forma a todo esto. Un subagente con memoria habilitada recibe solo las primeras 200 líneas o 25 KB de MEMORY.md inyectadas en su system prompt, lo que llegue primero. Ese único límite es la razón por la que todos nuestros agentes mantienen un índice en vez de un diario.

# Researcher Memory

## Reusable post patterns
- [Challenger H1 pattern](feedback_challenger_h1_pattern.md): when a question-shaped H1 earns the click
- [Sponsored post research](feedback_sponsored_post_research.md): H1 must be category-shaped, never a review
- [Claude Skills tutorial](project_claude_skills_tutorial.md): docs own the top two slots, target the long tail

Una línea por entrada, con el detalle empujado al archivo de tema enlazado, que el agente lee bajo demanda con su herramienta Read. MEMORY.md se mantiene como un índice que cabe dentro del presupuesto de inyección, mientras el corpus detrás de él crece sin límite.

Usamos project en vez de user para casi todo, porque la memoria de proyecto vive en el repo y viaja con el control de versiones. Cuando un compañero de equipo hace pull, se lleva el criterio acumulado del agente junto con el código. local existe para los casos en los que quieres las notas, pero no el commit.

Qué se rompió: modos de fallo, nombres duplicados y un alias heredado en nuestro propio repo

Cuatro modos de fallo explican casi todo lo que nos ha pasado. Un subagente que se niega a lanzarse, un subagente que en silencio no es el que editaste, un subagente que Claude no encuentra en absoluto, y un tope duro de sesión sobre cuántos puedes lanzar. Los cuatro tienen soluciones cortas e inequívocas.

El del nombre duplicado es más traicionero de lo que parece. Editas un archivo, el comportamiento no cambia, y no hay ningún error por ninguna parte, porque otro archivo con el mismo name ganó el orden de lectura.

Los hooks ayudaron más de lo que esperábamos con los fallos que ni siquiera son errores, solo pasos que un humano se olvida de hacer. El nuestro es deliberadamente simple:

"SubagentStop": [
  {
    "matcher": "content-writer",
    "hooks": [
      {
        "type": "command",
        "command": "echo 'Content writer finished. Run /validate to check quality and SEO compliance.'"
      }
    ]
  }
]

Ahora la parte honesta. Mientras escribíamos este post, hicimos grep sobre nuestra propia flota y encontramos esto todavía metido en translation-coordinator.md:

# .claude/agents/translation-coordinator.md
name: translation-coordinator
tools: Read, Write, Glob, Grep, Task
model: sonnet

Task, no Agent. Ese campo lleva desactualizado desde v2.1.63 y nunca ha fallado ni una sola vez, porque Anthropic mantuvo el alias. Todavía no lo hemos limpiado. Si tus propios archivos de agente todavía dicen Task, no están rotos, solo están viejos, y el alias está haciendo un trabajo silencioso en un montón de repos ahora mismo.

Una corrección en la otra dirección: las guías escritas antes de v2.1.172 dicen que un subagente no puede lanzar subagentes. Sí puede, y lo hace desde esa versión. La profundidad está fija en cinco niveles por debajo de la conversación principal y no es configurable, así que un subagente en el nivel cinco simplemente no recibe la herramienta Agent.

Qué cuestan los subagentes, y cuándo no usar uno

Cada lanzamiento de subagente crea una ventana de contexto nueva, así que delegar nunca es gratis. El equipo de ingeniería de Anthropic reporta que los agentes usan aproximadamente 4 veces más tokens que las interacciones de chat, y los sistemas multiagente aproximadamente 15 veces más, y que solo el uso de tokens explica el 80 % de la varianza de rendimiento que midieron.

No tenemos mediciones propias de tokens que aportar, así que trata cualquier multiplicador concreto que leas sobre este tema, incluidas las cifras de 4x a 7x que circulan por otros blogs, como el número de ese autor y no como un benchmark. El informe del sistema de investigación multiagente de Anthropic es aquí la única fuente con datos reales detrás, y ese mismo estudio encontró que un agente líder en Opus con subagentes en Sonnet superó a un único agente Opus por un 90,2 % en su evaluación interna. Ese resultado, no el conteo de tokens, es el argumento a favor de repartir modelos por niveles.

Sáltate el subagente cuando la salida de todos modos pertenece a tu conversación principal, porque solo la volverás a pegar y pagarás dos veces. Sáltatelo para ediciones pequeñas donde el viaje de ida y vuelta de la delegación cuesta más que hacer el trabajo directamente. Y sáltatelo cuando la tarea de verdad necesite tu historial de conversación: usa un fork en su lugar, que hereda toda la conversación y reutiliza la caché de prompt del padre, lo cual lo hace más barato que un subagente nuevo para trabajo paralelo intensivo en contexto. Tanto la guía de costes de Anthropic como su criterio sobre cuándo usarlos llegan al mismo sitio.

Vale la pena conocer el tope de 200 por sesión antes de diseñar un fan-out. Es un límite real contra la delegación descontrolada, y subirlo es un acto deliberado, no algo por defecto.

Sobre el autor

Mert Batur construye en Techsy, donde el equipo lanza agentes de IA, sistemas de automatización y pipelines de voz y SDR para clientes B2B. Escribe sobre el stack de herramientas LLM y las Claude Skills que el equipo de Techsy usa de verdad en producción.

Techsy — University of Birmingham · LinkedIn

Preguntas frecuentes

¿Qué son los subagentes de Claude Code?

Los subagentes de Claude Code son asistentes especializados que corren cada uno en su propia ventana de contexto, con un system prompt propio, acceso restringido a herramientas y permisos independientes. Se definen como un archivo Markdown con frontmatter YAML en .claude/agents/. El subagente se encarga de una tarea paralela y devuelve solo su resumen a tu conversación principal.

¿Claude Code usa subagentes automáticamente?

Sí. Claude lee el campo description de cada subagente disponible y delega cuando una tarea encaja, sin preguntarte antes. Desde v2.1.198 los subagentes corren en segundo plano por defecto, así que el trabajo delegado suele suceder mientras tú sigues escribiendo en la conversación principal.

¿Dónde viven los archivos de subagentes?

Los subagentes de proyecto viven en .claude/agents/ y los de usuario en ~/.claude/agents/. Ambas ubicaciones se escanean de forma recursiva, así que las subcarpetas no son problema. La identidad viene solo del campo name del frontmatter, nunca de la ruta. Los subagentes gestionados que despliega un administrador tienen prioridad sobre las definiciones de proyecto y de usuario que compartan nombre.

¿Cómo invoco un subagente de forma explícita?

Pídelo por nombre en tu prompt, por ejemplo "usa el subagente validator en este borrador". La invocación explícita se salta el matching de description que impulsa la delegación automática, lo cual ayuda cuando dos de tus subagentes tienen descripciones que se solapan y Claude sigue eligiendo el equivocado.

¿Puede un subagente lanzar sus propios subagentes?

Sí, desde Claude Code v2.1.172. Las guías escritas antes de esa versión dicen que el anidamiento es imposible, y están desactualizadas. La profundidad cuenta niveles por debajo de la conversación principal y está fija en cinco: un subagente en el nivel cinco no recibe la herramienta Agent. El límite no es configurable.

¿Los subagentes recuerdan algo entre sesiones?

Solo si defines el campo memory. Acepta user para ~/.claude/agent-memory/<name>/, project para .claude/agent-memory/<name>/, o local para .claude/agent-memory-local/<name>/. Sin él, cada invocación arranca en blanco. Doce de nuestros dieciocho agentes usan memory: project para que sus notas viajen con el control de versiones.

¿Puede un subagente usar un modelo distinto al de mi sesión?

Sí. Define model en el frontmatter como haiku, sonnet, opus, o un ID de modelo concreto, y anula el modelo de tu sesión para ese subagente. Nuestra flota se reparte en seis en Opus, once en Sonnet, y uno en Haiku, asignados según cuánto criterio exige la salida de cada agente.

¿Por qué no aparece mi subagente nuevo?

Tres causas habituales. El directorio agents no existía cuando arrancó la sesión, así que el watcher nunca lo detectó: reinicia Claude Code. O dos archivos comparten el mismo name y solo carga uno. O nada en tu lista de tools resuelve, lo cual desde v2.1.208 se niega a lanzarse con un error que nombra el problema.

¿Sigue siendo válido el nombre de herramienta Task?

Sí, como alias. La herramienta Task se renombró a Agent en v2.1.63, y las referencias Task(...) existentes siguen funcionando en la configuración y en las definiciones de agentes. Escribe Agent en los archivos nuevos. Nuestro propio translation-coordinator.md todavía declara Task, algo que encontramos mientras escribíamos este post y que no hemos limpiado.

Tres cosas que llevarte

Si estás montando tu primera flota, empieza por aquí. El campo description lo decide todo, porque es lo que Claude lee al elegir un worker, así que escríbelo como una regla de enrutamiento y no como un título de puesto. Diseña el traspaso como un archivo antes de diseñar el agente, porque ningún subagente verá nunca el contexto de otro. Y pon cada agente en el modelo más barato que pueda producir una respuesta correcta, y súbelo de nivel solo cuando lo pilles equivocándose.

Explora la biblioteca completa para ver las especificaciones detrás de este pipeline.