Context Engineering

Qué es Context Engineering

Context Engineering es la disciplina de gestionar qué información recibe el modelo y cómo se organiza esa información para obtener los mejores resultados posibles. A diferencia del prompt engineering, que se centra en la redacción de instrucciones, Context Engineering abarca un enfoque más amplio: incluye qué archivos se leen, qué herramientas se utilizan, cómo se estructura el trabajo y cuándo se libera contexto.

En Claude Code, la ventana de contexto de 200K tokens es el recurso más valioso de cada sesión. Cada archivo leído, cada comando ejecutado y cada respuesta generada consume parte de ese espacio. A medida que se llena, la calidad de las respuestas disminuye: el modelo pierde la capacidad de recordar instrucciones anteriores, comete más errores y produce resultados menos precisos.

Context Engineering no consiste en llenar la ventana de contexto con la mayor cantidad de información posible, sino en equilibrar dos objetivos: dar a Claude suficiente información relevante para resolver la tarea y dejar espacio libre suficiente para que razone con profundidad.

El flujo explorar, planificar, implementar

La estrategia más efectiva para tareas complejas consiste en separar el trabajo en tres fases y limpiar el contexto entre cada una. Este enfoque obliga a seleccionar cuidadosamente qué información pasa de una fase a la siguiente y garantiza que el modelo tenga espacio suficiente en cada etapa.

Fase 1: explorar

Se activa el modo Plan (con Shift+Tab o --permission-mode plan). Claude lee archivos y responde preguntas sin realizar modificaciones. El objetivo es recopilar el contexto necesario para planificar la implementación.

lee src/auth/ y entiende como gestionamos las sesiones y el login.
tambien revisa como manejamos las variables de entorno para secretos.

Durante esta fase, Claude puede leer múltiples archivos, explorar la estructura del proyecto y analizar patrones existentes. Toda esta información se acumula en el contexto.

Fase 2: planificar

Se pide a Claude que cree un plan de implementación basado en lo explorado. El plan sirve como puente entre la exploración y la implementación.

quiero anadir autenticacion con Google OAuth. que archivos hay que modificar?
cual es el flujo de sesion? crea un plan detallado.

El plan se puede abrir en un editor de texto con Ctrl+G para revisarlo y editarlo directamente antes de que Claude proceda.

Fase 3: implementar

Se ejecuta /clear para limpiar todo el contexto de exploración, y se pega el plan (o se carga desde un archivo) en una sesión limpia enfocada exclusivamente en la implementación.

implementa el flujo OAuth segun este plan: [plan]. escribe tests
para el callback handler, ejecuta los tests y corrige los fallos.

flowchart LR
    A["Explorar<br>(modo Plan)"] --> B["/clear"]
    B --> C["Planificar<br>(crear plan)"]
    C --> D["/clear"]
    D --> E["Implementar<br>(sesión limpia)"]

Este flujo de tres fases tiene una ventaja fundamental: la sesión de implementación arranca con un contexto limpio y enfocado, sin el ruido de las decenas de archivos leídos durante la exploración.

No todas las tareas necesitan tres fases. Si el cambio es sencillo y puedes describir el diff en una frase ("renombra esta variable", "añade un log aquí"), el plan sobra. Las tres fases aportan valor cuando el alcance es incierto, el cambio afecta a múltiples archivos o no conoces bien el código.

Proporcionar criterios de verificación

La práctica con mayor impacto en la calidad de los resultados es dar a Claude una forma de verificar su propio trabajo. Cuando Claude puede ejecutar tests, comparar capturas de pantalla o validar salidas, corrige errores por sí mismo en lugar de trasladar esa carga al usuario.

Algunas formas de proporcionar verificación:

• Tests existentes: pedir a Claude que ejecute la suite de tests después de implementar un cambio.

implementa la funcion validateEmail. ejecuta npm test despues
y corrige los fallos.

• Tests nuevos: pedir que escriba tests primero y luego implemente el código que los pasa.

escribe tests para el endpoint de login cubriendo el caso de sesion
expirada. despues implementa el codigo que los pase.

• Comandos de validación: indicar un comando cuya salida permite verificar que el cambio es correcto.

modifica el schema de la base de datos. ejecuta npm run typecheck
despues para verificar que no hay errores de tipos.

• Comparación visual: pegar una captura de pantalla del diseño esperado y pedir que compare el resultado.

implementa este diseno [captura]. toma una captura del resultado
y compara con la original. lista las diferencias y corrígelas.

Sin criterios de verificación, Claude produce resultados que parecen correctos pero pueden no serlo. Con verificación, Claude se convierte en su propio revisor de código, reduciendo drásticamente los ciclos de corrección.

Delegar con subagentes

Los subagentes ejecutan tareas en una ventana de contexto separada y devuelven un resumen al agente principal. Esto los convierte en una herramienta fundamental de Context Engineering: toda la exploración que realiza un subagente (archivos leídos, búsquedas ejecutadas, análisis de código) queda contenida en su propio contexto y no contamina el contexto principal.

usa subagentes para investigar como funciona el sistema de autenticacion
y si tenemos utilidades de OAuth existentes que pueda reutilizar.

El subagente puede leer decenas de archivos, pero al agente principal solo le llega un resumen conciso con los hallazgos. El contexto principal se mantiene limpio para la implementación.

Los subagentes también son útiles para verificación posterior: tras implementar un cambio, se puede pedir a un subagente que revise el código en busca de edge cases o problemas de seguridad, sin consumir el contexto principal.

usa un subagente para revisar el codigo que acabamos de escribir
y buscar posibles edge cases.

Prompts específicos y con alcance definido

La precisión del prompt tiene un impacto directo en cuánto contexto se consume. Un prompt vago obliga a Claude a explorar más archivos, ejecutar más búsquedas y generar respuestas más amplias. Un prompt específico reduce la exploración al mínimo necesario.

| Vago (más contexto) | Específico (menos contexto) | |---|---| | "arregla el bug de login" | "el login falla tras expirar la sesion. revisa el flujo de refresco de token en src/auth/, especialmente token-refresh.ts" | | "añade tests para foo.py" | "escribe un test para foo.py cubriendo el caso en que el usuario no está autenticado. evita mocks" | | "investiga la arquitectura" | "lee src/api/ y resume como se estructuran los handlers de la API" |

Referenciar archivos y datos

Claude Code permite proporcionar contexto de formas que ahorran tokens:

• Mención de archivos con @: escribir @src/auth/login.ts en el mensaje para que Claude lo lea directamente, sin necesidad de buscarlo.

• Piping de datos: canalizar la salida de un comando o el contenido de un archivo:

cat error.log | claude -p "analiza estos logs y sugiere la causa raíz"

• URLs de documentación: proporcionar enlaces a documentación oficial para que Claude los consulte, en lugar de explicar conceptos que ya están documentados.

• Imágenes: pegar o arrastrar imágenes al prompt para proporcionar contexto visual (capturas de pantalla, diagramas, mockups).

Gestionar sesiones de forma activa

El Context Engineering no se limita al contenido de un solo prompt: abarca la gestión activa de toda la sesión para mantener el contexto enfocado.

Limpiar entre tareas

Ejecutar /clear entre tareas no relacionadas elimina el contexto de la tarea anterior y garantiza que Claude empiece la siguiente con una ventana limpia. Acumular contexto de tareas distintas es una de las causas más frecuentes de degradación de calidad.

Corregir temprano

Si Claude va por un camino equivocado, corregirlo en el primer o segundo turno es mucho más efectivo que dejarlo avanzar y corregir después. Cada turno adicional por el camino equivocado añade ruido al contexto.

Si se ha corregido a Claude más de dos veces por el mismo error, el contexto está contaminado con intentos fallidos. En ese caso, /clear seguido de un prompt mejor (que incorpore lo aprendido) produce mejores resultados que seguir corrigiendo.

Compactar con instrucciones de enfoque

Cuando se acumula contexto útil pero extenso, /compact con instrucciones de enfoque permite resumir selectivamente:

/compact Conserva los cambios de la API y los resultados de los tests.
Descarta la exploracion inicial del proyecto.

Aprovechar CLAUDE.md como contexto persistente

Las instrucciones que deben estar disponibles en todas las sesiones pertenecen a CLAUDE.md, no a la conversación. CLAUDE.md se reinyecta tras cada compactación y se carga al inicio de cada sesión nueva, lo que lo convierte en el mecanismo más fiable para mantener contexto entre sesiones.

Context Engineering es una habilidad que se desarrolla con la práctica. Con el tiempo, se desarrolla la intuición de cuándo dar contexto detallado y cuándo ser conciso, cuándo limpiar el contexto y cuándo dejarlo acumularse, cuándo planificar y cuándo dejar que Claude explore.