Subagentes de Claude Code: estructura, cinco roles y orquestación

¿Qué es un subagente de Claude Code y por qué no es «simplemente otra Skill»?#

La documentación de Claude Code lo define así:

Dicho en términos que entendería un emprendedor: imagina una agencia inmobiliaria. Hay un director, un especialista en marketing, un abogado y responsables de ventas. Que un empleado alterne entre todos esos roles no forma un equipo: es una persona sobrecargada. Un equipo surge cuando cada persona tiene su propio contexto y área de responsabilidad, mientras que el director solo asigna tareas y reúne los resultados.

Los subagentes de Claude Code funcionan de la misma manera. El chat principal es el director. Un subagente es un especialista con una tarea concreta, su propio contexto y conjunto de herramientas. Cuando una tarea coincide con la descripción de un especialista, el director la delega y no se atasca en los detalles.

5 objetivos para los que Anthropic creó los subagentes

La documentación de Anthropic enumera exactamente cinco motivos para crear tu propio subagente:

El punto más práctico de esta lista para alguien que no programa es el control de costes. Puedes encargar una tarea de investigación exigente al económico modelo Haiku mientras continúas la conversación principal con Sonnet u Opus. El ahorro de tokens es directamente proporcional.

Comprueba el anidamiento admitido por tu versión

Las plantillas de esta guía usan una sesión principal que delega directamente a trabajadores. No trates la documentación antigua que prohíbe iniciar subagentes desde otros como una regla permanente: depende de versión y herramientas permitidas. La guía de subagentes anidados describe una receta específica de versión. Verifica el soporte instalado antes de planear más profundidad.

¿En qué se diferencia un subagente de una Skill, un comando de barra y un hook?#

La guía anterior sobre Skills explica que las Skills y los comandos de barra de Claude Code se han fusionado, en la práctica, en un solo formato. Pero un subagente es una entidad diferente, no simplemente «una Skill más grande».

Tabla resumen de los cuatro mecanismos:

Una buena forma de explicarlo en una guía en español: las Skills son recetas; los subagentes son colegas especializados.

Las skills son como recetas; los subagents son como colegas especializados.

En la práctica, funciona así: las Skills se activan automáticamente cuando su descripción coincide con la tarea, mientras que los subagentes se invocan de forma explícita: el chat principal decide delegar o tú llamas a uno por su nombre.

Árbol de decisión: «¿Cuál debería elegir?»

Cuando pienses «necesito que Claude haga X», responde estas cuatro preguntas:

1. ¿Es conocimiento que debería estar siempre disponible? Por ejemplo, «localizamos en el idioma preferido del usuario» o «no usamos rayas em». Inclúyelo en CLAUDE.md.
2. ¿Es una metodología que se activa y que ahora realizas manualmente? Por ejemplo, «escribo un informe de ventas todos los lunes». Crea una Skill.
3. ¿Es una tarea que consumirá el contexto del chat principal o que puede ejecutarse en paralelo? Por ejemplo, «investigación exhaustiva en 30 fuentes» o «una auditoría de seguridad mientras escribo una función nueva». Crea un subagente.
4. ¿Necesitas una respuesta automática a un evento en Claude Code? Por ejemplo, «ejecuta el linter después de cada Edit». Escribe un hook.

El 90% de las tareas de un emprendedor pertenece a las dos primeras categorías. Los subagentes son una herramienta más avanzada, para cuando pasas de «una tarea a la vez» a la orquestación.

¿Dónde se guardan los subagentes de Claude Code y cuál tiene prioridad?#

La jerarquía de subagentes tiene cinco niveles, ordenados de mayor a menor prioridad:

La lógica de prioridad es igual que para Skills y CLAUDE.md: la organización prevalece sobre CLI, CLI sobre proyecto, proyecto sobre personal y personal sobre plugin.

Qué debes saber sobre la carga

Los subagentes se cargan al iniciar una sesión de Claude Code. Si editas manualmente un archivo de agente en el disco, los cambios no se aplicarán hasta que reinicies la sesión. Las ediciones realizadas desde la interfaz interactiva /agents se aplican de inmediato.

Un subagente por ámbito significa un archivo. Si .claude/agents/ contiene code-reviewer.md y otro code-reviewer.md a su lado (por ejemplo, de una copia de seguridad antigua), Claude Code ignorará uno de ellos sin avisar. No habrá ninguna notificación.

Los subagentes de plugins son un caso aparte. Tienen restricciones de seguridad: no admiten los campos hooks, mcpServers y permissionMode. Así se evita que la instalación de un plugin de terceros le permita ejecutar código arbitrario en tu máquina.

Estructura de un archivo de subagente: frontmatter y cuerpo#

Un ejemplo mínimo de la documentación oficial, de solo 9 líneas:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

Eres un revisor de código. Cuando te invoquen, analiza el código y ofrece
comentarios específicos y prácticos sobre su calidad, seguridad y buenas prácticas.

Eso basta. Si un usuario dice «revisa mi PR» en el chat principal, Claude relaciona «reviewer / code / quality» con la descripción y delega la tarea al subagente. El subagente lee el diff, redacta comentarios y devuelve un resumen al chat principal. El chat principal no se llena de registros ni de análisis intermedios.

Esquema completo del frontmatter

El campo model: haiku corresponde precisamente al «control de costes» de la lista de cinco objetivos. Si tienes un agente de investigación que lee 50 páginas de documentación, ponlo en Haiku para gastar entre 5 y 7 veces menos que con Opus.

El campo isolation: worktree resuelve un problema importante: un subagente realiza cambios potencialmente peligrosos (refactorización, migración), pero no quieres que toque tu copia de trabajo. Configura isolation: worktree y Claude Code creará una copia temporal de Git del proyecto; el subagente trabajará ahí y devolverá un diff para que lo revises.

El cuerpo del archivo es el prompt de sistema

Después del frontmatter viene Markdown normal, es decir, el prompt de sistema del subagente. No hace falta ninguna estructura especial, pero este patrón está probado:

1. Quién eres: una frase, por ejemplo: «eres un revisor de código», «eres un auditor de seguridad» o «eres un responsable de documentación».
2. Cuándo te invocan y qué haces primero: las primeras 2–3 acciones después de recibir la tarea.
3. Una lista de comprobación: entre 5 y 10 puntos que el subagente debe seguir.
4. Qué devuelves: el formato del informe final. Es fundamental: si no especificas un formato, el subagente producirá un «ensayo» en vez de un resumen estructurado.
5. Qué NO haces: limitaciones explícitas. Sin esta sección, el subagente empieza a improvisar.

Limita el cuerpo del archivo a 200–500 líneas. Si se hace más largo, traslada las referencias extensas a archivos cercanos y enlázalos desde el prompt.

Cómo escribir una descripción para que Claude invoque sin falta tu subagente#

Un problema habitual es configurar un subagent para revisar código, pero que Claude haga todo por su cuenta sin usarlo. Normalmente hay un solo motivo: la descripción dice «Helper for code review». Claude no entiende cuándo activarlo.

Fórmula para una descripción eficaz (3 partes)

Parte 1: qué hace. Una frase sobre el resultado, no sobre el proceso. No «analiza el código», sino «detecta vulnerabilidades en el código y devuelve una lista con su gravedad y una solución».

Parte 2: cuándo activarlo. Entre 3 y 5 frases entre comillas, tal como los usuarios realmente formulan sus solicitudes. No adivines: revisa tu historial de chats y la manera real de expresarlas.

Parte 3: cuándo NO activarlo. Entre 1 y 2 frases sobre tareas similares a las que este subagente no debería responder. Sin esta sección, dos agentes parecidos entran constantemente en conflicto.

La frase mágica «Use Proactively»

La documentación oficial de Anthropic hace una recomendación directa:

En otras palabras, Claude tiende a no invocar un subagente por defecto si la descripción no tiene señales claras. Añade «use proactively» o «use immediately after writing code» y la activación aumenta considerablemente.

Así es una descripción sólida

description: |
  Especialista experto en revisión de código. Revisa de forma proactiva la calidad,
  seguridad y facilidad de mantenimiento del código. Úsalo inmediatamente después de
  escribir o modificar código. Devuelve una lista priorizada de problemas con su gravedad
  y recomendaciones para corregirlos.
  No lo invoques para cambios en la documentación, ediciones de README ni reescrituras de
  mensajes de commit: de eso se encarga doc-maintainer.

Qué funciona aquí:

• Los verbos «revisa» + «devuelve» especifican un resultado concreto, no un proceso.
• «De forma proactiva» e «inmediatamente después» son activadores explícitos.
• «No lo invoques para...» evita conflictos con un subagente parecido.
• La descripción en inglés es lo habitual. Claude hace mejores coincidencias en inglés.

5 roles de subagente listos para usar en 10 minutos#

Cada rol que aparece a continuación es un único archivo, .claude/agents/<name>.md. Después de crear el archivo, reinicia Claude Code, abre /agents y comprueba que el nuevo agente aparezca en la lista. Luego puedes invocarlo con @agent-name.

1. code-reviewer: revisar el código después de cada cambio

Este es el ejemplo oficial de la documentación de Anthropic, adaptado a un flujo de trabajo:

---
name: code-reviewer
description: |
  Especialista experto en revisión de código. Revisa de forma proactiva la calidad,
  seguridad y facilidad de mantenimiento del código. Úsalo inmediatamente después de
  escribir o modificar código.
tools: Read, Grep, Glob
model: inherit
color: blue
---

Eres un revisor sénior de código que vela por unos altos estándares de calidad.

Al invocarte:
1. Lee el diff y la lista de archivos cambiados entregados por la sesión principal. Si faltan, pídeselos.
2. Usa Read, Grep y Glob para inspeccionar los archivos pertinentes.
3. Devuelve hallazgos sin cambiar archivos ni ejecutar comandos de shell.

Lista de comprobación:
- El código es claro y legible
- Las funciones y variables tienen buenos nombres
- No hay código duplicado
- Se gestionan correctamente los errores
- No hay secretos ni claves de API expuestos
- Se valida la entrada
- La cobertura de pruebas es adecuada
- Se tienen en cuenta los aspectos de rendimiento

Presenta los comentarios organizados por prioridad:
- Problemas críticos (hay que corregirlos antes de fusionar)
- Advertencias (conviene corregirlas)
- Sugerencias (se pueden valorar mejoras)

Formato: para cada problema, archivo:línea + 1 frase sobre por qué supone un problema + solución concreta.

La clave es tools: Read, Grep, Glob: lectura y búsqueda, sin Bash, Write ni Edit. La sesión principal prepara y entrega el diff. Decir «ejecuta solo git diff» no restringe una herramienta Bash plenamente concedida.

2. security-auditor: detectar vulnerabilidades y filtraciones

Este rol usa opus para razonar más y la misma restricción Read, Grep y Glob. Se omite memoria persistente de esta plantilla de solo lectura porque activarla también concede capacidad de escritura de memoria:

---
name: security-auditor
description: |
  Especialista en auditorías de seguridad. Úsalo de forma proactiva para detectar
  vulnerabilidades del OWASP Top 10, secretos expuestos, riesgos de inyección y problemas
  de autenticación. Ejecútalo antes de cualquier despliegue o fusión a main.
tools: Read, Grep, Glob
model: opus
color: red
---

Eres un auditor de seguridad. Detecta vulnerabilidades explotables, no problemas de estilo.

Lista de comprobación:
- Inyección SQL / NoSQL
- XSS (almacenado, reflejado, basado en DOM)
- Riesgos de CSRF / SSRF
- Secretos codificados directamente (claves de API, tokens, contraseñas)
- Autenticación o gestión de sesiones defectuosas
- Deserialización insegura
- Falta de validación de entradas
- Recorrido de rutas
- Redirecciones abiertas
- Referencias directas inseguras a objetos (IDOR)

Para cada hallazgo:
- Gravedad: Crítica / Alta / Media / Baja
- Archivo:línea
- Escenario de ataque en 1–2 frases
- Recomendación de solución con un ejemplo de código

Omite el ruido del linter o de estilo. Informa solo de problemas explotables.

Solo lectura en cuanto a las herramientas, con model: opus para comprobaciones complejas, como las cadenas de vulnerabilidades.

3. research-agent: investigación exhaustiva en más de 8 fuentes

Anthropic describe este patrón en su propio artículo sobre el sistema de investigación multiagente. La clave es especificar un formato de salida y prohibir volcar resultados sin procesar:

---
name: research-agent
description: |
  Especialista en investigación web exhaustiva. Úsalo de forma proactiva para buscar
  información, realizar análisis competitivos, recopilar documentación externa y comparar
  enfoques en varias fuentes.
tools: WebFetch, WebSearch, Read, Write
model: sonnet
maxTurns: 30
color: purple
---

Eres analista de investigación. Objetivo: un informe sintetizado, no volcados de búsquedas sin procesar.

Proceso:
1. Desglosa la pregunta en 3–5 subconsultas
2. Busca cada subconsulta con WebSearch y consulta las 3–5 fuentes principales de cada una
3. Contrasta las afirmaciones con al menos 2 fuentes independientes
4. Descarta el contenido de granjas SEO y agregadores; da preferencia a fuentes primarias
5. Cita literalmente y atribuye la URL de cualquier afirmación concreta
6. Devuelve: TL;DR (3 viñetas) + Hallazgos + Fuentes (mínimo 8 dominios)

Antipatrones que debes evitar:
- No cites un dato de una sola fuente
- No presentes paráfrasis de citas como si fueran literales
- No devuelvas al agente principal volcados de resultados de búsqueda sin procesar
- No incluyas introducciones o conclusiones de relleno («Espero que esto ayude»)

maxTurns: 30 protege frente a investigaciones que se prolongan en iteraciones interminables. Anthropic informa de esta cifra en su sistema de investigación multiagente:

El noventa por ciento se refiere a tareas de investigación comparativa. En la práctica, la mejora es menor en tareas empresariales, pero la magnitud general es parecida.

4. doc-maintainer: mantener la documentación sincronizada con el código

Este rol utiliza model: haiku, un ejemplo típico de «control de costes». La documentación no requiere Opus; Haiku hace el trabajo por un tercio del precio:

---
name: doc-maintainer
description: |
  Especialista en sincronización de documentación. Úsalo después de fusionar funciones para
  actualizar README, documentación de API y CHANGELOG. Lee los commits recientes, identifica
  cambios sin documentar y actualiza la documentación de forma proactiva.
tools: Read, Write, Edit, Glob, Grep, Bash
model: haiku
memory: project
color: green
---

Mantienes la documentación sincronizada con el código.

Al invocarte:
1. Ejecuta `git log --since="last release"` para ver los cambios recientes
2. Lee README.md, docs/, CHANGELOG.md
3. Identifica carencias: funciones nuevas sin documentar, API eliminadas que aún figuran en la documentación, discrepancias de versiones

Resultado:
- Archivos actualizados (usa Edit, no Write: conserva la estructura existente)
- Entrada en CHANGELOG.md con el formato Keep-A-Changelog
- Lista de cambios realizados (resumen del diff real, no una paráfrasis)

Reglas de estilo:
- Voz activa, presente
- Los ejemplos de código deben poder copiarse y pegarse
- Nada de lenguaje promocional («potente», «robusto», «fluido»)
- Nada de relleno («Esta guía te ayudará a...»)

5. refactor-agent: refactorización segura mediante un worktree

Este rol utiliza isolation: worktree: el subagente trabaja en una copia independiente del repositorio y solo fusionas los cambios si son correctos:

---
name: refactor-agent
description: |
  Especialista en refactorización segura. Úsalo para renombrar, extraer e insertar código
  en línea cuando no deba tocar la copia de trabajo hasta que se revise. Se ejecuta en un
  worktree temporal.
tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet
isolation: worktree
permissionMode: acceptEdits
color: yellow
---

Refactorizas código sin cambiar el comportamiento.

Reglas estrictas:
1. Las pruebas deben pasar ANTES y DESPUÉS de la refactorización.
   Si las pruebas previas fallan, DETENTE e informa.
2. Una refactorización atómica por commit (extraer, renombrar, insertar en línea).
3. Nunca cambies las API públicas sin instrucciones explícitas.
4. Nunca modifiques las pruebas, salvo que prueben directamente la implementación refactorizada.

Proceso:
- Ejecuta el conjunto de pruebas → referencia inicial
- Haz una refactorización atómica
- Ejecuta el conjunto de pruebas → verifica
- Crea un commit con un mensaje convencional: refactor(scope): what

Devuelve: resumen de cambios + ruta del worktree para que el usuario pueda comparar y fusionar.

Con este rol desaparece el problema de refactorización más doloroso: «Lo he roto y no sé cómo volver atrás». La copia original permanece intacta y el subagente trabaja en un worktree aislado.

¿Quieres copiar subagentes listos para usar o montar una combinación que convierta a Claude en una herramienta estable? Los subagentes forman parte de tu clon de IA: una forma de darle a Claude un equipo especializado que trabaje según tu lógica. Los tres pilares de la metodología son: clon de IA (Skills + Subagentes) + Segundo cerebro + Ingeniería de contexto. Esta combinación convierte a Claude de un asistente que adivina en una herramienta que razona según tu lógica.

Lanzar 5 subagentes en paralelo: orquestador + trabajadores#

La orquestación paralela es como «director de orquesta + músicos». El director conserva el plan, no escribe las partituras y comprueba cómo tocan los músicos. Si alguien toca una nota equivocada, el director le pide que la vuelva a tocar en lugar de intentar terminar en su lugar.

Para un emprendedor, una analogía más cercana es una agencia de marketing que prepara una estrategia para un cliente nuevo. Un analista realiza un SWOT, otro analiza a la competencia, un tercero crea un perfil de audiencia, un analista sénior descarta las hipótesis que no se ajustan al presupuesto y el gestor del proyecto prepara la presentación final. En Claude Code, este flujo empieza con una frase, y la crítica está integrada en el proceso en vez de llegar a posteriori.

Prompt mínimo de orquestación

Basta una frase en el chat principal:

Lanza cinco subagentes en paralelo: tres research-agents que trabajen con distintas fuentes
(documentación de Anthropic, repositorios de GitHub, blogueros de IA), un critic-agent para descartar
conclusiones débiles y un summary-agent para el documento final.

Contexto: estoy escribiendo una guía sobre X. Extensión objetivo: 2,000 palabras con fuentes.
Antes de empezar, cada uno lee CLAUDE.md.

Claude delega entonces las tareas a los cinco agentes. Cada uno trabaja en su propio contexto: los agentes de investigación utilizan sus respectivas fuentes, el agente crítico filtra y el agente de síntesis prepara el documento. Solo los resúmenes finales vuelven al chat principal.

Cuándo vale la pena el paralelismo

No siempre. La ejecución en paralelo solo tiene sentido cuando:

1. Las tareas son independientes. Si research-agent #2 está esperando el resultado de research-agent #1, no habrá paralelismo: en la práctica, trabajarán en secuencia.
2. Las tareas llevan mucho tiempo. No tiene sentido paralelizar «eliminar espacios en blanco al final de línea»: el coste de iniciar subagentes se comerá el beneficio.
3. Tienes límites suficientes. Más adelante se explica en una sección aparte: los subagentes paralelos consumen tokens rápidamente.

Multi-Agent v2 de Anthropic: un paso más

En mayo de 2026, Anthropic presentó Multi-Agent Orchestration v2 con tres diferencias importantes respecto al enfoque clásico de iniciar subagentes en paralelo. Se explican en la siguiente sección.

Novedades de Multi-Agent v2: orquestación, resultados y Dreaming#

Multi-Agent Orchestration: sistema de archivos compartido y comprobaciones durante el flujo

Anthropic describe la función así:

La diferencia clave respecto a los subagentes clásicos es el sistema de archivos compartido. Antes, cada subagente trabajaba en completo aislamiento y el intercambio se producía únicamente mediante el resumen devuelto. Ahora los especialistas pueden escribir en una carpeta compartida, y el agente principal lee los resultados a medida que avanza el trabajo, no solo al final. Esto resuelve el problema de «todos trabajaron durante todo el día y al final resultó que dos personas habían seguido enfoques incompatibles».

Lo segundo son las comprobaciones durante el flujo. El agente principal puede pausar el trabajo y preguntar a cualquier especialista «¿cómo va?», para luego ajustar el plan general. Se parece a la manera de trabajar de un gerente de equipo real.

Outcomes: una rúbrica en lugar de instrucciones paso a paso

Con Outcomes, escribes criterios de éxito y el agente busca la manera de cumplirlos. Un agente evaluador independiente comprueba el resultado desde su propio contexto para que el razonamiento del agente principal no lo «contamine».

Un diez por ciento en tareas difíciles es una mejora considerable. Especialmente cuando la tarea se formula como «redacta un artículo extenso que cumpla estos criterios de calidad», en lugar de «sigue los pasos 1–7».

Dreaming: los agentes acumulan experiencia entre sesiones

Esta es la función más novedosa en cuanto a su concepto. Un agente revisa sesiones anteriores, detecta patrones en los aciertos y errores y actualiza el almacén de memoria. Puedes configurar una revisión manual antes de aplicar los cambios o permitir que el agente edite la memoria por su cuenta.

Anthropic informa que Harvey (una empresa de tecnología jurídica) observó un aumento de aproximadamente seis veces en el éxito de tareas de redacción jurídica tras implementar Dreaming. Ya funciona en producción; no es solo una demostración.

Qué significa esto para emprendedores que no programan

Actualmente, se puede acceder a Multi-Agent Orchestration mediante Claude Agent SDK, no directamente desde la CLI de Claude Code. Pero la dirección está clara: la orquestación pasa de «inicias manualmente N subagentes» a «describes la tarea y el agente principal decide a quién delegar y cómo». Si acabas de empezar con los subagentes, todavía no te preocupes por v2. Aprende primero el patrón clásico de «1 chat principal + 3–5 subagentes con roles distintos» y, en 3–6 meses, podrás pasar de forma natural a Managed Agents.

7 errores que dejan a los subagentes fuera de juego#

Error 1. Las descripciones del tipo «Helper for X» no activan nada

Síntoma: escribiste un subagente, comprobaste su estructura y todo es válido, pero Claude no lo invoca cuando los usuarios hacen solicitudes. El motivo casi siempre es el mismo: la descripción es abstracta, como «Helper for code review». La solución: escribe directamente en la descripción entre 3 y 5 frases reales de usuarios entre comillas y añade «use proactively» / «use immediately after».

Error 2. Crear un subagente cuando hace falta una Skill

Un subagente cuesta más que una Skill: crea su propio contexto, carga su propio prompt de sistema y utiliza más tokens. Si la tarea es breve, no consumirá el contexto principal y puede completarse de una pasada, debería ser una Skill, no un subagente. Un ejemplo de antipatrón: un subagente format-validator que comprueba un esquema JSON con 20 reglas. Debería ser una Skill: un modelo, sin necesidad de aislamiento ni de cargar contexto adicional.

Error 3. Iniciar «60 agentes en paralelo» desde el principio

Esta es la ilusión más extendida. Ves un tuit que dice «tengo 1,500 agentes trabajando» y piensas «yo también debería hacerlo». En la práctica, 60 agentes agotan en una hora los límites de un plan Pro, generan un montón de resultados contradictorios y, al final del día, no has terminado nada.

Un profesional en Medium lo expresa así:

La solución: empieza con un subagente para una tarea. Cuando lo domines, añade un segundo con otro rol. Cuando domines la orquestación de dos, pasa a un equipo de 3–5. Saltar de «instalé Claude Code ayer» a «hoy tengo 20 en paralelo» garantiza que romperás código y agotarás los límites.

Error 4. Dar a todos los agentes acceso a todas las herramientas

Si tu revisor de código tiene acceso a Bash, Write y WebFetch, eso supone un enorme agujero de seguridad y costes. Un revisor no debería tener permiso para escribir archivos, y mucho menos para acceder a Internet.

La solución: limita tools estrictamente. Un revisor de código solo necesita Read, Grep, Glob. Un auditor recibe las mismas herramientas de lectura y búsqueda y un diff de la sesión principal. Añadir Bash concede shell; no lo limita automáticamente a git diff. Un agente de investigación necesita WebFetch, WebSearch, Read, Write. No le des a un subagente más permisos de los que necesita para una tarea concreta.

Error 5. Un subagente vuelca resultados sin procesar en el contexto principal

Si un agente de investigación devuelve «aquí están las 30 páginas que encontré; apáñatelas» al chat principal, has perdido la mayor ventaja de los subagentes: aislar el ruido. La solución: exige explícitamente un formato de salida en el prompt de sistema del subagente. «Devuelve SOLO: resumen ejecutivo de 3 viñetas + lista de 5 fuentes. SIN volcados de código, SIN resultados de búsqueda sin procesar». El formato debe ser estricto: el subagente no debería poder convertirlo en un ensayo.

Error 6. Solicitudes vagas: peticiones de delegación poco claras

Un subagente no puede ver el historial de la conversación principal. Empieza con un contexto limpio + CLAUDE.md + lo que le hayas escrito explícitamente. Si escribes «corrige la autenticación», el subagente inventará detalles. Especifica, en cambio: «Corrige el bucle de redirección de OAuth por el que, después de iniciar sesión correctamente, se redirige al usuario a /login en vez de a /dashboard. Archivo: src/lib/auth.ts».

Una regla clara: al delegar, da al subagente tanto contexto como le darías a un contratista que acaba de incorporarse al proyecto.

Error 7. Agentes basados en roles en vez de en tareas

Un patrón tentador es: «creemos un frontend-developer, un backend-developer y un qa-engineer, y hagamos que trabajen en equipo». No funciona. Cada «rol» pierde el contexto del proyecto en su conjunto y no pueden ponerse de acuerdo sobre los detalles porque no pueden verse entre sí.

La solución: un subagente debe encargarse de una tarea recurrente con un resultado claro, no de un rol. No «frontend-developer», sino «explore-ui-tree», «refactor-component» o «audit-accessibility». Cada subagente basado en tareas hace un único trabajo concreto y devuelve un único resultado concreto.

¿Cuánto cuestan los subagentes paralelos y cuándo valen la pena?#

Un plan Pro se agota en menos de una hora si lanzas 5 subagentes en paralelo para tareas complejas. Max 5x ($100) es un mínimo realista para trabajar con regularidad en paralelo. Para equipos y Enterprise, la cuestión del coste ya se gestiona en el presupuesto de herramientas.

Para saber más sobre cómo ahorrar tokens en Claude Code, consulta la guía sobre límites. Para los subagentes, la regla clave es que compensa usarlos en tareas que requieran al menos 10 minutos de trabajo concentrado. Si una tarea es más breve, no crees un subagente: hazla en el chat principal o con una Skill.

¿Cómo integrar subagentes en tu clon de IA y segundo cerebro?#

Un subagente depende de tres elementos que deberían estar en tu proyecto antes de crear el primer especialista:

1. El CLAUDE.md adecuado. Un subagente lee CLAUDE.md antes de empezar: es su «contrato de trabajo». Sin él, no conoce el contexto del proyecto, sus restricciones ni su tono. Inventará cosas.

2. Las Skills básicas. Una Skill es una metodología empaquetada. Un subagente carga solo las Skills que necesita, no todas a la vez. Sin Skills, repite el mismo trabajo desde cero cada vez.

3. Segundo cerebro: una estructura de conocimiento. La carpeta business/ (o su equivalente en tu ámbito) es una biblioteca que consultan todos los subagentes. Sin ella, un subagente da una respuesta promedio de ChatGPT, indistinguible de la de cualquier otra persona.

Invertir este orden supone generar expectativas exageradas sin resultados. «Tengo 60 subagentes en paralelo» con una carpeta business/ vacía significa tener 60 sesiones de ChatGPT promedio que aplican el mismo enfoque.

La combinación completa, clon de IA + Segundo cerebro + Ingeniería de contexto, constituye los tres pilares que hacen que Claude sea consistente. Los subagentes forman parte del clon de IA: una forma de darle a Claude un equipo especializado que trabaje según tu lógica.

La forma más rápida de empezar es copiar code-reviewer del primer ejemplo anterior en .claude/agents/code-reviewer.md, reiniciar Claude Code e invocar @agent-code-reviewer en tu próximo commit. En 5 minutos sabrás si necesitas subagentes o si basta con el chat principal.