Subagentes de Claude Code: aislamiento de contexto, orquestador y revisor, cuándo no hacen falta

Qué son los subagentes de Claude Code

Un subagente es otra instancia del agente que el agente principal lanza para una tarea concreta. Tiene su propia ventana de contexto, su propio prompt de sistema y su propia lista de herramientas permitidas. El agente principal le transmite la descripción de la tarea, el subagente trabaja de forma independiente —lee archivos, ejecuta comandos— y devuelve solo el mensaje final.

La palabra clave aquí es aislamiento. Todo lo que el subagente leyó por el camino —decenas de archivos, una salida larga de pruebas, hipótesis descartadas— se queda en su contexto y no llega al contexto de la sesión principal. El agente principal ve un resultado breve: «el error está en la función X, la causa es tal, estos son tres lugares afectados».

Los subagentes de Claude Code son un caso particular de la idea general de los sistemas multiagente: en lugar de un único ciclo «pienso, actúo, verifico» aparece un grafo de varios nodos, cada uno con su papel y su responsabilidad.

Por qué hace falta el aislamiento de contexto

La ventana de contexto es el recurso principal del agente. En ella caben a la vez las instrucciones de CLAUDE.md, el historial del diálogo, el código leído y la salida de los comandos. Cuando el agente pasa media hora buscando la causa de un error, el contexto se llena de basura: archivos que no tenían nada que ver y registros de los que solo importa una línea.

Las consecuencias son conocidas por quien trabaja con agentes durante mucho tiempo: el modelo empieza a respetar peor las reglas del proyecto, confunde detalles y, al comprimir el historial automáticamente, pierde lo que era importante. El subagente lo resuelve de forma estructural: el trabajo sucio se hace en un contexto aparte, que se descarta después de responder.

• Búsqueda e investigación. «Encuentra todos los lugares donde se llama a la función de pago y describe cómo están implementados» es una tarea típica para un subagente.
• Verificaciones ruidosas. Ejecutar las pruebas y analizar las que fallan: se encarga a un subagente y se recibe la lista de causas.
• Lectura de documentos grandes. Una especificación de cientos de páginas hace falta por unos pocos datos: que el subagente los extraiga.

Cómo configurar un subagente: la carpeta .claude/agents

Un subagente propio se describe con un archivo Markdown que tiene una cabecera YAML. Los archivos del proyecto están en .claude/agents/ dentro del repositorio y los comparte todo el equipo a través de git; los personales están en ~/.claude/agents/ y funcionan en todos sus proyectos. Puede crear y editar un subagente de forma interactiva con el comando /agents en Claude Code.

---
name: code-reviewer
description: Revisa los cambios de código en busca de errores e incumplimientos de las reglas del proyecto. Úsalo después de terminar una tarea, antes del commit.
tools: Read, Grep, Glob, Bash
---
Eres un revisor de código. No tienes que corregir nada.

1. Revisa los cambios: git diff.
2. Comprueba cada cambio en busca de errores de lógica, manejo de errores,
   seguridad (SQL, escape de la salida, secretos).
3. Contrasta con las reglas de AGENTS.md.
4. Devuelve una lista de observaciones: archivo, línea, problema, por qué
   importa. Si no hay observaciones, dilo así.

Qué significan los campos:

El cuerpo del archivo es el prompt de sistema del subagente. No ve el historial de su diálogo, así que todo lo que necesite saber sobre su papel y el formato de respuesta debe estar en el prompt o en la tarea que le encarga el agente principal.

Cómo invocar a un subagente

El agente principal puede elegir al subagente por sí mismo si la tarea encaja con su description. Es más fiable pedirlo de forma explícita: «Usa el subagente code-reviewer para revisar los cambios». Expresiones como «úsalo de forma proactiva» en la descripción aumentan la probabilidad de que el agente lo invoque sin recordatorio, pero no lo garantizan.

Subagente explorador

Un segundo archivo que conviene crear en casi cualquier proyecto es un explorador de solo lectura. Responde preguntas sobre el código y no cambia nada.

---
name: explorer
description: Busca en la base de código respuestas sobre dónde y cómo está implementado algo. Úsalo cuando haya que leer muchos archivos para obtener una respuesta breve.
tools: Read, Grep, Glob
---
Investigas el código y no cambias nada.
Devuelve: una respuesta breve a la pregunta, una lista de archivos con líneas
en las que se apoya, y lo que no se pudo comprobar.

Este subagente es especialmente útil al principio de una tarea: el agente principal recibe un mapa de los lugares necesarios sin gastar contexto leyendo todo seguido, y a partir de ahí trabaja con archivos concretos.

Esquema «orquestador y ejecutores»

El esquema multiagente más extendido: un agente orquestador mantiene el plan y la visión global, y reparte los pasos concretos entre los ejecutores. El orquestador no lee todo el código por sí mismo: formula las tareas, acepta los resultados y decide qué hacer después.

1. El orquestador divide la tarea en partes independientes y escribe para cada una un encargo autosuficiente: objetivo, dónde buscar, qué se considera terminado, en qué formato devolver la respuesta.
2. Los ejecutores cumplen los encargos en sus propios contextos.
3. El orquestador reúne las respuestas, comprueba que las partes encajan y lanza el siguiente paso o vuelve a un paso anterior.

El punto débil del esquema es la transmisión de la tarea. El subagente sabe solo lo que se le ha escrito. Un encargo como «arregla el error del que hablamos» no le dice nada: no vio la conversación. Un buen encargo se lee como una tarea para un nuevo compañero que abre el repositorio por primera vez.

Qué debe devolver el ejecutor

Defina el formato de la respuesta de antemano: lista de archivos, salida, causas encontradas, qué no se pudo verificar. Una respuesta breve y estructurada ahorra contexto al orquestador, y el punto «qué no se ha verificado» protege frente a la falsa seguridad: el ejecutor, como cualquier agente, tiende a informar de éxito.

Revisor independiente: por qué separar al juez del ejecutor

Cuando el mismo agente escribe el código y además lo verifica, el juez y el acusado comparten una misma cabeza. El agente recuerda lo que quería hacer y ve en el código su intención, no lo que realmente está escrito. Además, tiene interés en terminar: la verificación se convierte en una formalidad.

El revisor en un contexto aparte no tiene esos problemas. No conoce el historial de decisiones, ve solo el diff y las reglas del proyecto, y evalúa el resultado con una mirada fresca. Es el mismo principio que en un equipo real: el autor no aprueba su propio pull request.

• Dé al revisor solo herramientas de lectura y de ejecución de comprobaciones, sin permiso para editar archivos. Así no empezará a «corregir en silencio» en lugar de informar del problema.
• Describa los criterios de revisión de forma explícita: qué se considera un error, qué reglas del proyecto son obligatorias.
• La decisión sobre qué hacer con las observaciones déjesela al orquestador o a la persona. El revisor encuentra; el ejecutor corrige.

El revisor no sustituye a las comprobaciones mecánicas. Las pruebas, el linter y la comprobación de tipos son nodos deterministas, más fiables que cualquier modelo. El revisor atrapa lo que la mecánica no ve: lógica incorrecta, incumplimiento de acuerdos, complejidad innecesaria.

Ejecución en paralelo de subagentes

Claude Code puede lanzar varios subagentes a la vez. Esto acelera el trabajo cuando las partes de la tarea son realmente independientes: estudiar tres módulos, revisar los cambios desde tres ángulos (seguridad, rendimiento, pruebas), reunir información de varias fuentes.

El paralelismo funciona bien en lectura y mal en escritura. Si dos ejecutores modifican a la vez los mismos archivos, se pisan los cambios mutuamente, y ninguno se entera. En términos del grafo de agentes, es un estado compartido sin regla de fusión. Reglas prácticas:

• En paralelo, investigación, análisis y revisión. En serie, las ediciones en archivos que se solapan.
• Si los ejecutores escriben en paralelo de todos modos, reparta las zonas: cada uno trabaja solo en sus archivos o en su propia copia del repositorio (por ejemplo, en un git worktree aparte).
• Los resultados los reúne un único nodo —el orquestador—, no los ejecutores entre sí.

Cuándo no hacen falta subagentes

El esquema multiagente tiene un coste: más tokens, más tiempo y más puntos en los que se pierde información al transmitirla. Los subagentes de Claude Code no siempre compensan.

Antes de construir un grafo de agentes, responda a preguntas sencillas: quién es responsable del objetivo común, quién puede vetar y revertir un cambio, qué métricas cuentan como éxito. Si no hay respuestas, varios agentes solo multiplicarán la confusión de uno.

Errores habituales con los subagentes

Descripción vaga

Una descripción como «asistente para código» no ayuda al agente principal a decidir cuándo llamarlo. Escriba el disparador: «después de cambios en la carpeta api/, antes del commit».

Encargo sin contexto

El subagente recibe la tarea sin rutas, sin criterios de terminado y sin restricciones, y gasta la mitad del trabajo en adivinar lo que se espera de él. Se soluciona con una plantilla de encargo: objetivo, datos de entrada, restricciones, formato de la respuesta.

Permisos demasiado amplios

Al explorador y al revisor no les hace falta el permiso para editar archivos. La restricción tools es una forma barata de convertir el papel en un mecanismo, y no en una petición escrita en el prompt.

Confiar en el informe sin comprobarlo

«Todas las pruebas pasaron» en la respuesta de un subagente es una afirmación, no un hecho. El orquestador debe basarse en algo comprobable: la salida del comando, el código de retorno, las líneas concretas.

En resumen

Los subagentes de Claude Code sirven para tres cosas: mantener limpio el contexto principal, separar la verificación de la ejecución y paralelizar el trabajo independiente. Se describen con archivos Markdown breves en .claude/agents/, y la calidad de su trabajo depende casi por completo de la descripción del papel, del conjunto de herramientas y de lo autosuficiente que sea el encargo. Cuando la tarea es pequeña o está muy ligada a la conversación, un solo agente sigue siendo mejor. El paso de un ciclo a un sistema de nodos, aristas y estado compartido se analiza en la práctica en el curso.