Ingeniería de contexto para agentes de IA: guía práctica

La ingeniería de contexto es el trabajo de decidir qué ve un agente de programación con IA en cada turno: qué instrucciones, archivos de reglas, definiciones de herramientas, archivos recuperados, resultados de herramientas e historial hay en su ventana de contexto, y qué se queda fuera. En los agentes de programación suele importar más que retocar el prompt, porque el prompt que escribes es una pequeña parte de lo que lee el modelo. La mayor parte de la ventana la ocupan los archivos de reglas, la salida de las herramientas y la conversación hasta ese momento. Si mantienes ese contexto pequeño y relevante, obtienes mejores resultados que con cualquier reformulación del prompt.

Esta guía explica qué entra en el contexto de un agente, por qué los contextos largos se degradan, qué técnicas ayudan y cómo saber si funcionan. Los datos sobre Claude Code y Codex son de octubre de 2026.

Qué significa ingeniería de contexto

El artículo de ingeniería de Anthropic Effective context engineering for AI agents (29 de septiembre de 2025) define el contexto como el conjunto de tokens que se incluyen al generar con un modelo, y la ingeniería de contexto como seleccionar y mantener el mejor conjunto de esos tokens durante la inferencia.

La diferencia con la ingeniería de prompts está en el alcance y en el momento:

Un agente de programación trabaja en bucle: lee, llama a una herramienta, lee el resultado, decide y vuelve a llamar. Cada paso añade tokens y cada paso vuelve a leer lo que ya está ahí. Por eso el artículo dice que la ingeniería de contexto es iterativa: la selección se repite cada vez que el agente decide qué pasarle al modelo.

Qué entra en el contexto de un agente de programación

Antes de tu primer mensaje, y creciendo durante la sesión:

• Prompt de sistema y herramientas integradas. Lo fija la CLI. No lo controlas, pero lo pagas en cada turno.
• Archivos de reglas. CLAUDE.md para Claude Code, AGENTS.md para Codex y muchos otros agentes. Se cargan al inicio de la sesión.
• Definiciones de herramientas y MCP. Cada herramienta que el agente puede llamar tiene nombre y descripción, y los servidores MCP añaden más. Claude Code aplaza las definiciones completas de las herramientas MCP hasta que se usan, así que al principio solo se cargan los nombres y las instrucciones del servidor.
• Contenido recuperado. Archivos que lee el agente, resultados de búsqueda, documentación que consulta.
• Resultados de herramientas. Ejecuciones de tests, logs de build, git diff, consultas a bases de datos, capturas de páginas.
• Historial de la conversación. Tus mensajes, las respuestas del agente y cada intento fallido.

Para hacerte una idea de la parte fija: medimos la primera petición de Claude Code en unos 34,4k tokens con una configuración estándar y unos 13,3k con una ligera (lo contamos en nuestro artículo sobre el consumo de tokens). Esa base se reenvía en cada turno. Para los detalles de /context, /compact y /clear en Claude Code, consulta la guía de la ventana de contexto de Claude Code.

Por qué más contexto no es mejor: context rot

La ventana de contexto es un límite duro, pero el límite blando llega antes. El artículo de Anthropic habla de un «presupuesto de atención»: los transformers relacionan cada token con todos los demás, así que n tokens generan n² relaciones por pares y cada token extra reparte más la atención. A medida que crece la ventana, disminuye la capacidad del modelo para recordar lo que hay en ella.

La investigación independiente apunta a lo mismo. El informe Context Rot de Chroma (14 de julio de 2025) probó 18 modelos y vio que el rendimiento cae con la longitud de la entrada en todos sus experimentos, incluso en tareas sencillas. Algunos hallazgos que importan al programar:

• Un solo distractor, un texto que parece relevante pero no lo es, ya bajó la precisión, y el efecto creció con la longitud de la entrada.
• En un benchmark de memoria larga, todos los modelos rindieron mucho mejor con un prompt enfocado de unos 300 tokens que con el prompt completo de unos 113k tokens.

En un agente de programación los distractores están por todas partes: una versión antigua de un archivo leída antes de editarlo, el stack trace de un error ya corregido, un enfoque descartado. Una ventana de 1M tokens da margen, no inmunidad.

Técnicas que funcionan

Estas son las técnicas que describe el artículo de Anthropic, trasladadas a lo que haces con un agente de programación.

1. Archivos de reglas cortos y acotados

Los archivos de reglas se pagan en cada sesión, así que cada línea tiene que ganarse su sitio. La documentación de memoria de Claude Code recomienda mantener cada CLAUDE.md por debajo de 200 líneas y advierte que los archivos más largos reducen el cumplimiento de las reglas. En lugar de un único archivo largo:

• Pon las reglas que solo afectan a una parte del código en .claude/rules/ con un campo paths. Solo se cargan cuando Claude lee o edita un archivo que coincide.
• Usa archivos CLAUDE.md anidados en subcarpetas. Claude Code los carga bajo demanda cuando trabaja en esa carpeta.
• Ten en cuenta que los imports con @path ordenan un archivo pero no reducen su coste: los archivos importados se cargan junto con el que los importa.

---
paths:
  - "src/api/**/*.ts"
---

# Reglas de la API

- Valida el cuerpo de cada petición con el esquema compartido.
- Devuelve los errores en el formato de error estándar.

Codex funciona igual con AGENTS.md: lee un archivo global de ~/.codex y después un archivo por directorio desde la raíz del proyecto hasta el directorio de trabajo; los más cercanos van después y tienen prioridad. Deja de añadir archivos al llegar a project_doc_max_bytes, 32 KiB por defecto. Nuestra guía de CLAUDE.md y AGENTS.md explica qué poner en ellos.

Sobre el contenido, Anthropic aconseja escribir a la «altitud adecuada»: lo bastante concreto para guiar el comportamiento y lo bastante general para no fijar una lógica if-else frágil. Unos pocos ejemplos representativos funcionan mejor que una larga lista de casos límite.

2. Recuperación justo a tiempo

En lugar de cargarlo todo de entrada, guarda referencias ligeras (rutas de archivo, nombres de funciones, enlaces) y deja que el agente cargue el contenido cuando lo necesite. Anthropic pone como ejemplo a Claude Code: usa glob y grep para encontrar archivos y head y tail para mirar datos grandes sin cargarlos enteros. En la práctica:

• Señala al agente un archivo o un símbolo en vez de pedirle que «eche un vistazo».
• Pide un esquema o un rango de líneas antes de leer entero un archivo grande.
• Mantén un mapa breve del repo en el archivo de reglas (dónde está la API, dónde están los tests) y deja que el agente busque el resto.

3. Aislar el trabajo en subagentes

Un subagente trabaja en su propia ventana de contexto limpia. Puede gastar decenas de miles de tokens explorando y devolver solo un resumen condensado; Anthropic menciona resúmenes de a menudo 1.000 a 2.000 tokens. Buenos candidatos son explorar el código, leer logs largos y revisar el diff con un contexto nuevo.

Los subagentes no salen gratis. El artículo de Anthropic sobre su sistema de investigación multiagente (13 de junio de 2025) indica que los agentes usan unas 4 veces los tokens de un chat y los sistemas multiagente unas 15 veces. Lo que compras es un hilo principal limpio, no una factura más pequeña.

4. Compactar y limpiar resultados antiguos de herramientas

La compactación resume una conversación cercana a su límite y continúa a partir del resumen. Anthropic considera que borrar resultados antiguos de herramientas es una de las formas más seguras de compactar: el agente rara vez necesita la salida en bruto de un test de hace cuarenta turnos. En el lado de la API, el anuncio de gestión de contexto de Anthropic (29 de septiembre de 2025) informó de que la edición de contexto, que elimina llamadas y resultados de herramientas obsoletos, redujo el consumo de tokens un 84 % en una evaluación de búsqueda web de 100 turnos.

En una CLI de programación, dirige tú el resumen en lugar de dejar que ocurra al llegar al límite:

/compact Conserva la lista de archivos que cambiamos, el test que falla y la decisión sobre la API

Y cuando pases a un trabajo sin relación, abre una sesión nueva en lugar de compactar la anterior.

5. Darle al agente notas fuera de la ventana

Tomar notas estructuradas significa que el agente escribe su progreso en un archivo y lo vuelve a leer más tarde. Entre los ejemplos de Anthropic hay un archivo NOTES.md y listas de tareas. La memoria automática de Claude Code funciona así: un índice MEMORY.md por repositorio, del que se cargan las primeras 200 líneas o 25 KB al inicio de cada sesión. Para varios agentes y sesiones, una memoria compartida del proyecto va más allá; lo explicamos en memoria compartida para agentes de programación con IA.

6. Un mapa del código en vez de búsquedas a ciegas

Explorar a base de grep y lecturas llena la ventana de archivos completos, la mayoría de los cuales resultan irrelevantes. Un mapa del código es un índice de archivos, símbolos, imports y tests que el agente puede consultar: primero lee una lista ordenada y un esquema, y solo después las líneas que necesita.

7. Salidas de herramientas breves

Los resultados de las herramientas suelen ser la parte más grande y ruidosa de la ventana. El artículo de Anthropic Writing effective tools for agents (11 de septiembre de 2025) recomienda paginación, selección de rangos, filtrado y truncado con valores por defecto razonables, y señala que Claude Code limita por defecto las respuestas de las herramientas a 25.000 tokens. Puedes aplicar la misma idea desde fuera:

• Ejecuta un solo archivo de tests, no toda la suite.
• Filtra los logs con grep o tail antes de que el agente los lea.
• Prefiere un comando CLI concreto a una herramienta que devuelve una página o una tabla entera.
• Desactiva los servidores MCP que un proyecto no usa.

Medir la ingeniería de contexto

Sin medir, vuelves a ir a ciegas. Señales útiles:

• El desglose. /context en Claude Code muestra por categorías qué ocupa la ventana y qué archivos de reglas y de memoria se cargaron. Revísalo tras cambiar tus archivos de reglas o tu configuración de MCP.
• Tokens por tarea. Compara tareas parecidas antes y después de un cambio, no sesiones sueltas.
• Correcciones repetidas. Si no paras de repetir una regla, o falta en el archivo de reglas o está enterrada en él.
• Éxito al primer intento. Menos prompts de seguimiento en tareas comparables es el resultado que de verdad buscas.
• Señales de deterioro. Releer archivos, olvidar instrucciones anteriores, repetir un enfoque descartado. Cuando aparezcan, compacta o empieza de cero.

Cambia una sola variable cada vez. El artículo multiagente de Anthropic vio que el uso de tokens explicaba por sí solo cerca del 80 % de la variación de rendimiento en su evaluación BrowseComp, lo que recuerda que más tokens pueden parecer mejores resultados; compara coste y calidad a la vez.

Lista de comprobación

Dónde encaja AgentVera

AgentVera ejecuta Claude Code, Codex y otros agentes CLI en paralelo dentro de una aplicación de escritorio. No sustituye los hábitos anteriores, pero varias de sus funciones los aplican a cada agente que lanzas. Todo esto está descrito en las páginas de funciones:

• Ahorro de tokens: perfiles de contexto que reducen la base inicial, tamaño del contexto en directo en cada panel, autocompactación activada por defecto con un umbral de 150k tokens usando el propio comando de cada CLI, y RTK, que acorta la salida de tests, builds y git antes de que llegue al modelo.
• Mapa del proyecto: un índice local de símbolos, imports, tests y archivos que cambian juntos, que los agentes consultan con herramientas MCP de agentvera-map como map_related y map_outline. La pestaña AI ROI compara las conversaciones que usaron el mapa con las que no, incluidos los tokens por tarea.
• Brain: una memoria del proyecto construida a partir de documentación, commits, PR y conversaciones de agentes. Los agentes la consultan con brain_recall y guardan correcciones con brain_remember; un paquete de contexto opcional de hasta 2.500 caracteres se entrega a los agentes nuevos.
• Herramientas inteligentes para Claude Code: rechazan releer un archivo que no ha cambiado, entregan primero el esquema de un archivo grande y limitan las ejecuciones completas de tests a los tests afectados.

Si trabajas con un solo agente en una sola terminal, las técnicas de este artículo funcionan perfectamente por sí solas, y /context, /compact y un archivo de reglas bien cuidado te llevan casi hasta el final. AgentVera aporta más cuando ejecutas varios agentes y quieres aplicarles a todos la misma disciplina de contexto. Puedes descargarlo y probarlo en un proyecto.

Resumen

La ingeniería de contexto consiste en seleccionar lo que ve un agente en cada turno, y en los agentes de programación rinde más que retocar el prompt porque el prompt es solo una pequeña parte de la ventana. Los contextos largos son menos fiables, así que mantén los archivos de reglas cortos y acotados, recupera justo a tiempo, delega la exploración en subagentes, compacta con un foco, guarda notas fuera de la ventana, usa un mapa del código y mantén breves las salidas de las herramientas. Después mide: el desglose del contexto, los tokens por tarea y el éxito al primer intento te dicen si un cambio ha ayudado.