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

URL: https://agentvera.dev/es/blog/context-engineering-for-ai-coding/ · Publicado: 2026-10-28

Ingeniería de contexto para agentes de programación con IA: qué llena el contexto, por qué se degrada y qué técnicas rinden más que retocar el prompt.

**En resumen:**

- La ingeniería de contexto consiste en elegir qué tokens ve un agente en cada turno: prompt de sistema, archivos de reglas, definiciones y resultados de herramientas, MCP, archivos leídos e historial.
- Los modelos pierden fiabilidad a medida que crece la entrada (context rot), así que un contexto pequeño y preciso suele rendir más que un prompt ingenioso en una sesión saturada.
- Las técnicas clave: archivos de reglas cortos y acotados, recuperación justo a tiempo, subagentes con ventana limpia, compactación, un mapa del código, archivos de notas y salidas breves.

**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](https://www.anthropic.com/engineering/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:

| | Ingeniería de prompts | Ingeniería de contexto |
| --- | --- | --- |
| Qué moldeas | La redacción de las instrucciones | Todo lo que hay en la ventana |
| Cuándo | Una vez, al escribir el prompt | En cada turno del bucle del agente |
| Palancas típicas | Redacción, ejemplos, formato | Archivos de reglas, recuperación, herramientas, compactación, subagentes, memoria |
| Fallo típico | Un prompt vago o frágil | Una ventana llena de tokens obsoletos, ruidosos o contradictorios |

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](/es/blog/claude-code-token-usage/ "Reduce el consumo de tokens de Claude Code un 61 %")). 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](/es/blog/claude-code-context-window/ "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](https://www.trychroma.com/research/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](https://code.claude.com/docs/en/memory) 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.

```markdown
---
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](/es/blog/claude-md-agents-md/ "Buenas prácticas de CLAUDE.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](https://www.anthropic.com/engineering/multi-agent-research-system) (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](https://claude.com/blog/context-management) 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:

```text
/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](/es/blog/shared-memory-for-ai-coding-agents/ "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/blog/codebase-map-for-ai-agents/ "Mapa del código para agentes de IA") 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](https://www.anthropic.com/engineering/writing-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

| Problema | Técnica |
| --- | --- |
| Se ignoran las reglas y el archivo no para de crecer | Archivo de reglas más corto, reglas por ruta, archivos anidados |
| El agente lee primero medio repo | Recuperación justo a tiempo, mapa del código |
| La investigación inunda la sesión principal | Subagente que devuelve un resumen |
| Sesión larga y calidad en descenso | Compactación dirigida o sesión nueva |
| Cada sesión nueva empieza de cero | Notas o un archivo de memoria compartida |
| Salidas enormes de tests y builds | Comandos acotados, salida filtrada o comprimida |

## 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](/es/features/token-savings/ "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](/es/features/project-map/ "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](/es/features/brain/ "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.

## Preguntas frecuentes

**¿Qué es la ingeniería de contexto?** Anthropic la define como seleccionar y mantener el mejor conjunto de tokens durante la inferencia. Para un agente de programación significa decidir qué entra en la ventana de contexto en cada turno: instrucciones, archivos de reglas, herramientas, código recuperado, resultados de herramientas e historial de la conversación.

**¿En qué se diferencia la ingeniería de contexto de la ingeniería de prompts?** La ingeniería de prompts se ocupa de redactar y ordenar un conjunto de instrucciones. La ingeniería de contexto abarca todo lo que entra en la ventana y se repite en cada turno del bucle del agente, así que es un trabajo continuo, no un borrador puntual.

**¿Qué es el context rot?** La pérdida de fiabilidad a medida que la entrada se alarga. El informe de Chroma de julio de 2025 probó 18 modelos y vio que el rendimiento cae con la longitud de la entrada, incluso en tareas sencillas. Una ventana grande no elimina el efecto.

**¿Una ventana de contexto de 1M tokens hace innecesaria la ingeniería de contexto?** No. Una ventana más grande da margen, pero cada token sigue compitiendo por la atención del modelo y se reenvía en los turnos siguientes. Las exploraciones antiguas y los intentos fallidos hacen la sesión más lenta, cara y ruidosa sea cual sea su tamaño.

**¿Cómo mido si mi ingeniería de contexto funciona?** Revisa el desglose del contexto (/context en Claude Code), los tokens por tarea, cuántas veces tienes que repetir una regla y con qué frecuencia una tarea sale bien al primer intento. Cambia una sola cosa cada vez y compara tareas parecidas.

---

**Sobre AgentVera.** AgentVera es una app de escritorio para macOS, Windows y Linux, desarrollada por Solviera Teknoloji. Ejecuta 18 agentes de programación con IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) en paralelo, por proyecto, en terminales reales con las instalaciones y sesiones de CLI del propio usuario. El plan gratuito tiene agentes ilimitados. Descargar: https://agentvera.dev/es/download/ · Precios: https://agentvera.dev/es/pricing/