Ingeniería de contexto en Claude Code: por qué el modelo no es el cuello de botella
La ingeniería de contexto (context engineering) es la disciplina de curar deliberadamente la información que entra al modelo antes de que tome decisiones. No es prompt engineering: el prompt es solo una pieza, y a esta altura la menos crítica. Con los modelos actuales, lo que separa una sesión de Claude Code que funciona de una que frustra casi nunca es el modelo. Es qué información tenía enfrente antes de planificar.
Esta guía explica por qué esa es la habilidad que más mueve la aguja, y cómo empezar a aplicarla.
El cambio que casi nadie nombra
Hay una experiencia común. Ves a alguien en redes que resolvió en quince minutos un refactor que toca cuarenta archivos, o generó una feature entera con un prompt. Tú usas el mismo modelo, la misma CLI, prompts razonables, y los resultados no se parecen. La conclusión cómoda es "el modelo todavía no llegó" o "yo prompteo mal".
La conclusión cómoda esconde la realidad. Con la generación actual de modelos, ya razonan a través de problemas complicados y producen código de calidad cuando se les da el material adecuado. Lo que cambió es dónde está el cuello de botella: antes era el modelo, ahora es el contexto. La regla que lo resume: si el plan es bueno, el código va a ser bueno. Y la pregunta se desplaza a: ¿qué le impide al modelo producir un plan sólido? La respuesta empírica, casi siempre, es contexto faltante.
¿Por qué falla el contexto en Claude Code?
- El path de exploración. Cuando el agente explora el código por su cuenta, puede pasar al lado del archivo crítico sin abrirlo, sobre todo si los nombres no son obvios o vive en una carpeta que no parece relevante.
- Patrones confusos. Si el codebase tiene un framework no estándar o convenciones idiosincráticas sin documentar, el modelo no las reconoce y arma un plan que las viola.
- Restricciones no escritas. "No toques esta tabla, tiene un trigger sensible." "Este endpoint afecta a tres clientes que no podemos romper." Cosas que viven en la cabeza de un senior y en mensajes de Slack, no en el código. El modelo no las ve y planifica como si no existieran.
¿Por qué Claude Code es como un junior cada día?
Es la imagen que mejor captura el principio. A un junior recién llegado no le das "refactoriza el sistema de pagos para escalabilidad". Le das tareas pequeñas y explícitas: "hay un bug en el formateo de fechas, está en utils/dates.ts, este es el comportamiento esperado." No le das ambigüedad porque no tiene el contexto para resolverla.
Dos años después, ese mismo junior pasó por suficientes archivos, incidentes y conversaciones como para construir una representación interna del codebase. Ahora puede con tareas grandes y ambiguas, porque tiene contexto.
Tu Claude Code es un junior en su primer día, todos los días. Cada sesión arranca sin esa representación. La pregunta operativa de la ingeniería de contexto es: ¿cómo le entrego esa representación, en cantidad suficiente y bien curada, antes de que empiece a trabajar?
¿Cuáles son las reglas de la ingeniería de contexto?
La ingeniería de contexto no es un truco; es un conjunto de principios que se aplican en cada sesión. Estas son las seis reglas que más rinden:
| Regla | Qué significa |
|---|---|
| Signal to Noise | Maximiza la información útil; elimina el ruido antes de que entre al contexto. |
| Golden Window | El inicio de sesión es el momento de máxima precisión; úsalo para dar el objetivo y el material correcto. |
| Progressive Disclosure | Revela el contexto justo cuando la tarea lo necesita, no todo de entrada. |
| Goal In, Strategy Out | Da el objetivo; deja que el modelo proponga la estrategia. |
| Boxing the Agent In | Restringe el espacio de acción del agente para ganar precisión. |
| Long Context Failure | Un contexto saturado rinde peor que uno limpio; límpialo a tiempo (/clear entre tareas, /compact cuando una se alarga). |
Estas reglas no son independientes de las demás capacidades de Claude Code: son el hilo que las cose. Los subagentes existen para mantener el contexto principal limpio; las skills cargan sus referencias de forma progresiva. Todo el sistema es ingeniería de contexto aplicada.
¿Cómo empezar a aplicar la ingeniería de contexto?
No necesitas un comando nuevo. Necesitas cambiar la unidad de análisis: dejar de pensar "qué prompt escribo" y empezar a pensar "qué tiene el modelo enfrente antes de planificar". En concreto:
- Antes de pedir un plan grande, dale los archivos correctos en lugar de esperar que los encuentre solo.
- Escribe las restricciones no obvias en el
CLAUDE.mddel proyecto o en el propio prompt. - Limpia el contexto entre tareas no relacionadas, para que el ruido viejo no contamine la decisión nueva.
Dominar esto es lo que más distingue a quien obtiene resultados consistentes con Claude Code. El recorrido completo, con las capacidades que lo apoyan, está en la guía para dominar Claude Code.
Preguntas frecuentes
¿Qué es la ingeniería de contexto (context engineering)?
La ingeniería de contexto es la disciplina de curar deliberadamente la información que entra al modelo antes de que tome decisiones. No es prompt engineering: el prompt es solo una pieza. Con los modelos actuales, lo que determina la calidad de los resultados en Claude Code no es el modelo: es qué información tiene enfrente antes de planificar.
¿En qué se diferencia del prompt engineering?
El prompt engineering se centra en cómo formular la instrucción. La ingeniería de contexto se centra en qué información tiene el modelo disponible antes de procesar esa instrucción. Con la generación actual de modelos, el cuello de botella raramente es el prompt. Casi siempre es contexto faltante, ambiguo o ruidoso.
¿Por qué falla el contexto en Claude Code?
Por tres razones principales: el agente puede explorar el código y pasar por alto el archivo crítico (path de exploración); el codebase tiene convenciones no documentadas que el modelo no reconoce; o hay restricciones implícitas que viven en la cabeza del equipo, en mensajes de Slack, pero no están escritas en ningún archivo.
¿Cuáles son las reglas principales de la ingeniería de contexto?
Las seis que más rinden: Signal to Noise (maximiza información útil, minimiza ruido), Golden Window (el inicio de sesión es el momento de mayor precisión), Progressive Disclosure (revela contexto justo cuando se necesita), Goal In Strategy Out (da el objetivo, el modelo propone la estrategia), Boxing the Agent In (restringe el espacio de acción) y Long Context Failure (un contexto saturado rinde peor que uno limpio).
¿Cómo empezar a aplicar la ingeniería de contexto?
Tres pasos concretos sin comandos nuevos: antes de pedir un plan grande, dar al modelo los archivos correctos en lugar de esperar que los encuentre solo; escribir las restricciones no obvias en el CLAUDE.md del proyecto; y limpiar el contexto entre tareas no relacionadas con /clear para que el ruido viejo no contamine la siguiente decisión.
Recursos relacionados
- Guía completa para dominar Claude Code.
- Subagentes y skills, hooks y MCP: las capacidades que aplican estos principios.
Lleva las reglas contigo
Las diez reglas de oro de context y prompt engineering, más los comandos de contexto (/context, /clear, /compact), están en la Cheat Sheet de Claude Code: una hoja imprimible, en español.
Descargar la Cheat Sheet gratis
Es el resumen de Ship with Claude Code, la guía de Takren (14 módulos, 190 capítulos, actualizaciones gratuitas).