Context engineering: qué ve el agente y cuándo
Un agente solo sabe lo que tiene en su ventana de contexto en ese momento. Esta página explica cómo tratar esa ventana como un presupuesto, qué conviene cargar siempre, qué traer bajo demanda y qué guardar fuera, y cómo lo resuelve este repo.
La ventana es un presupuesto
El modelo no recuerda la conversación de ayer ni el archivo que leyó hace dos sesiones. Cada vez que responde, trabaja con un único bloque de texto: instrucciones del sistema, descripciones de herramientas, mensajes previos, resultados de comandos y archivos leídos. Ese bloque es la ventana de contexto, y tiene un límite.
El límite en tokens es la parte fácil de ver. La otra es menos obvia: la calidad baja antes de llegar al tope. El estudio Lost in the Middle mostró que los modelos encuentran mejor un dato cuando está al principio o al final de un texto largo que cuando queda en el medio, y el informe Context Rot de Chroma midió que el rendimiento cae a medida que crece la entrada, incluso en tareas simples. Por eso Anthropic describe el contexto como un recurso finito con rendimientos decrecientes: cada token de más compite por la atención del modelo con los tokens que sí importan.
Context engineering es el trabajo de decidir qué entra en esa ventana en cada paso. El prompting se ocupa de cómo redactar una instrucción (lo cubre Prompting). Aquí la pregunta es otra: de todo lo que el agente podría leer, qué necesita ahora, qué puede esperar y qué debería vivir en disco?
Tres zonas: siempre, bajo demanda, fuera
Una forma práctica de pensarlo es repartir el conocimiento en tres zonas según cuándo llega a la ventana.
- Siempre cargado
- Lo mínimo para orientarse: reglas que no admiten excepción, el mapa de qué cargar para cada tipo de tarea y el nombre y la descripción de cada skill. Cada línea aquí se paga en todas las sesiones, así que tiene que ganarse el lugar.
- Bajo demanda
- El procedimiento detallado de una skill, sus references y los archivos del ticket. Entran cuando la tarea los pide y sobran cuando la tarea cambia.
- Fuera
- Hechos regenerables, historia de trabajo y estado de sesiones largas. Viven en disco o en una memoria externa y el agente los consulta con una lectura concreta.
Lazy loading y compact rules
Las Agent Skills se diseñaron alrededor de esta idea, que Anthropic llama
progressive disclosure. Al arrancar, el agente solo conoce el name y
la description de cada skill. Si una tarea encaja con esa descripción, lee el
SKILL.md completo. Si el SKILL.md remite a un archivo de
referencia, lo abre en ese momento y no antes. Una skill puede tener cientos de páginas de
material sin costar nada mientras nadie la usa.
Esto cambia cómo se escribe una skill. La descripción es lo que el modelo compara con la
tarea, así que tiene que nombrar los disparadores reales. El cuerpo lleva el flujo y las
reglas. El detalle largo (tablas de campos, sintaxis de CLI, casos borde) va a
references/, con una línea en el cuerpo que diga cuándo abrirlo.
Las compact rules son un escalón intermedio pensado para subagentes. Cuando
el agente principal delega una tarea, podría pedirle al subagente que lea tres
SKILL.md enteros. En cambio, le pega en el briefing un bloque acotado de reglas
por skill (DO, DO NOT, WHEN; un bloque escrito a mano va entero, y solo el raspado
automático de scripts/build-skill-registry.ts tiene tope) y una línea que dice
cuándo hace falta leer el archivo completo. El subagente trabaja con un resumen verificado y
el costo por encargo baja mucho cuando varias skills se solapan.
Memoria, resúmenes y handoffs
Una tarea larga no cabe en una sola ventana. Hay tres herramientas para que el trabajo sobreviva al límite, y cada una resuelve un problema diferente.
La compaction la hace el harness: cuando la conversación se acerca al tope, resume lo anterior y sigue con el resumen. Es cómoda y automática, pero el resumen lo decide un modelo que no sabe qué va a necesitar el paso siguiente, y lo que se pierde no vuelve.
Las notas estructuradas son archivos que el propio agente escribe mientras trabaja: un plan, un registro de avance, una lista de decisiones. Si la sesión se corta, la siguiente lee esos archivos y retoma. La ventaja es que están en disco, tienen una ruta y cualquiera puede leerlas, humano o agente.
La memoria persistente guarda lo que tiene valor más allá de una tarea: una decisión de arquitectura, la causa raíz de un bug, una preferencia del equipo. Se consulta con una búsqueda cuando el tema vuelve a aparecer, semanas después.
Un handoff combina lo anterior a propósito. En lugar de dejar que el harness comprima, la sesión que termina escribe un documento pensado para su sucesora: qué estaba haciendo, qué archivos importan, qué falta y qué no debe repetirse. La sesión nueva arranca con la ventana limpia y con exactamente lo que necesita.
Contaminación y drift
Dos problemas estropean un contexto que en tamaño parece sano.
La contaminación es texto que está en la ventana y no ayuda: la salida completa de un comando de 2000 líneas, cinco archivos leídos para encontrar una función, un intento fallido que el modelo sigue teniendo delante. Ese ruido distrae y además empuja las instrucciones importantes hacia el medio, donde se atienden peor. Las defensas son simples: filtrar salidas antes de leerlas, delegar la exploración pesada a un subagente que devuelve solo la conclusión (ver Subagentes y orquestación) y empezar una sesión nueva cuando la tarea cambia de tema.
El drift aparece cuando una copia en el contexto deja de coincidir con la fuente. Un documento cita un script que se renombró, un resumen describe un campo que ya no existe, una caché local tiene el ticket de hace una semana. El agente actúa con confianza sobre un dato viejo. La defensa es tener una sola fuente para cada hecho, leerla en el momento y poner gates que detecten la copia desactualizada antes de que llegue a un commit (ver Harness engineering).
Así lo hace este repo
| Idea | Dónde vive | Cómo se aplica |
|---|---|---|
| Franja fija mínima | AGENTS.md |
Se carga en cada sesión (Claude Code lo lee a través de CLAUDE.md, que
solo importa @AGENTS.md). Guarda solo lo que ata en cada turno: la
frase obligatoria de cada regla, la capa de conducta, el núcleo de orquestación y un
router. El resto vive en una sección por tema bajo
.agents/instructions/, que se lee cuando el router o una línea
ROUTE: del hook la nombra; la tabla de tarea → skill → contexto es
agent-context-map.md.
|
| Compact rules |
.agents/skills/REGISTRY.md,
.agents/skills/agentic-qa-core/references/skill-resolver.md
|
scripts/build-skill-registry.ts genera un bloque por skill. Strategy A
toma la sección ## Compact Rules del SKILL.md tal cual,
sin tope; Strategy B raspa las primeras viñetas (ahí sí hay un tope,
MAX_SCRAPED_RULES) y marca el bloque como de baja confianza. Si el
frontmatter trae compact_rules:, también se usa literal y sin tope. El
briefing pega un número acotado de skills; el límite lo fija el protocolo del
resolver (agentic-qa-core/references/skill-resolver.md).
|
| Un modo, una reference | .agents/skills/project-context/SKILL.md |
Cada ejecución resuelve un solo modo y carga solo la reference de ese modo. El modo
context-skill crea una skill de criterio propia del proyecto, solo para
un aspecto que las context skills de mapas no cubren: cita sus fuentes y nunca copia
su contenido
(.agents/skills/project-context/references/context-skill.md). El modo
coverage no escribe un mapa: cruza los mapas con los tests (manifest
KATA y TMS) y deja una lista de brechas recalculable en .session/, con
un script para la parte aritmética (bun run context:coverage) y la IA
para el juicio de qué test ejercita qué
(.agents/skills/project-context/references/coverage.md).
|
| Lo sintetizado vive en una skill |
cli/lib/context-maps.ts (CONTEXT_MAP_SKILLS),
scripts/context-map.ts
|
Lo que un script baja de una fuente (la caché de Jira) va a .context/;
lo que una IA sintetiza (los mapas de datos, API, E2E, dominio e infraestructura) es
un HTML dentro de su context skill. Tú lo abres en el navegador; el agente lo lee
con bun run context:map <slug>, que quita SVG y estilos y deja
cada sección como texto (--section <id> trae una sola,
--list el índice). Así el agente carga una sección y no el mapa entero.
|
| Hecho contra criterio | .agents/skills/agentic-qa-core/references/skill-scaffold.md |
Tres preguntas deciden dónde va cada dato: si un comando lo regenera, va a
.context/; si dos sesiones lo escribirían distinto, es criterio y va a
la skill; si tiene que aparecer sin que nadie lo pida, también va a la skill.
|
| Caché local con niveles | .context/PBI/, scripts/sync-jira-issues.ts |
Cada archivo es [SYNC] (espejo de Jira, gitignored, se reconstruye con
bun run context:hydrate), [COMMIT] (versionado, como
test-specs/) o [LOCAL] (desechable, nada puede depender de
él). Un [SYNC] nunca se escribe a mano.
|
| Notas estructuradas |
.agents/skills/agentic-qa-core/references/session-management.md
|
Las skills largas escriben plan.md y progress.md en
.session/<skill>/<scope>/. La Phase 0 lee el progreso y
ofrece retomar, reiniciar o abortar. El diseño es file-first: la reanudación
funciona aunque Engram no esté disponible.
|
| Memoria persistente | Engram (sección 12 de AGENTS.md) |
mem_save después de cada decisión, bug corregido o hallazgo no obvio, y
mem_session_summary antes de cerrar la sesión.
|
| Handoff |
.agents/skills/session-handoff/SKILL.md,
.agents/skills/session-handoff/references/capture-contract.md
|
Escribe .session/handoffs/<session-name>-handoff-NN.md en el
checkout principal (también desde un worktree, para que no se pierda al borrarlo) y
lanza la sucesora en el mismo worktree y el mismo harness. Lo dispara la persona
cuando ve que la ventana se llena.
|
| Contra el drift | AGENTS.md y package.json |
La regla 11 prohíbe citar comandos de memoria: se lee
package.json antes de nombrar un script.
bun run skills:registry:check falla si el REGISTRY quedó viejo respecto
de las skills.
|
El resultado práctico: una sesión de QA arranca con AGENTS.md y las
descripciones de skills, lee las secciones que el router le nombra, carga
/sprint-testing cuando le piden probar un ticket, sincroniza ese ticket a
.context/PBI/ y lee solo los archivos de esa historia. Si delega, el subagente
recibe compact rules en lugar de skills completas. Para ver el ciclo entero en contexto,
revisa el IQL en este repo.
-
Meter en
AGENTS.mdun procedimiento que solo usa una skill. Se paga en cada sesión y diluye las reglas que sí importan. Va a la skill o a una reference. -
Leer un archivo entero para sacar una línea, o volcar la salida completa de un comando.
Filtra primero con
grep,heado un subagente. -
Editar a mano un archivo
[SYNC]de.context/PBI/. El próximo sync lo pisa. El cambio va a Jira y luego se sincroniza. -
Hacer depender un paso de un archivo
[LOCAL]. En otra máquina no existe y el paso se degrada sin avisar. -
Copiar en otra skill la tabla de un mapa de contexto. El mapa vive en su context skill y
se lee con
bun run context:map; con una copia quedan dos fuentes y una va a envejecer. - Confiar en la compaction para una tarea de horas. Escribe plan y progreso en disco, o haz un handoff, antes de que el harness decida qué olvidar.
Para profundizar
- Effective context engineering for AI agents (Anthropic Engineering): el contexto como recurso finito, compaction, notas estructuradas y arquitecturas con subagentes.
- Equipping agents for the real world with Agent Skills (Anthropic Engineering): progressive disclosure en tres niveles, de la descripción a las references.
- Lost in the Middle: How Language Models Use Long Contexts (Liu et al., TACL 2024): por qué la posición de un dato dentro de un texto largo cambia si el modelo lo usa.
- Context Rot: How Increasing Input Tokens Impacts LLM Performance (Chroma Research): mediciones de cómo cae el rendimiento al crecer la entrada, con distractores y tareas simples.