Imagina que eres un contratista general trabajando en una obra. No colocas cada ladrillo: llamas al electricista, al plomero, al pintor; cada uno hace su parte y te entrega el trabajo listo. En Claude Code funciona igual. Conversas con el maestro (el chat principal). Cuando aparece un trabajo pesado, el maestro activa subagentes: especialistas que hacen el trabajo en una ventana separada y devuelven solo el resumen. Este es el diseño que tienes que grabarte.
↑ El flujo del subagente: uno lo lanza, muchos trabajan en paralelo y vuelve un resumen.
Contenido detallado
🎼 El maestro y el especialista
El chat con el que conversas es el orquestador — el director. Entiende la solicitud, decide qué hay que hacer y, cuando la tarea es grande, delega a un especialista. Nunca dejas de hablar con el maestro: es tu punto de contacto de principio a fin.
🏗️ La analogía del contratista general
El contratista general no coloca ladrillos, no instala cables ni pinta paredes. Él coordina. Cada especialista llega, hace su parte con pericia y entrega. El contratista lo integra todo y te entrega la obra terminada. El director de orquesta de Claude Code es ese contratista:
- •Maestro = el chat principal. Entiende, planifica, delega y reúne.
- •Subagente = el especialista. Recibe una tarea única y se enfoca solo en ella.
- •Tú = el dueño de la obra. Solo habla con el maestro y ve el resultado.
El maestro es el agente principal: quien conduce la conversación y distribuye el trabajo. El subagente es un trabajador que activa según sea necesario para una tarea específica.
Sin tener este modelo en mente, intentas "conversar" con el subagente o esperas que recuerde toda la conversación. Entender quién coordina y quién ejecuta evita el 90% de la confusión inicial.
Orquestador × ejecutor · delegación bajo demanda · punto de contacto único (tú ↔ maestro).
🔁 El ciclo: tarea → ventana propia → informe
El corazón del subagente es el contexto separado. Cuando el director delega, el subagente abre una ventana propia — una sesión limpia, aislada de tu conversación. Hace el trabajo allí, genera todo el desorden que necesite y devuelve solo un informe. El director de orquesta lee ese informe y te comunica el resultado. Tu ventana nunca ve el desorden.
La tarea se despacha
El maestro identifica una tarea pesada.
Escribe un briefing claro y se lo entrega al subagente: "lee estos 40 archivos y dime dónde falla el inicio de sesión".
El subagente trabaja en su ventana
Sesión propia, aislada, descartable.
Abre archivos, ejecuta búsquedas y acumula cientos de líneas de lectura, todo dentro de su contexto, que desaparece cuando termina.
El informe vuelve limpio
El maestro se comunica contigo.
El subagente devuelve la conclusión: "el bug está en auth.js, línea 88". El maestro te pasa eso, sin los 40 archivos de por medio.
📊 Por qué importa tener una ventana propia
El subagente puede "quemar" 200 mil tokens leyendo archivos y eso no ocupa un solo token de tu sesión. Te quedas con la conclusión; la lectura en bruto quedó en su ventana descartable. Es protección del contexto: el tema del próximo módulo.
🎭 La demo de las 5 personas
El ejemplo clásico: le pides al maestro que revisar un libro bajo cinco perspectivas diferentes. En vez de hacer cinco lecturas seguidas, abre cinco subagentes en paralelo — cada uno con una lente propia. Se ejecutan al mismo tiempo, cada uno en su ventana. Y puedes entrar en cada sesión y ver exactamente el prompt que el maestro envió a ese especialista.
Linda, 58
Profesora jubilada · principiante en IA
"¿Esto tiene sentido para alguien que nunca escuchó hablar del tema? ¿Dónde me trabé?"
Ingeniero de software
Perspectiva técnica
"¿Los ejemplos de código son correctos? ¿Falta rigor en algún punto?"
Dueño de negocio
Perspectiva de retorno
"¿Cuál es el valor práctico? ¿Esto me ayuda a ganar o ahorrar dinero?"
David, 52
COO de Fortune 500 · visión de escala
"¿Esto funciona con 5.000 empleados? ¿Dónde falla en una operación grande?"
Editor / publisher
Perspectiva editorial
"¿El texto fluye? ¿El argumento se sostiene de principio a fin?"
Cinco en paralelo
Cinco perspectivas, al mismo tiempo, cada una en su ventana. El maestro reúne los cinco informes.
💡 Puedes inspeccionar cada sesión
Cada subagente se ejecuta en una sesión visible. Puedes abrir la del «COO» y leer el briefing exacto que el maestro escribió para ella. Esto desmitifica al subagente: no es magia, es un chat enfocado que alguien abrió para una tarea.
🚫 Qué NO es el subagente
Aquí está la confusión más común. El subagente no es el chat principal y tú no conversa directamente con él. No te responde a ti; le responde al maestro. Pensar en él como «otro chat donde escribo» es el error que hace que todo parezca no funcionar.
✓ Qué ES el subagente
- ✓Un trabajador enfocado, activado por el maestro
- ✓Dueño de una ventana de contexto separada
- ✓Quien entrega un informe y desaparece
- ✓Subordinado al maestro, no a ti
✗ Lo que el subagente NO es
- ✗No es tu chat principal
- ✗No es alguien con quien escribes directamente
- ✗No guarda la memoria de tu conversación
- ✗No te responde a ti, le responde al maestro
⚠️ El error que frena a quienes empiezan
Intentar "responder" a un subagente como si fuera una ventana de chat. No está esperando tu input: ya recibió las instrucciones del maestro y está ejecutando. Si quieres cambiar algo, hablas con el maestro, y el maestro ajusta o activa un nuevo subagente.
🔗 Relación 1 a 1 con el maestro
Cada subagente habla solo con el maestro. Los subagentes no conversan entre sí. Es un modelo en estrella: el director en el centro, cada especialista conectado a él por una línea directa y sin líneas entre los especialistas. Así todo se mantiene predecible, sin «teléfono descompuesto» entre trabajadores.
✓ Cómo ocurre el flujo
- ✓Subagente → director de orquesta (informe)
- ✓Maestro → subagente (instrucciones)
- ✓El maestro reúne los informes de todos
✗ Qué no funciona
- ✗Subagente A → subagente B
- ✗Dos subagentes «negociando» una respuesta
- ✗Un subagente leyendo la ventana del otro
🚀 Primer contacto — invoca un built-in
No necesitas crear nada para empezar. Claude Code ya viene con subagentes built-in
(como el general-purpose, que investiga y lee archivos). Para activar uno, basta con
lenguaje natural: describes el servicio y el maestro decide delegar. Sin comandos
especiales ni sintaxis difícil.
você > Pesquise a ferramenta "ripgrep" e me traga só
um resumo de 5 bullets, sem encher meu contexto.
# o maestro decide delegar a um subagente built-in,
# que abre a janela dele, faz a pesquisa pesada,
# e devolve ao maestro só os 5 bullets pedidos.
maestro > Pronto — 5 pontos sobre o ripgrep:
1) busca recursiva ultrarrápida em texto …💡 La frase que activa
Dos pistas hacen que el maestro delegue: "tráeme solo un resumen" (la salida es pequeña) y "sin llenar mi contexto" (la lectura es extensa y descartable). Este es exactamente el caso ideal para un subagente, y el tema de la "pregunta que decide" en el módulo 1.5.
Ejemplo real: un subagente en un archivo
Un subagente personalizado es solo un archivo .md: un encabezado de configuración
(frontmatter) y un cuerpo con las instrucciones. Vas a analizar cada campo en las siguientes rutas — por ahora, lee este code-reviewer.md lo mínimo, solo para ver cómo es.
--- # frontmatter: a CONFIGURAÇÃO do subagente
name: code-reviewer # minúsculas e hífens
description: Revisa o diff atual em busca de bugs,
falhas de segurança e testes faltando. Use após
qualquer mudança de código. # isto é o GATILHO
tools: Read, Grep, Glob # só leitura: não edita nada
model: sonnet # bom o bastante para revisar
---
# corpo: o CÉREBRO do subagente
You are a senior code reviewer.
When invoked:
1. Run git diff to see what changed.
2. Read the changed files and understand the intent.
3. Review for correctness, security and missing tests.
Flag: bugs, security holes, and missing tests.
Be concise. Do not rewrite the code — only report.⚙️ El frontmatter (configuración)
- name — cómo el maestro llama al agente.
- description — el disparador: permite que el director sepa cuándo usarlo.
- tools — lo que puede hacer (aquí, solo leer).
- model — qué modelo ejecuta la tarea.
🧠 El cuerpo (cerebro)
- Papel — «eres un revisor de código sénior».
- Pasos — qué hacer, en orden numerado.
- Salida — qué informar.
- Límites — lo que NO debes hacer (no reescribir).
Prompts listos (copia y pega)
Dos prompts para activar un subagente built-in ahora mismo, sin configurar nada. Fíjate en el patrón: pedir el resumen y proteger el contexto.
Abra um subagente pra pesquisar a ferramenta X e me
traga só um resumo de 5 bullets. Não cole o conteúdo
bruto aqui — só a conclusão.Use o general-purpose pra ler estes arquivos e me
resumir o que importa, sem encher meu contexto.
Devolva no máximo 1 parágrafo + os caminhos relevantes.Pantalla simulada: 5 subagentes en paralelo
Así es como aparece en la terminal la demo de las 5 personas: el maestro lanzó cinco subagentes y los ves ejecutándose lado a lado, cada uno con su modelo y su progreso. Abajo, la línea de estado muestra cuánto del tu el contexto está en uso — y casi no cambia, porque el trabajo pesado se hace en sus ventanas.
↑ Recreación ilustrativa del terminal (no es una captura de pantalla real). Observa los 5 subagentes trabajando a toda máquina mientras tu contexto apenas se mueve.
Ejercicio
Lista 3 tareas de tu día que darían buenos subagentes. Para cada una, justifica con la pregunta que decide: "¿esto va a soltar un montón de cosas que nunca voy a releer?"
Cómo hacerlo
- Piensa en cosas que haces en la computadora y que leen mucho, generan mucha salida, o si se repiten.
- Escribe la tarea en una línea (p. ej., "revisar 30 PDFs en busca de una cláusula").
- Responde, para cada una, la pregunta decisiva — y di qué criterio cumple.
✅ Criterio de verificación — cómo saber si acertaste
Cada tarea que enumeraste debe cumplir con al menos uno de estas tres señales:
- →Lee muchos archivos (la lectura en bruto no tiene que quedarse en tu contexto).
- →Genera mucho contenido que nunca vas a releer por completo (solo quieres la conclusión).
- →Es repetible o paralelo (se puede ejecutar varias veces, o varias a la vez).
Si una tarea es una edición rápida o exige toda la conversación, ella no es una candidata, y darse cuenta de eso también cuenta como acierto.
Ejemplo resuelto
Tarea: "leer 30 PDF de contratos y encontrar dónde aparece la cláusula de rescisión". ¿Buen subagente? Sí: lee muchos archivos y genera mucho contenido que no voy a volver a leer; solo quiero el "lo encontré en la página X de cada contrato". Cumple 2 de las 3 señales.
✅ Resumen del módulo
Próximo módulo:
1.2 — El verdadero motivo: contexto limpio. Por qué proteger el contexto es el motivo n.º 1 de los subagentes.