📝 Qué es el contexto
O contexto es todo lo que el modelo sabe en ese momento: tu mensaje, la conversación anterior, los archivos que leyó el agente y los resultados de las herramientas. Es la "memoria de trabajo" activa de la sesión — y tiene un límite.
📝 Qué entra en el contexto
- •System prompt: instrucciones internas de Claude Code (~2K tokens, fijo)
- •CLAUDE.md: tus instrucciones personalizadas del proyecto (tú tienes el control)
- •Historial: toda la conversación desde el inicio de la sesión
- •Resultados de herramientas: contenido de cada archivo leído, salida de cada Bash
🔢 Qué son los tokens
Tokens son la unidad mínima de texto que procesan los modelos de lenguaje. No son exactamente palabras ni letras: son fragmentos de texto que el tokenizer divide según la frecuencia en el idioma.
📊 Referencia de tokens
- 1 palabra en inglés ≈ 1.3 tokens
- 1 palabra en pt-BR ≈ 1.5-2 tokens
- 100 líneas de código ≈ 800-1.200 tokens
- 1 página A4 de texto ≈ 500-700 tokens
- archivo de 1KB ≈ 250-400 tokens
- archivo de 10KB ≈ 2.500-4.000 tokens
- archivo de 100KB ≈ 25.000-40.000 tokens
- CLAUDE.md típico ≈ 500-2.000 tokens
✓ Token eficiente
- ✓Código en inglés/símbolos
- ✓Textos concisos y directos
- ✓Código sin comentarios largos
- ✓JSON sin espacios adicionales
✗ Consume muchos tokens
- ✗Copiar archivos enteros en el mensaje
- ✗Textos en idiomas con palabras largas
- ✗Repetir el mismo contenido varias veces
- ✗Respuestas verbosas del agente
🪟 Ventana de contexto
A ventana de contexto es el límite máximo de tokens que el modelo puede procesar de una sola vez. Es como la RAM de la computadora: rápida, pero finita. Claude 3 Sonnet tiene 200K tokens.
🪟 200.000 tokens en perspectiva
Parece mucho. Y lo es, pero se llena rápido en sesiones largas con mucha lectura de código.
- •≈ 500 páginas de texto denso
- •≈ 20.000 líneas de código
- •≈ 40-60 archivos de código de tamaño medio
Con una sesión larga, puedes consumir esto en:
- ⚠️1 archivo de 500KB leído = 125K tokens
- ⚠️10 archivos de 50KB = lo mismo
- ⚠️Sesión de 2h con mucho debugging = llena
💡 Consejo: cuando el contexto está lleno
Síntomas de una ventana casi llena: el agente empieza a «olvidar» instrucciones del inicio, hace cosas que ya dijiste que no hiciera o las respuestas se vuelven más genéricas. Usa /compact o /clear.
📈 Por qué se llena el contexto
La ventana no se llena al azar. Hay culpables comunes que consumen tokens de forma desproporcionada — e identificarlos permite actuar antes de perder contexto crítico.
Archivos grandes leídos completos
Un archivo de 500KB consume ~125K tokens, más de la mitad de la ventana. Si no hay instrucciones específicas, el agente lee más de lo que necesita.
Historial de conversación largo
Cada mensaje permanece en el contexto. Una sesión de 2h con muchos intercambios acumula fácilmente 30-50K tokens solo en el historial.
Muchas llamadas a herramientas con salidas largas
Cada Bash(npm install) con output largo va directamente al contexto. Los logs de 10K líneas son comunes.
Respuestas verbosas del agente
¿El agente explica cada paso en detalle? Eso también llena el contexto. Configura en CLAUDE.md: "sé conciso en las respuestas".
🗜️ Compactación del contexto
Claude Code tiene mecanismos para manejar contextos llenos: el comando /compact (manual) y la compactación automática que ocurre cuando la ventana está casi llena.
✓ /compact — cuándo usarlo
- ✓Después de completar una feature
- ✓Cuando el historial se hizo muy largo
- ✓Antes de iniciar una nueva subtarea
- ✓Cuando notes una degradación de la calidad
✗ Cuidado con /compact
- ✗Es posible que se pierdan detalles de errores anteriores
- ✗No lo uses en medio de una tarea crítica
- ✗El resumen puede perder matices importantes
- ✗Es mejor mantener algunos contextos íntegros
⌨️ Comandos para gestionar el contexto
💡 Buenas prácticas de contexto
Gestionar bien el contexto es una de las habilidades que más diferencia a los usuarios avanzados de los principiantes. Algunas reglas simples tienen un gran impacto en la calidad y costo de las sesiones.
📋 Las 5 reglas de oro del contexto
- 1.Sesiones cortas y enfocadas: una sesión por feature/bug, no por día
- 2.CLAUDE.md para contexto fijo: stack, reglas de código, convenciones del proyecto
- 3.No pegues código en los mensajes: di "edita el archivo X" en lugar de copiar el contenido
- 4./compact proactivo: úsalo antes de empezar una nueva tarea, no cuando la ventana ya está llena
- 5.Pide concisión: incluye en el CLAUDE.md "sé directo y conciso en las respuestas"
💡 El CLAUDE.md perfecto para ahorrar contexto
Un buen CLAUDE.md tiene 3 secciones: (1) Contexto del proyecto — tecnologías, estructura, arquitectura; (2) Reglas de código — estilo, convenciones, patrones; (3) Instrucciones de sesión — "sé conciso", "pregunta antes de crear archivos".
Esto elimina la necesidad de repetir el contexto en cada sesión y el agente empieza a trabajar de inmediato.
✅ Resumen del Módulo 1.3
Siguiente módulo:
1.4 — Terminal y CLI para principiantes: de cero a usar la terminal en 40 minutos, incluidos los comandos que Claude Code más usa.