Context engineering: qué entra en el contexto de tu agente y cómo mantenerlo ligero
El context engineering es decidir qué tiene delante el modelo en cada paso. Qué cargan Claude Code, Codex y OpenCode, cuánto cuesta un AGENTS.md grande y cómo mantener el contexto ligero, con datos de un experimento propio.
En este artículo · 14 secciones
- La versión corta
- Qué es el context engineering
- Context engineering frente a prompt engineering
- Qué entra en el contexto en cada paso
- ¿Por qué no meterlo todo? Lo que dicen los datos
- Cinco formas de mantener el contexto ligero
- El mismo encargo con un mapa, con todo dentro y sin AGENTS.md
- Cuándo un AGENTS.md grande no es un problema
- Cómo lo hacemos en DevExpert
- Por dónde empezar
- Lo que vemos en clase
- Errores comunes
- Preguntas frecuentes
- Fuentes
Antes de escribir este artículo quisimos medir algo que damos por hecho desde hace meses: que un AGENTS.md largo pesa. Preparamos ficheros de 50, 300, 1.000 y 2.500 líneas, con una marca de control cada 50 líneas, y preguntamos a Claude Code, Codex y OpenCode qué marcas veían.
Claude Code las vio todas. OpenCode, también. Codex se quedó en la línea 400: corta el fichero a los 32 KiB y no avisa. Si tus reglas importantes están al final de un AGENTS.md grande, Codex no las lee.
Casi nunca miramos estas cosas. Nos fijamos en el prompt, pero el modelo trabaja con mucho más: las instrucciones del proyecto, los ficheros que ha leído, la salida de cada comando y todo lo que lleva la sesión. A decidir qué entra ahí, y cuándo, se le llama context engineering.
En este artículo te contamos qué es, qué entra en el contexto de tu agente en cada paso, qué dicen los datos sobre meterlo todo y cinco formas de mantenerlo ligero. Lo acompañamos con medidas que hemos tomado en los tres agentes. Son pruebas pequeñas y con fecha, así que te contamos cómo las hemos hecho para que puedas repetirlas con tu versión.
La versión corta
- El context engineering es decidir qué tiene delante el modelo en cada paso: instrucciones, ficheros, salidas de herramientas e historial. El prompt es solo una parte.
- Antes de que escribas nada, el agente ya carga mucho. En nuestra prueba, Claude Code arranca con unos 37.700 tokens, casi todos de la definición de sus herramientas. Codex, con entre 15.000 y 18.000, y OpenCode 2.2.6, con unos 6.100.
- Todo lo que pones en el
AGENTS.mdviaja en cada petición. En Claude Code, 2.500 líneas son 78.600 tokens más. En Codex, a partir de 32 KiB el fichero se corta sin avisar. - Más contexto no da mejores resultados: la precisión de los modelos baja cuando crece la entrada y, cuantas más instrucciones reciben a la vez, menos cumplen.
- Un
AGENTS.mdque hace de mapa mantiene ligero lo que se carga siempre: lo que vale para cualquier tarea y dónde está lo demás. En Claude Code, una ruta con@carga el fichero al arrancar, y en nuestra prueba el contexto inicial subió un 48 %. - En sesiones largas, en la experiencia de Antonio, Claude Code y Codex compactan bien. Guarda el estado en el repositorio, abre una sesión nueva para cambiar de tarea o validar y usa subagentes para que las búsquedas pesadas no llenen el contexto principal.
- En nuestro experimento, con 41 KB de documentación, meterla toda en el
AGENTS.mdno empeoró el resultado de ningún agente. Cambió el coste: Codex gastó entre un 20 y un 72 % más de tokens que con un mapa, y Claude Code, casi lo mismo.
Qué es el context engineering
El context engineering (ingeniería de contexto) es diseñar qué información tiene delante el modelo en cada paso de su trabajo, en qué forma y en qué momento, para que resuelva la tarea con el menor ruido posible.
Antonio lo resumió en X como el arte de cargar exactamente el contexto que necesitas cuando lo necesitas. Anthropic lo plantea casi igual en su guía: buscar el conjunto más pequeño de tokens que más información aporte.
En un chat, el contexto es la conversación. En un agente, se construye en bucle: el modelo pide leer un fichero, la herramienta devuelve su contenido y ese contenido entra en el contexto. Luego ejecuta los tests y su salida también entra. Cada paso añade algo, y el modelo decide el siguiente con todo lo acumulado delante.
Por eso, en un agente de código, el context engineering es sobre todo diseñar el entorno en el que el agente va llenando su propia ventana: qué carga al empezar, qué encuentra cuando lo busca y qué se queda fuera.
De dónde sale el término
La expresión no es nueva. En enero de 2023, Charles Frye ya proponía en X pensar en context engineering en lugar de prompt engineering, y Riley Goodside la usaba esa misma semana, según Simon Willison.
Se generalizó en 2025, con los agentes. Dex Horthy la convirtió en uno de sus 12-factor agents en abril (“controla tu ventana de contexto”), y Walden Yan, de Cognition, escribió en junio que era el trabajo número uno de quien construye agentes, en Don’t Build Multi-Agents.
El empujón llegó con Tobi Lütke, CEO de Shopify. El 19 de junio de 2025 la definió en X como “the art of providing all the context for the task to be plausibly solvable” para el modelo. Seis días después, Andrej Karpathy le dio la razón: para él, en una aplicación seria se trata de llenar la ventana con justo la información que hace falta para el siguiente paso. Ninguno de los dos dice haber inventado el término.
En pocas semanas escribieron sobre él Simon Willison, Lance Martin en LangChain, Drew Breunig, que clasificó cómo falla el contexto, y Manus, que contó lo que aprendió construyendo su agente. Anthropic publicó su guía el 29 de septiembre de 2025. Thoughtworks la recomienda adoptar desde abril de 2026, y Birgitta Böckeler explicó en la web de Martin Fowler cómo se aplica a los agentes de código.
Context rot, el deterioro del rendimiento cuando el contexto crece, también es de junio de 2025. Lo propuso un usuario de Hacker News y lo recogió Simon Willison. Un mes después, Chroma lo midió con 18 modelos.
Context engineering frente a prompt engineering
El prompt engineering trabaja una petición: cómo pides algo para que la respuesta sea buena. El context engineering trabaja todo lo que el modelo tiene delante cuando responde. En un agente eso incluye tu petición, pero también las instrucciones del proyecto, los ficheros, las salidas de las herramientas y el historial. El harness engineering va un paso más allá: incluye lo que actúa aunque el modelo no lo lea, como un hook, un permiso o un test.
nivel 1
Prompt engineering
- Pregunta
- ¿Cómo se lo pido?
- Qué diseñas
- El mensaje
- Cuánto dura
- Una petición
- Ejemplo
- Rol, tarea, formato y ejemplos en el prompt
nivel 2 · incluye el 1
Context engineering
- Pregunta
- ¿Qué tiene que tener delante ahora?
- Qué diseñas
- Todo lo que entra en la ventana de contexto en cada paso
- Cuánto dura
- Una sesión
- Ejemplo
- AGENTS.md, documentación bajo demanda, resultados de herramientas
nivel 3 · incluye el 2
Harness engineering
- Pregunta
- ¿Cómo hago que salga bien una y otra vez?
- Qué diseñas
- El entorno completo en el que trabaja el agente
- Cuánto dura
- La vida del proyecto
- Ejemplo
- Specs, skills, permisos, gates, validación y memoria entre sesiones
El RAG o la memoria son técnicas de context engineering: formas de decidir qué entra en la ventana. Dónde acaba el contexto y dónde empieza el arnés depende de a quién leas, y lo contamos con más detalle en el artículo de harness engineering.
Para saber si algo es contexto, pregúntate si el modelo lo va a leer. Si lo lee, compite por su atención con todo lo demás.
Qué entra en el contexto en cada paso
Cuando abres una sesión y escribes tu primera petición, el modelo recibe mucho más que tu mensaje:
- Las instrucciones de la herramienta: el system prompt de Claude Code, Codex u OpenCode, con su forma de trabajar.
- La definición de cada herramienta: leer ficheros, editar, ejecutar comandos o buscar, cada una con su descripción y sus parámetros.
- Tus instrucciones: el
AGENTS.mdoCLAUDE.mdglobal y el del proyecto. - Lo que tengas conectado: la descripción de cada skill y las herramientas de cada servidor MCP. En Claude Code, Codex y OpenCode 2, de cada servidor solo va una referencia corta, y el esquema de una herramienta entra cuando el modelo la busca.
- El entorno: la carpeta de trabajo, la fecha y, a veces, el estado de git.
- Tu mensaje: lo único que has escrito tú en esta sesión.
A partir de ahí, en cada paso, se suma lo que el agente lee, lo que le devuelven las herramientas y lo que él mismo escribe.
Al empezar
Fijo: viaja en cada petición
- Instrucciones de la herramientael system prompt del agente
- Definición de las herramientasleer, editar, ejecutar, buscar
- AGENTS.md o CLAUDE.mdel global y el del proyecto
- Skills y MCP conectadosnombres y descripciones
- Entornocarpeta, fecha y estado de git
En cada paso
Crece con cada paso
- Tus mensajesla petición y lo que añades
- Ficheros que leeenteros o por trozos
- Salidas de los comandostests, builds, búsquedas, logs
- Lo que escribe el agenterespuestas, razonamiento y diffs
- Resúmenescuando compacta
Solo si lo busca
Bajo demanda: entra si el agente lo busca
- Documentos enlazadosdocs/ que el mapa señala
- Cuerpo de las skillscuando decide usar una
- Esquema de cada tool MCPcuando la busca, en los agentes al día
- AGENTS.md de subcarpetasen Claude Code, al leer ahí
- Resultado de un subagentesolo su resumen
Quisimos ver cuánto ocupa cada parte. Repetimos la prueba del artículo sobre cómo carga Claude Code los ficheros, esta vez con los tres agentes, sin configuración personal y con AGENTS.md de distintos tamaños, y medimos los tokens de la primera petición cuando solo le pedimos que responda “OK”.
Claude Code 2.1.319 · Opus 5.5
- Sin AGENTS.md37.657
- 50 líneas · 3,7 KB39.360
- 300 líneas · 23 KB47.162
- 1.000 líneas · 79 KB69.206
- 2.500 líneas · 197 KB116.244
Codex 0.167.0 · gpt-6.1-sol
- Sin AGENTS.md15.431
- 50 líneas · 3,7 KB18.772
- 300 líneas · 23 KB23.369
- 1.000 líneas · 79 KB · cortado a 32 KiB25.575
- 2.500 líneas · 197 KB · cortado a 32 KiB23.167
OpenCode 2.2.6 · Qwen 3.8 27B
- Sin AGENTS.md6.104
- 50 líneas · 3,7 KB7.052
- 300 líneas · 23 KB12.006
- 1.000 líneas · 79 KB25.825
- 2.500 líneas · 197 KB55.501
Salen tres cosas:
- Lo fijo ya es mucho: sin ningún
AGENTS.md, Claude Code con Opus 5.5 arranca con 37.657 tokens. Sin herramientas serían unos 3.400, así que el resto es la definición de sus 27 herramientas. Codex arranca con entre 15.400 y 17.900, según la ejecución, porque carga de serie algunos plugins de OpenAI. OpenCode 2.2.6, con 6.104. - Cada línea de tu AGENTS.md se paga en cada petición: en Claude Code, unos 31 tokens por línea. 300 líneas son 9.500 tokens más, y 2.500 líneas, 78.600.
- Codex pone un tope: a partir de 32 KiB, el fichero se corta. Lo verás más abajo, en el apartado del mapa.
Los números no se comparan entre agentes, porque cada modelo usa su propio tokenizador. Sí se puede comparar cómo crece cada uno con el tamaño del fichero.
Para verlo en tu caso: en Claude Code, /context te enseña cómo se reparte la ventana. En Codex, la línea de estado puede mostrar el contexto que queda. Y opencode stats te da los tokens y el coste de tus sesiones.
¿Por qué no meterlo todo? Lo que dicen los datos
Con ventanas de un millón de tokens, la tentación es meterlo todo y que el modelo se apañe. El problema es que los modelos rinden peor cuando la entrada crece.
GPT-3.5 Turbo · aciertos con 20 documentos en el contexto
- La respuesta está en el primer documento75,8 %
- La respuesta está en el décimo53,8 %
- Sin ningún documento56,1 %
El estudio más citado es Lost in the Middle, de 2023. Es un modelo antiguo, pero el patrón se ha repetido después:
- NoLiMa (febrero de 2025): cuando la pregunta y la respuesta no comparten palabras, con 32.000 tokens de contexto 11 de 13 modelos se quedan por debajo de la mitad de su rendimiento con textos cortos.
- Chroma (julio de 2025): en 18 modelos, el rendimiento baja a medida que crece la entrada, incluso en tareas sencillas. En su prueba con conversaciones largas, todos aciertan más con una versión enfocada de unos 300 tokens que con el historial completo de unos 113.000.
- IFScale (julio de 2025): con 500 instrucciones a la vez, el mejor modelo cumple en torno al 68 %, y las primeras de la lista se respetan más que las últimas.
Con ficheros de instrucciones para agentes de código, la referencia es el estudio de ETH Zúrich, en su versión de septiembre de 2026. Los AGENTS.md generados con un LLM no mejoraron la tasa de éxito y encarecieron cada tarea entre un 20 y un 23 %. Los que escribieron los propios desarrolladores la subieron 2,4 puntos, una diferencia que no llega a ser significativa, con hasta un 19 % más de coste.
También hay datos en sentido contrario:
- Un buen índice ayuda: en las evals de Vercel, meter en el
AGENTS.mdun índice de 8 KB de su documentación llevó al agente al 100 %, frente al 53 % sin documentación. - Más contexto suma si es bueno: ACE mejora un 10,6 % con guías que crecen con la experiencia del agente, y critica la manía de resumirlo todo.
El problema está en lo que no aporta, más que en el tamaño. Un contexto largo y relevante funciona. Uno largo y con ruido distrae al modelo, cuesta más y, en Codex, puede que ni siquiera llegue entero.
Cinco formas de mantener el contexto ligero
Lance Martin lo resume en cuatro verbos: escribir fuera de la ventana, seleccionar lo que entra, comprimir lo que ya está y aislar lo que estorba. En un agente de código, lo aplicamos de cinco formas.
1. Un AGENTS.md que hace de mapa
El AGENTS.md es lo único que el agente lee siempre, así que es donde más cuesta cada línea. Lo usamos como mapa: qué es el proyecto, cómo se comprueba, dónde está cada cosa, qué leer antes de cada tipo de tarea y las pocas reglas que valen para cualquier tarea. El detalle va en otros ficheros.
- AGENTS.md# 37 líneas: qué es, cómo se comprueba, qué leer y reglas para todo
- CONTEXT.md# glosario
- docs/
- dominio.md# reglas de negocio
- api.md# convenciones y endpoints
- arquitectura.md
- testing.md
- convenciones.md, decisiones.md…
- AGENTS.md# 674 líneas: el mapa y toda la documentación pegada
- ├ glosario
- ├ reglas de negocio
- ├ convenciones y endpoints
- ├ arquitectura y testing
- └ convenciones, decisiones…
se carga siempre se lee cuando hace falta
Así es una parte del mapa que usamos en el experimento:
## Qué leer antes de cada tipo de tarea
- Reglas de negocio (reservas, cancelaciones, bloqueos y pistas cerradas): `docs/dominio.md`.
- Endpoints nuevos o cambios en la API: `docs/api.md`, con las convenciones y el orden de las comprobaciones.
- Tests, ayudantes y datos de la semilla: `docs/testing.md`.
## Reglas para cualquier tarea
- Usa el glosario: franja (nunca turno), socio (nunca usuario) y gestor (nunca admin).
- El dominio y los servicios no llaman a `new Date()` ni a `Date.now()`: usan `reloj.ahora()`.
- No cambies tests existentes para que pasen: arregla el código.
Sobre el tamaño, seguimos con las cifras del artículo de harness: entre 30 y 50 líneas para empezar y, hacia las 150, empieza a ser demasiado grande. Como referencia, en una muestra de 738 repositorios públicos con más de mil estrellas que medimos en noviembre, la mitad de los AGENTS.md y CLAUDE.md tiene menos de 111 líneas, y más de uno de cada cuatro pasa de 200.
Al medirlo salieron tres detalles.
Codex corta a los 32 KiB. El límite es para toda la cadena de ficheros que carga (el global y los de cada carpeta), no para cada uno. Se puede subir con project_doc_max_bytes en su configuración, pero con las cifras de arriba no deberías acercarte: 32 KiB son entre 400 y 500 líneas de texto, según lo largas que sean. En el repositorio de Codex se fusionó el 4 de noviembre un cambio que avisará del recorte, pero en la versión que probamos, la 0.167.0, no apareció ningún aviso.
AGENTS.md · 1.000 líneas · 78.604 bytes
Lo que llega al modelo: 32.768 bytes, hasta la línea 416. Ve 8 de las 20 marcas.
Lo que se pierde: 45.836 bytes, el 58 % del fichero.
Para ver qué pasa con el tuyo, pégalo aquí. Si también tienes un AGENTS.md global, pon su tamaño: Codex lo cuenta dentro del mismo límite.
Ejemplo de la prueba · 1.000 líneas · 78.604 bytes
- Claude Code, en cada petición
- +31.442 tokens
- OpenCode 2.2.6, en cada petición
- +19.730 tokens
Lo que lee Codex 0.167.0, con el límite de 32 KiB
Llega hasta la línea 416 y se pierde el 58 % del fichero, sin aviso.
1.000 líneas. Pasa de las 150, donde empieza a ser demasiado grande. La mitad de los que medimos tiene menos de 111.
Con @, Claude Code lo carga todo al arrancar. En Claude Code, una ruta escrita como @docs/dominio.md es un import: el fichero entra en el contexto desde el principio. Escrita en texto plano, el agente la lee solo cuando le hace falta. Con el mismo mapa y la misma documentación, la diferencia fue de 18.654 tokens en cada petición, tanto con el @ en AGENTS.md como en CLAUDE.md.
Claude Code 2.1.319 · tokens de entrada de la primera petición
- Rutas en texto plano en AGENTS.md38.831
- Rutas con @ en AGENTS.md57.485
- Rutas con @ en CLAUDE.md57.484
Y una trampa que nos pilló al montar la prueba: si la ruta lleva un punto o una coma pegados (@docs/dominio.md.), el import falla y no avisa.
Un solo fichero para todas las herramientas. Codex y OpenCode leen AGENTS.md. Claude Code lo lee desde septiembre, pero solo si no hay un CLAUDE.md, como Antonio comprobó fichero a fichero. En nuestros repositorios solo hay AGENTS.md, sin CLAUDE.md, y en el global de Antonio CLAUDE.md es un enlace simbólico al AGENTS.md. Así no mantenemos dos ficheros que acaban diciendo cosas distintas. Un CLAUDE.md con la línea @AGENTS.md también carga el mapa una sola vez: entre una opción y otra hubo 142 tokens de diferencia.
2. Documentación y skills que se cargan cuando hacen falta
Lo que no vale para todas las tareas no debería estar siempre en el contexto. Hay tres formas de tenerlo a mano sin cargarlo:
- Documentos que el mapa enlaza:
docs/dominio.mdodocs/api.md, que el agente abre cuando la tarea lo pide. Para que funcione, el mapa tiene que decir cuándo leer cada uno, no solo que existen. - AGENTS.md en subcarpetas: Claude Code carga el de una subcarpeta cuando lee un fichero de esa carpeta. Codex, en cambio, carga al empezar todos los que hay desde la raíz del repositorio hasta la carpeta donde abres la sesión.
- Skills: el agente solo ve el nombre y la descripción de cada skill hasta que decide usarla. Entonces carga sus instrucciones y, si hace falta, sus referencias y scripts. Antonio contó más sobre ellas en este artículo.
Este reparto tiene un riesgo: que el agente no vaya a buscar lo que necesita. En el experimento de más abajo no pasó: los tres agentes leyeron las reglas de negocio en todas las ejecuciones que las necesitaban.
3. Herramientas que devuelven poco
En una sesión de trabajo, lo que más crece son las salidas de las herramientas. Un cat de un fichero grande, un test que imprime cuatrocientas líneas o un git log sin límite entran enteros en el contexto, y se quedan ahí en cada petición siguiente. En las ejecuciones de Claude Code del experimento, entre el 65 y el 87 % de lo que se fue acumulando en la sesión, medido en caracteres, fueron salidas de herramientas.
- Pide salidas cortas:
rgcon límites, tests que resumen al final ygit log --oneline -20. Si tienes un script de comprobación, que diga qué falla y no todo lo que pasa. - Revisa lo que tienes conectado: Claude Code, Codex y OpenCode 2 ya dejan en espera las definiciones de las herramientas MCP y cargan solo las que el modelo busca. Lo que sigue llenando la sesión es lo que esas herramientas devuelven, así que vale lo mismo que para los comandos: que respondan poco. Si tu agente o tu versión no las deja en espera, como OpenCode 1.x, cada servidor añade la definición de todas sus herramientas a cada petición, las uses o no.
Hace un año, Antonio midió una sesión vacía de Claude Code con el 60 % de la ventana ocupada antes de escribir nada, la mitad por los MCP, y empezó a pasarlos a CLI. Lo contó en este vídeo, con las cifras de entonces:
El coste de los MCP en tokens y cuándo compensan frente a una CLI o una skill lo veremos a fondo en el artículo sobre MCP.
4. Compactar o empezar de cero
Cuando la ventana se llena, el agente compacta: resume la conversación y sigue con el resumen. Claude Code lo hace cuando se acerca al límite (hacia los 967.000 tokens en los modelos de un millón) y Codex, al 90 % de la ventana. En Claude Code puedes adelantarlo con /compact o fijar otro umbral con --autocompact.
Compactar tiene un coste: el resumen decide qué se pierde, y no siempre acierta. Hay alternativas más baratas. JetBrains comparó en agentes de código resumir con un LLM frente a enmascarar las salidas antiguas, es decir, sustituir lo que devolvieron las herramientas hace muchos pasos por un aviso. Enmascarar costó la mitad con el mismo éxito, y resumir alargó las sesiones un 15 %. Anthropic vio algo parecido con su edición de contexto, que borra resultados antiguos de herramientas: un 29 % mejor en su evaluación interna, y un 39 % junto con una herramienta de memoria.
En la experiencia de Antonio, que es personal y no tiene por qué valer para todos, tanto Codex como Claude Code compactan muy bien, y rara vez ha notado que una sesión larga empeore los resultados. No abre una sesión nueva solo porque se llene el contexto.
| Si… | Haz esto | Por qué |
|---|---|---|
| Sigues con la misma tarea y lo leído aún sirve | Deja que compacte, o compacta tú antes de un cambio grande | No pierdes el trabajo de lectura que ya ha hecho |
| Cambias de tarea | Sesión nueva | Lo anterior ya solo es ruido |
| Vas a validar lo que ha hecho | Sesión nueva, con la spec y el diff | Que no herede las conclusiones de quien escribió el código |
| Hay que leer mucho para encontrar algo | Un subagente | Al contexto principal solo llega el resumen |
El estado lo guardamos en el repositorio, con un PROGRESS.md y commits pequeños, para que una sesión nueva sepa por dónde seguir. Y la validación siempre la hacemos en una sesión limpia, para que no herede las conclusiones de la que escribió el código.
5. Subagentes para aislar el contexto
Un subagente trabaja con su propia ventana y devuelve solo un resumen. Si hay que buscar en todo el código, leer cuarenta ficheros o revisar un log enorme, el subagente se queda con ese ruido y al contexto principal llega lo que importa: entre 1.000 y 2.000 tokens, según Anthropic.
Pero tienen un coste. El sistema multiagente de investigación de Anthropic superó en un 90,2 % al de un solo agente, gastando unas 15 veces los tokens de un chat. Cognition desaconseja repartir una tarea entre agentes que no comparten contexto, porque toman decisiones que chocan. Y Google vio que ganan en tareas que se pueden paralelizar y pierden entre un 39 y un 70 % en las secuenciales.
Los usamos para tres cosas: investigar en paralelo cosas independientes, aislar un contexto muy pesado y revisar con criterios concretos. Como cadena fija de especialistas que se pasan el trabajo, casi nunca. Si trabajas con varios agentes de Codex a la vez, en este artículo Antonio enseña cómo organiza los suyos, cada uno con su AGENTS.md.
El mismo encargo con un mapa, con todo dentro y sin AGENTS.md
Las cinco formas suenan bien, pero queríamos comprobar la primera con un encargo real: ¿compensa un mapa frente a meterlo todo en el AGENTS.md?
Cómo lo hemos medido
Montamos una API de reservas de pádel en TypeScript, a partir del ejemplo público del Harness Starter: unas 1.200 líneas de código, 62 tests y 637 líneas de documentación. Le pedimos tres encargos:
- Cancelar reservas: con la política del club, que está en la documentación (plazo de 24 horas, quién puede cancelar y en qué orden se comprueba cada cosa).
- Arreglar un fallo: la semana sale con ocho días, y un test lo demuestra. No necesita la documentación.
- Bloquear pistas: un endpoint para el gestor que tiene que seguir las convenciones de la API, la auditoría y los avisos a los socios.
Cada encargo, con tres versiones del proyecto:
- Mapa: un
AGENTS.mdde 37 líneas que apunta a los documentos. - Todo dentro: un
AGENTS.mdde 674 líneas (41 KB) con el mapa y toda la documentación pegada. Lleva la misma información que el mapa, y los documentos ya no están aparte. - Sin AGENTS.md: solo los documentos, en Claude Code.
Lo ejecutamos tres veces por combinación en Claude Code (Opus 5.5), Codex (gpt-6.1-sol) y OpenCode 2.2.6 con Qwen 3.8 27B, un modelo menos potente. Cada agente corrió sin configuración personal, en una copia limpia del proyecto. El resultado lo deciden tests ocultos que el agente no ve: 14 para la cancelación, 4 para el fallo y 18 para los bloqueos. En Codex subimos el límite a 64 KiB para que el fichero llegara entero.
Lo que salió
Las 63 ejecuciones pasaron todos los tests ocultos y el gate. Con 41 KB de documentación, ningún agente acertó más o menos por tenerla en un mapa, dentro del AGENTS.md o sin AGENTS.md. Ni siquiera con Qwen 3.8 27B, el modelo menos potente, hubo diferencias.
Claude Code · Opus 5.5
Cancelar reservas
- Mapa: 1,02 M · 1,03 $ · 2 min 36 s
- Todo dentro: 1,01 M (−1 %) · 1,02 $ · 2 min 16 s
- Sin AGENTS.md: 1,06 M (+3 %) · 1,06 $ · 2 min 21 s
Arreglar el fallo
- Mapa: 0,23 M · 0,18 $ · 20 s
- Todo dentro: 0,18 M (−22 %) · 0,26 $ · 15 s
- Sin AGENTS.md: 0,18 M (−23 %) · 0,17 $ · 20 s
Bloquear pistas
- Mapa: 1,84 M · 1,59 $ · 4 min 6 s
- Todo dentro: 1,53 M (−17 %) · 1,61 $ · 4 min 19 s
- Sin AGENTS.md: 1,72 M (−6 %) · 1,75 $ · 4 min 1 s
Codex · gpt-6.1-sol
Cancelar reservas
- Mapa: 0,34 M · 2 min 15 s
- Todo dentro: 0,46 M (+36 %) · 2 min 25 s
Arreglar el fallo
- Mapa: 0,13 M · 24 s
- Todo dentro: 0,22 M (+72 %) · 25 s
Bloquear pistas
- Mapa: 0,38 M · 3 min 46 s
- Todo dentro: 0,46 M (+20 %) · 3 min 25 s
OpenCode 2.2.6 · Qwen 3.8 27B
Cancelar reservas
- Mapa: 1,71 M · 0,17 $ · 7 min 51 s
- Todo dentro: 1,95 M (+14 %) · 0,28 $ · 8 min 25 s
Arreglar el fallo
- Mapa: 0,06 M · 0,009 $ · 15 s
- Todo dentro: 0,11 M (+86 %) · 0,009 $ · 10 s
Bloquear pistas
- Mapa: 5,32 M · 0,71 $ · 7 min 40 s
- Todo dentro: 4,08 M (−23 %) · 0,56 $ · 14 min 21 s
La diferencia estuvo en el coste, y no siempre a favor del mapa:
- Codex gastó menos con el mapa en las tres tareas: con todo dentro procesó un 36 % más de tokens al cancelar reservas, un 72 % más al arreglar el fallo y un 20 % más al bloquear pistas.
- Claude Code no ahorró nada con el mapa: Opus 5.5 se leyó los diez documentos al empezar las dos tareas que los necesitaban, así que procesó tanto o más que con todo dentro, y costó lo mismo. Solo en la tarea corta, arreglar el fallo, meterlo todo dentro salió un 46 % más caro (0,26 $ frente a 0,18 $), por escribir en caché un fichero que no hacía falta. Sin
AGENTS.md, encontró los documentos por su cuenta y acertó igual. - OpenCode, según la tarea: al cancelar reservas, todo dentro procesó un 14 % más de tokens y costó un 62 % más. Al arreglar el fallo procesó un 86 % más, aunque se quedó en menos de un céntimo en los dos casos. Al bloquear pistas, la más larga, fue al revés: con el mapa procesó un 30 % más y costó un 26 % más, aunque todo dentro tardó casi el doble. Entre una ejecución y otra varió mucho (con el mapa, bloquear pistas costó entre 0,16 y 0,81 $), así que en OpenCode no vemos una tendencia clara.
Los tres agentes leyeron casi toda la documentación, aunque el mapa decía qué leer para cada tipo de tarea. Codex se leyó siete documentos incluso para arreglar el fallo de la semana, que no necesitaba ninguno.
MapaTodo dentroSin AGENTS.md
Claude Code · Opus 5.5 · tokens de entrada en cada petición
Codex · gpt-6.1-sol · tokens de entrada en cada petición
Con el mapa, el contexto arranca más ligero, pero en cuanto el agente lee la documentación alcanza al de todo dentro. Al terminar la tarea, la diferencia es pequeña. El ahorro está en los primeros pasos, y por eso se nota más en las tareas cortas.
Sacamos tres conclusiones:
- Con documentación pequeña y un modelo frontera, meterla dentro no rompe nada: te cuesta más o menos lo mismo en Claude Code y algo más en Codex.
- El mapa compensa cuando la documentación crece: este
AGENTS.mdde 41 KB se habría cortado en Codex con su configuración por defecto, y cada petición arrastra lo que lleve dentro. - No esperes que un mapa haga leer menos a un agente frontera: Claude Code y Codex leyeron casi todo de todas formas.
Es una prueba pequeña: un repositorio, tres encargos y tres repeticiones, con una documentación que cabe en 41 KB. No es un benchmark, y los tokens no se comparan entre agentes porque cada modelo usa su propio tokenizador. Los scripts, los encargos, los tests ocultos y los resultados de cada ejecución están en este repositorio, por si quieres repetirlo con tu versión.
Cuándo un AGENTS.md grande no es un problema
Hay casos en los que un contexto grande no estorba:
- Si casi todo vale para casi todas las tareas: el índice de Vercel funcionaba porque el agente lo necesitaba en cada prueba.
- Si la caché lo abarata: lo que se repite al principio de cada petición se cobra mucho más barato. Opus 5.5 cuesta 4 dólares por millón de tokens de entrada, y 0,20 si están en caché. Por eso lo fijo va primero y no debería cambiar a mitad de sesión. Manus llama a la tasa de acierto de la caché “la métrica más importante” de un agente en producción.
- Si la documentación es pequeña: en nuestra prueba, con 41 KB dentro, los tres agentes acertaron igual que con el mapa, y en Claude Code costó lo mismo.
La caché no arregla la atención: los tokens siguen ahí y compiten con lo que importa. Y en Codex, por encima de 32 KiB, el fichero no llega entero.
Hay un motivo más para revisar el contexto de vez en cuando: lo que hoy ayuda a un modelo puede estorbar al siguiente. Antonio lo contó en este vídeo:
Cómo lo hacemos en DevExpert
Todo esto lo aplicamos en nuestros propios repositorios. Estos son los AGENTS.md de los proyectos en los que más trabajamos, medidos hoy con wc:
| Proyecto | Qué es | AGENTS.md |
|---|---|---|
| Academia | La plataforma de formación: web, backend y apps de iOS y Android | 86 líneas (5,1 KB), más uno de 20 a 25 líneas en cada app |
| devexpert.io | Esta web | 92 líneas (8,3 KB) |
| PostFlow | Programador de publicaciones en redes, open source | 148 líneas (5,3 KB) |
| Proyecto de AI Expert | La tienda de ejemplo del programa | 83 líneas (3,5 KB) |
| Portal de FUNDAE | Gestión de la formación bonificada, en fase de especificación | 68 líneas (2,8 KB) |
| Pasarela de inferencia | El acceso a modelos que usamos en DevExpert | 66 líneas (1,6 KB) |
| Cuentas claras | Una CLI de ejemplo para repartir gastos | 65 líneas (3,5 KB) |
| Tablero | El panel de tareas y calendario de Antonio | 50 líneas (8,3 KB) |
| Vídeos de un curso | La producción de los vídeos, que se construyen desde el repo | 33 líneas (2,8 KB) |
| Humans in the Loop | La web del meetup | 30 líneas (1,5 KB) |
Ninguno pasa de 150 líneas ni de 9 KB, muy lejos de los 32 KiB de Codex. Solo la academia tiene AGENTS.md en subcarpetas, uno por app, porque cada una es casi un proyecto aparte.
El AGENTS.md de la academia, commit a commit
La academia es el proyecto más grande, con 1.599 commits desde junio. Su AGENTS.md nació el 25 de junio con 61 líneas, y en un mes llegó a 178: cada problema añadía una regla, desde los logs del servidor de desarrollo hasta los niveles de tests, la base de datos aislada para los tests de extremo a extremo o el presupuesto de contexto. El 7 de septiembre separamos la web y las apps nativas en un monorepo. El AGENTS.md raíz pasó a 165 líneas y cada app estrenó el suyo, de unas 18.
El 19 de septiembre lo dejamos en 83. La política de verificación pasó a docs/agent-verification.md, quitamos las reglas que estaban repetidas en otros documentos y retiramos el PROGRESS.md y el feature_list.json. Hoy tiene 86 líneas.
AGENTS.md raíz · líneas · jun–nov 2026
La parte que hace de mapa es la que dice qué leer según la tarea. Este es un extracto:
## Read only what the task needs
- Product/domain decisions: `CONTEXT.md`, `docs/product-brief.md`,
`docs/domain-model.md` and accepted `docs/adr/` entries.
- Permissions, enrollment, review or certificates: `docs/user-and-access-model.md`.
- Visual work: `DESIGN.md`; written tokens take priority over concept images.
- Integrations/auth/deployment: `docs/technical-discovery.md` and the relevant
operational runbook.
- Verification: `docs/agent-verification.md` is the single current policy.
Cada línea apunta a un documento y dice cuándo abrirlo. Los 303 documentos de docs/ se quedan fuera del contexto hasta que la tarea los pide.
En los proyectos pequeños, como Cuentas claras o el proyecto de AI Expert, seguimos usando un PROGRESS.md: es la forma más simple de que una sesión nueva sepa por dónde va. En la academia, con cientos de commits al mes, el historial de git ya cuenta lo que está hecho, y lo que queda a medias va en una sección corta del documento de ese tema. Cómo encaja el estado con el resto del arnés lo explicamos en la guía de harness engineering.
Por dónde empezar
- Mide lo que tienes: abre una sesión vacía y mira cuánto ocupa el contexto antes de escribir nada. En Claude Code, con
/context. - Convierte tu AGENTS.md en un mapa: deja lo que vale para todas las tareas y mueve el resto a documentos que el mapa enlaza, diciendo cuándo leer cada uno.
- Quita los
@que no hace falta cargar siempre y escribe esas rutas en texto plano. - Si usas Codex, comprueba el tamaño:
wc -c AGENTS.md, sumando los de las carpetas superiores. Por encima de 32 KiB, se corta. - Revisa los servidores MCP y las skills que tienes conectados: desconecta lo que no uses en ese proyecto.
- Guarda el estado en el repositorio, con un
PROGRESS.mdy commits pequeños, para poder abrir una sesión nueva sin perder el hilo. - Añade una línea cuando el agente falle dos veces en lo mismo: si nunca falla en algo, esa línea sobra.
Lo que vemos en clase
Esta parte la escribe Nino Ruano, que da prompt y context engineering en AI Expert.
Cuando llegamos al contexto en AI Expert, las dudas se repiten de una edición a otra. Estas son las que más salen en clase, con lo que respondo:
- “Si tengo muchos ficheros .md en el repo, ¿me gastan contexto?”: no. Un fichero que el agente no abre no ocupa nada, salvo que lo importes con
@en Claude Code. Lo que entra siempre es elAGENTS.md(o elCLAUDE.md), y de las skills solo el nombre y la descripción, hasta que el agente decide usar una. Un alumno lo tenía montado con un fichero por rol, planificador, implementador y revisor, y cada agente abría solo el suyo. Eso está bien hecho. - “¿Dejo que compacte o hago yo el resumen?”: otro alumno, cuando se acerca al límite en Codex, le pide que exporte el contexto a un markdown y se lo pasa a una conversación nueva. Es casi lo mismo que hace la compactación, con una ventaja: ese resumen lo puedes revisar y corregir antes de seguir. A mí la compactación automática me ha dado buen resultado. Además, tengo un hook que salta justo antes de compactar y le dice qué tiene que conservar, por ejemplo las decisiones de arquitectura. Afinarlo hasta que otro agente pueda seguir con ese resumen lleva bastante ensayo y error.
- “¿Pongo un AGENTS.md en cada módulo?”: solo si el proyecto es multimódulo de verdad, con módulos que casi son aplicaciones propias. Los ficheros se van sumando por el camino, así que más ficheros anidados es más contexto. Y el error que más veo es la contradicción: el de la raíz dice “arquitectura por capas” y el del módulo, “arquitectura hexagonal”. El agente recibe las dos. En un proyecto normal, con un
AGENTS.mdy unas cuantas skills basta. - “¿Sigo en la misma conversación?”: si cambia la tarea, no. Si acabas el login y en la misma conversación pides cambiar la lista, el agente arrastra todo el contexto del login, y la lista no lo necesita. Para mí, una conversación es una tarea.
Errores comunes
- El AGENTS.md como cajón de sastre: cada fallo añade una regla y nadie quita ninguna. En un estudio de 1.867 repositorios, el número de instrucciones de estos ficheros crecía de media un 226 % a lo largo de su vida, y casi nunca se podaban.
- Importar con
@lo que se puede leer bajo demanda: cada petición carga documentos que la tarea no necesita. - Pegar la documentación dentro del AGENTS.md para que no se le olvide: el agente la lee siempre, aunque no la necesite, y en Codex puede quedar fuera del límite.
- Dejar que las herramientas vuelquen salidas enteras: un test verboso o un log sin filtrar se quedan en el contexto el resto de la sesión.
- Compactar sin guardar antes el estado: si lo importante solo estaba en la conversación, el resumen decide si sobrevive.
- Generar el AGENTS.md con un comando y no revisarlo: en el estudio de ETH Zúrich, los generados no mejoraron el resultado y encarecieron cada tarea.
- Confiar en que el agente lo ha leído: si una regla importa y se puede comprobar, que la compruebe un test o un hook.
Preguntas frecuentes
¿Context engineering y prompt engineering son lo mismo?
No. El prompt engineering trabaja una petición. El context engineering trabaja todo lo que el modelo tiene delante en cada paso: instrucciones, ficheros, salidas de herramientas e historial. En un agente de código, el prompt es una parte pequeña del contexto.
¿Cuántas líneas debería tener un AGENTS.md?
Entre 30 y 50 es una buena referencia para empezar, y hacia las 150 toca partirlo en documentos. En los repositorios públicos, la mitad tiene menos de 111. Más que el número, importa que cada línea valga para casi todas las tareas.
¿Claude Code lee el AGENTS.md?
Sí, pero solo si no encuentra un CLAUDE.md en la carpeta de trabajo o en las superiores. Si usas varias herramientas, un enlace simbólico de CLAUDE.md a AGENTS.md te deja un solo fichero. Antonio lo probó caso a caso en este artículo.
¿Es mejor usar @ o escribir la ruta del fichero?
En Claude Code, @ importa el fichero al arrancar y la ruta en texto plano deja que el agente lo lea cuando le haga falta. En nuestra prueba, importar la documentación con @ subió el contexto inicial un 48 %. Usa @ solo para lo que el agente necesita en todas las tareas.
¿Una ventana de un millón de tokens hace innecesario el context engineering?
No. Cabe más, pero el modelo sigue rindiendo peor con contexto que no aporta, cada token se paga en cada petición y la compactación llega igual. Solo cambia el margen que tienes.
¿Cuándo compactar y cuándo empezar una sesión nueva?
En la experiencia de Antonio, Claude Code y Codex compactan bien y una sesión larga rara vez empeora el resultado, así que no hace falta empezar de cero solo porque se llene el contexto. Empieza una sesión nueva cuando cambias de tarea o vas a validar, con el estado guardado en el repositorio para que sepa por dónde seguir.
¿Los servidores MCP y las skills llenan el contexto?
Las skills, poco: hasta que se usan, solo cargan su nombre y su descripción. Los servidores MCP, también poco si tu agente está al día: Claude Code, Codex y OpenCode 2 dejan las definiciones en espera y cargan solo las que el modelo busca. En un agente que no lo hace, cada servidor añade la definición de todas sus herramientas a cada petición. En los dos casos, lo que más pesa es lo que devuelven las herramientas cuando se usan.
¿Dónde puedo aprender context engineering en español?
Para empezar, el Harness Starter es gratuito: una guía y cuatro skills que montan el mapa, el glosario y los documentos de tu proyecto. Si quieres trabajar el contexto y el resto del arnés sobre tu propio proyecto, con acompañamiento, eso es AI Expert. Y si es para un equipo entero, hay una formación para equipos en edición privada, adaptada a vuestro stack y bonificable por FUNDAE.
Fuentes
- Anthropic, Effective context engineering for AI agents, septiembre de 2025.
- Tobi Lütke, tuit sobre context engineering, y Andrej Karpathy, su respuesta, junio de 2025.
- Simon Willison, Context engineering y Context rot, junio de 2025.
- Lance Martin, Context engineering for agents, junio de 2025.
- Drew Breunig, How long contexts fail, junio de 2025.
- Manus, Context engineering for AI agents: lessons from building Manus, julio de 2025.
- Walden Yan (Cognition), Don’t build multi-agents, junio de 2025.
- Birgitta Böckeler, Context engineering for coding agents, febrero de 2026.
- Chroma, Context rot: how increasing input tokens impacts LLM performance, julio de 2025.
- Liu et al., Lost in the middle, 2023. NoLiMa, arXiv 2502.05167, febrero de 2025. IFScale, arXiv 2507.11538, julio de 2025.
- Gloaguen et al. (ETH Zúrich), Evaluating AGENTS.md, versión de septiembre de 2026.
- JetBrains, The complexity trap, agosto de 2025.
- Anthropic, How we built our multi-agent research system, junio de 2025.
- Google Research, Towards a science of scaling agent systems, 2025.
- Vercel, AGENTS.md outperforms skills in our agent evals.
- Zhang et al., Agentic context engineering (ACE), octubre de 2025.
- La documentación de Claude Code sobre la memoria y la de Codex sobre AGENTS.md.
