Toda sesión de Claude Code tiene un límite de tokens — la ventana de contexto. Todo lo que escribes, todo lo que responde el modelo, cada archivo que se lee, cada búsqueda que se hace: todo ocupa una parte de esa ventana. Cuando se llena, el modelo empieza a olvidar el inicio de la conversación. Usar un subagente no se trata de hacer dos cosas al mismo tiempo, sino de evitar que la lectura en bruto envenene tu contexto antes de tiempo.
↑ Sin subagente: la lectura en bruto consume el 90% de la ventana. Con subagente: solo entra el resumen; queda contexto libre para lo que importa.
Contenido detallado
📏 La ventana de contexto: tokens, línea de estado y %
Cada sesión de Claude Code tiene un presupuesto de tokens. A línea de estado — esa barra en el pie del terminal muestra en tiempo real cuánto de ese presupuesto ya consumiste. Cuando se acerca al límite, el modelo empieza a olvidar las partes más antiguas de la conversación. No puedes comprar tokens adicionales a mitad de camino.
📊 Qué ocupa tokens
Read o Grep inyecta el contenido sin procesar en la ventana — y ahí se queda.maestro · Opus ──────────────────────────────────── ctx 18% ↑cost $0.04
# leu 3 arquivos? ctx sobe para 34%
# leu 40 arquivos? ctx vai para 87% — quase no limite
# enviou subagente ler 40 arquivos? ctx fica em 18%🚰 Contaminación: todo lo que lees permanece durante toda la sesión
Este es el punto que la mayoría ignora: en Claude Code, cuando pides que lea un archivo, el contenido sin procesar entra en tu ventana y se queda allí. No se va cuando termina la lectura. No desaparece cuando cambias de tema. Solo desaparece cuando termina la sesión. Eso significa que leer 50 archivos en medio de una tarea larga puede consumir toda la ventana antes de que llegues a la parte importante.
Pides «lee estos 10 informes»
El modelo usa la herramienta Read diez veces.
Cada llamada inserta el texto sin procesar en la ventana. 10 informes de 5 páginas = ~50k tokens consumidos en un abrir y cerrar de ojos.
El contenido bruto queda en la ventana
Incluso después de que el modelo «lo haya leído».
Claude ya procesó la información, pero el texto de las páginas 1-50 sigue ocupando espacio en la ventana. Es como mantener abiertas 50 pestañas que ya no vas a usar.
La ventana se llena antes de llegar a la parte importante
El modelo empieza a olvidar.
Si el 90 % de la ventana está ocupado por lectura sin procesar, no queda espacio para las instrucciones finales y el modelo puede «olvidar» el objetivo original de la sesión.
⚠️ La trampa invisible
No te das cuenta de que estás contaminando el contexto porque el modelo todavía responde bien durante un tiempo. El problema aparece solo al final: cuando necesitas un análisis complejo y la ventana ya está casi llena de información descartable. En ese punto, no hay forma de recuperarla: la sesión está comprometida.
⚖️ Hacerlo tú mismo × enviar un subagente
A veces tú mismo debes leer el archivo —cuando la lectura es rápida y vas a necesitar razonar sobre ella justo después. Pero cuando la lectura es compleja, amplia o descartable (solo quieres la conclusión), enviar un subagente protege tu ventana. La distinción es simple: ¿quedará algo útil en mi ventana después de leer esto?
✓ Usa un subagente cuando
- ✓Lectura pesada: muchos archivos, logs largos, PDFs voluminosos
- ✓Solo necesitas la conclusión (no el texto sin procesar)
- ✓Búsqueda en la web con resultados de páginas completas
- ✓Tarea repetible que no depende del contexto actual
✗ Hazlo tú cuando
- ✗Es un único archivo corto al que vas a hacer referencia enseguida
- ✗La tarea requiere todo el historial de la conversación
- ✗La decisión depende del contexto que solo tiene el maestro
- ✗La lectura es la tarea en sí: no hay ningún "resumen que extraer"
💡 La pregunta de oro
Antes de pedirle a Claude que lea algo pesado, pregunta: "¿Voy a necesitar volver a leerla en contexto o solo necesito la conclusión?" Si la respuesta es solo de la conclusión, envía un subagente. Así de simple. Este filtro por sí solo evita el 80% de las sesiones comprometidas.
📬 El resumen limpio que vuelve al maestro
El subagente hace la lectura pesada en la su ventana — que está separado, es descartable y desaparece cuando termina. Lo único que vuelve al maestro es salida estructurada que pediste: 3 hechos, 1 párrafo, una lista de rutas, un número. Nada del texto bruto que leyó el subagente llega a tu ventana.
📊 Qué «vuelve» y qué «se quedó allí»
Se quedó en la ventana del subagente (descartado)
- ✗El texto en bruto de los 300 PDFs
- ✗Resultados intermedios de las búsquedas
- ✗Errores e intentos de lectura
- ✗Tokens de razonamiento interno
Llegó a tu ventana (lo que importa)
- ✓La conclusión: «X ocurrió en el 18% de los contratos»
- ✓Las rutas pertinentes: ["doc/contrato-12.pdf", …]
- ✓Flags explícitos: "falta la cláusula de rescisión en 4"
💡 Dar formato a la salida es parte del briefing
El subagente devolverá exactamente lo que le pidas. Si escribes "devuelve como máximo 3 viñetas con lo que encontraste", te devolverá 3 viñetas. Si escribes "devuelve el JSON con los campos X, Y, Z", te devolverá JSON. La compactación del resumen es controlada por ti en el briefing — no es magia, es una instrucción.
🏆 Por qué un contexto limpio supera la velocidad
Decir que los subagentes son "más rápidos" es técnicamente cierto para las lecturas en paralelo, pero es el motivo equivocado para usarlos. Un subagente en serie (uno a la vez) aun así protege la ventana. La la razón n.º 1 es cualitativa: una sesión con contexto limpio razona mejor, comete menos errores de "olvido" y puede continuar hasta el final sin degradarse.
⚡ Velocidad (motivo secundario)
- →El paralelismo reduce el tiempo total cuando hay varios subagentes
- →Pero un único subagente secuencial no es más rápido que si el maestro lo hiciera por su cuenta
- →La latencia al iniciar el subagente incluso puede aumentar el tiempo total en tareas pequeñas
🧠 Contexto limpio (motivo n.º 1)
- ✓El maestro razona sobre el problema, no sobre los datos sin procesar
- ✓La sesión larga no se degrada: la ventana nunca se llena de contenido descartable
- ✓Las respuestas del maestro mantienen la coherencia de principio a fin de la tarea
📊 Datos que ayudan a interiorizar
- →Un archivo de código típico ocupa ~2–5k tokens. Leer 40 archivos = 80–200k tokens más en la ventana.
- →Con un subagente reader, esos 200k quedan en su ventana; en la tuya solo entra el resumen de ~500 tokens.
- →Ahorro potencial: 99,75% del costo de contexto en esta lectura específica.
📚 Caso concreto: 300 páginas → 3 hechos
El caso más destacado del curso: tienes 300 páginas de informes financieros y necesitas
3 hechos para tu presentación de mañana. Si el maestro lee los 300
documentos, la ventana explota. Si un researcher (Haiku) leer todo en su ventana
y devolver solo los 3 datos; tu ventana no supera el 15%.
🔢 Los números del caso
Ejemplo real: el subagente researcher
O researcher es el subagente arquetípico de protección del contexto: usa
Haiku (barato y rápido), solo lee (sin escribir ni ejecutar) y recibe instrucciones explícitas para devolver solo el resumen. Es el modelo que
vas a replicar para cualquier tarea de «lectura extensa → conclusión concisa».
--- # frontmatter: configuração do subagente
name: researcher
description: Pesquisador de contexto limpo. Use quando precisar
ler muitos arquivos ou buscar na web e só quiser a
conclusão — não o conteúdo bruto. Mantém a janela
do maestro quase intacta.
tools: Read, Grep, Glob, WebSearch, WebFetch
model: haiku # barato e rápido para leitura volumosa
---
# corpo: o comportamento do researcher
You are a research assistant focused on context efficiency.
Primary rule: Never return raw file content or raw web pages.
Always distill. Your output must be ≤ 10% of what you read.
When invoked:
1. Understand what facts the orchestrator needs.
2. Read or search as much as needed (your context, not theirs).
3. Identify only the facts that answer the question.
4. Return a structured summary: bullets, JSON, or a short paragraph.
Output contract:
- Max 5 bullets OR 1 short paragraph OR 1 JSON object.
- Include file paths or URLs as references, not content.
- If nothing found, say so in ≤ 2 sentences.
Do not: paste raw file content · return full web pages ·
exceed the output contract · ask clarifying questions.⚙️ Por qué importa cada elección
- Haiku — la opción más barata: una lectura intensa no requiere un razonamiento profundo.
- Read+Grep+Web — solo lectura: sin riesgo de escribir o ejecutar algo por accidente.
- "≤10% de lo que leyó" — la regla numérica que ancla el output contract.
- Sin preguntas — el researcher no interrumpe al director a mitad de la tarea.
🧩 Cuándo activar este agente
- →"Revisa los registros de errores de las últimas 2 semanas"
- →"Lee los 8 PRD y dime cuáles mencionan 'autenticación'"
- →"Investiga en la web el estado del arte en RAG y tráeme 5 viñetas"
- →"Revisa toda la base de código en busca de todos los TODO y clasifícalos"
Prompts listos (copia y pega)
Usa estos prompts para delegar investigación exhaustiva a researcher y mantener
limpia tu ventana. Observa el patrón: pedir explícitamente
solo la conclusión y especificar el formato de salida.
Use o researcher pra varrer os PDFs em docs/contratos/
e me trazer só os 3 contratos que mencionam "rescisão
unilateral". Devolva: nome do arquivo + trecho exato (1 linha).
Não cole o conteúdo completo aqui.Abra o researcher e peça para ele pesquisar na web
"Claude Code subagent best practices 2025" e me trazer
5 bullets com as principais recomendações. Sem colar
páginas inteiras — só a síntese.Use o researcher pra varrer toda a codebase buscando
chamadas a `fetch()` sem tratamento de erro. Devolva
em JSON: { "arquivo": "...", "linha": N, "trecho": "..." }
para cada ocorrência. Não cole o código dos arquivos.Pantalla simulada: researcher leyendo 300 páginas
Mira cómo se muestra la status line de maestro casi no se mueve mientras el
researcher consume la lectura pesada. El maestro queda libre para razonar.
↑ Recreación ilustrativa del terminal (no es una captura de pantalla real). Researcher consume 204k tokens en su ventana; tu contexto se mantiene en 14%.
Ejercicio: estima los tokens ahorrados
Toma una tarea real de tu día: algo que ya le pediste a Claude y que implicó leer varios archivos. Calcula (de forma estimada) cuántos tokens más habrían entrado en tu ventana si lo hubieras hecho sin subagente.
Cómo hacerlo (3 pasos)
- Escribe la tarea: p. ej., "leer los logs de deploy de la semana (8 archivos, ~600 líneas cada uno)".
- Estima el tamaño sin procesar: n.º de archivos × promedio de líneas × ~4 (tokens por línea) = tokens si lo leyera el maestro.
- Estima la salida del subagente: ¿cuántas viñetas o líneas realmente necesitarías como respuesta? Multiplícalo por 4. Esa es la salida que entraría en tu ventana con el researcher.
✅ Criterio de verificación
Acertaste si:
- →Calculó por separado el recuento bruto de tokens (entrada) y el recuento de tokens del resumen (salida).
- →La diferencia entre los dos es mayor que 10× (recuerda: la regla del researcher es «≤10% de lo que leyó»).
- →Puedes decir en qué % de la ventana quedaría el maestro, y si eso te preocupa o no.
Bono: si la tarea no requería suficiente lectura como para justificar un subagente, la respuesta correcta es "¿no valdría la pena delegar?" — y eso también cuenta como un acierto.
Ejemplo resuelto
Tarea: "leer los registros del deploy de la semana" — 8 archivos × 600 líneas × 4 tok ≈ 19.200 tokens brutos si el maestro leyera. Resumen útil: 5 líneas de error + 2 líneas de conclusión ≈ 28 tokens con el researcher. Ahorro: 99,85%. El orquestador estaría en ~20% de la ventana con la lectura en bruto, algo ya preocupante para una sesión larga. Vale la pena delegar.
✅ Resumen del módulo
Próximo módulo:
1.3 — Agente × Subagente × Skill. Las tres primitivas, sus diferencias y cuándo elegir cada una.