Estructurar tu equipo de subagentes, los seis roles que necesitas en el día a día

Construir un subagente es el ejercicio fácil. Hacer que seis corran en paralelo sin que se destrocen los archivos entre ellos o repitan la misma investigación tres veces, eso es lo difícil. Lo probé durante ocho semanas con cinco setups distintos y acabé en exactamente seis roles que le sirven a cualquier fundador en solitario o equipo pequeño. Con más se vuelve inmanejable, con menos quedan huecos.

Requisito: has hecho el playbook "Tu primer sub-agente en 30 minutos" y conoces el patrón CEO-worker de Nivel 5, lección 2. Esto es el siguiente paso, convertir a un especialista suelto en un equipo que rema junto.

1. Los seis roles que casi todo el mundo necesita

Antes de crear ningún archivo, piensa qué tareas delegas de verdad. De mis ocho semanas de pruebas salieron estas seis:

• Researcher, investiga fuentes externas, resume, escribe un informe
• Reviewer, lee código o texto y da feedback concreto, pero no cambia nada
• Drafter, escribe las primeras versiones de textos, código, correos, posts
• Auditor, comprueba si las afirmaciones se sostienen, verifica fuentes, contrasta contra el inventario
• Coordinator, reparte tareas entre los demás, junta los resultados
• Janitor, limpia, archiva, deduplica, borra drafts viejos

Seis es el techo. Una vez tuve ocho y el coordinator se olvidaba de todo porque había demasiadas opciones. Con seis acierta de forma consistente.

2. Define los perfiles de permisos por adelantado

Cada subagente recibe un acceso a herramientas distinto. Esto es obligatorio, si no, en tres semanas tienes a alguien que "en un momentito" sobrescribe prod. Mi estándar:

• Researcher: solo Web-Search + Read, nada de Write, nada de Bash
• Reviewer: solo Read + Grep, nada de Write
• Drafter: Read + Write solo en drafts/, nada de git
• Auditor: Read + Web-Search + herramientas de verificación, nada de Write
• Coordinator: solo llamadas de herramienta a otros agentes, nada de escritura directa de archivos
• Janitor: Read + Write + Delete en drafts/.archive-*, nada más

Escribe eso como primera entrada en cada archivo markdown de agente, arriba del todo en el frontmatter. Si tu setup soporta los permisos con un array tools:, úsalo. Si no, ponlo en prosa dentro del prompt y que filtre el coordinator.

3. Divide la carpeta de agentes con orden

Con seis agentes necesitas estructura. En mi caso queda así:

~/.claude/agents/
  researcher.md
  reviewer.md
  drafter.md
  auditor.md
  coordinator.md
  janitor.md

Por proyecto añades además .claude/agents/ en el repo, y ahí van las variantes de proyecto. Si para Academy necesitas un drafter distinto del que usas para webs de clientes, crea .claude/agents/drafter.md en el repo de Academy. Ese sobrescribe al global automáticamente. Importante: los globales son los generalistas, los locales los especialistas. No al revés.

4. Quién dispara a quién

El error de principiante más común: que cada agente pueda llamar a cualquier otro. Eso te da bucles infinitos. En mi setup solo va en una dirección. El coordinator está arriba y llama a researcher, drafter, reviewer, auditor y janitor. Esos cinco no llaman a nadie. Si el drafter quiere que algo se revise, se lo devuelve al coordinator con una nota tipo "por favor planifica una revisión". El coordinator decide.

Suena engorroso, pero no lo es. Evita que acabes en bucles y hace que depurar sea trivial. Cuando algo sale mal, mira la traza del coordinator.

5. Memoria compartida o contextos aislados

Aquí se pone delicado. Cada subagente tiene su propia ventana de contexto. Si el researcher ha leído 30 fuentes, el drafter no ve nada de eso. Tres opciones:

Primera opción: después de cada llamada a un subagente, el coordinator escribe un resumen en un archivo y se lo pasa al siguiente agente como input. Funciona, pero es trabajo manual.

Segunda opción: usas un servidor MCP de memoria (mira Nivel 4, lección 3) y todos los agentes leen y escriben en el mismo almacén de memoria. La solución más bonita. Pero requiere setup.

Tercera opción: dejas que cada agente trabaje aislado y asumes que algunas cosas se investigarán dos veces. En equipos pequeños suele estar bien.

Yo uso la opción dos con StudioMeyer Memory. En mi caso redujo la investigación duplicada alrededor de un 60 por ciento.

6. Fija las convenciones de output

Si el drafter escribe Markdown hoy y YAML mañana, el reviewer no puede hacer nada con eso. Mi patrón:

• El researcher escribe siempre un informe con # Frage, ## Quellen, ## Befund, ## Verdict
• El drafter escribe siempre en drafts/{kind}/{slug}.md con frontmatter
• El reviewer escribe siempre una lista con el formato - [Severity] Zeile X: Befund
• El auditor escribe siempre una estadística de verificación arriba y los hallazgos abajo
• El coordinator escribe un bloque de estado: qué se ha hecho, qué queda abierto, siguiente paso

Eso hace que fusionar outputs sea trivial. Lees tres informes y todos están estructurados igual.

7. Evitar conflictos entre agentes

Tres conflictos aparecen una y otra vez:

Drafter y janitor: el drafter escribe, el janitor archiva. Si corren a la vez puede pasar que el drafter escriba un archivo, el janitor lo vea y lo retire al instante. Solución: el janitor no corre nunca en paralelo, solo mediante un trigger explícito del coordinator.

Researcher y auditor: los dos llaman a URLs externas. Si se piden las mismas URLs, pagas el doble. Solución: el auditor mira primero en el almacén de memoria si el researcher ya tenía esa URL. Si es así, la recicla.

Reviewer y drafter: el drafter escribe la versión 1, el reviewer encuentra 12 issues, el drafter escribe la versión 2 con issues en parte nuevos. Solución: máximo dos rondas de revisión por draft, después de eso pasa a una persona.

8. Cuándo el coordinator quiere demasiado

En algún momento mi coordinator empezó a querer hacerlo todo él mismo en vez de delegar. Deriva clásica. El patrón detrás: cuando el prompt del coordinator lleva demasiadas reglas del tipo "si X, haz Y", se cree que puede hacerlo directamente él. Solución: escribir más corto y poner al final una frase como "Eres el coordinator, no el executor. Tu trabajo es delegar, no ejecutar."

Síntomas concretos para reconocerlo: el coordinator da respuestas de 800 palabras cuando bastarían tres llamadas a subagentes. El coordinator discute con el usuario en vez de preguntar. El coordinator se olvida de arrancar los subagentes.

En mi caso, un reset a un system prompt de 200 palabras resolvió el problema en un día.

9. Eval y mejora

Después de dos semanas de funcionamiento deberías saber qué agente es demasiado lento, cuál alucina demasiado a menudo, cuál cuesta demasiado. Mi setup:

El coordinator corre un par de veces al día y yo registro el consumo de tokens por agente en un CSV. Después de una semana veo esto: el researcher se lleva el 40 por ciento, el drafter el 30, el auditor el 15, el reviewer el 10, el coordinator el 4, el janitor el 1. Si el drafter sube de repente al 50, voy a mirar qué ha cambiado en el prompt.

Si quieres el eval de forma más sistemática, échale un ojo al playbook "Eval de agente en 60 minutos". Ahí se ve cómo lanzar casos de test contra cada agente.

10. Cuándo NO necesitas subagentes

Para que esto no suene a "todo el mundo tiene que construir agentes": si tienes menos de tres tareas recurrentes, no necesitas un equipo. Con un solo subagente basta. Si no tienes tareas recurrentes, no necesitas ninguno, entonces Claude Code a secas es mejor. Y si tienes más de tres personas en el equipo llevando cada una su propio setup, un equipo de agentes puede quedarse en sobreingeniería y lo que necesitas es un setup multiusuario de verdad con configuraciones compartidas.

Regla práctica que a mí me funciona: a partir de cuatro tareas recurrentes por semana, el esfuerzo de montar un equipo compensa. Por debajo, no.

Qué viene después

Cuando tengas el equipo montado, estos son los dos siguientes pasos. Primero, échale un ojo al playbook "Hooks contra alucinaciones" para automatizar los pasos de auditoría. Segundo, lee Nivel 6, lección 7 "Orquestación multiagente" para los patrones avanzados si vas camino de escalar.

Fuentes para profundizar:

• Documentación de Anthropic sobre subagentes en Claude Code: https://docs.claude.com/en/docs/claude-code/sub-agents
• Patrón de investigación multiagente (blog de Anthropic): https://www.anthropic.com/engineering/multi-agent-research-system