context-engineering
verifiede553ec28-99e3-45e4-b2da-4133c1977075
Curate the finite context window of an AI agent — compaction, tool-output clearing, and the principle of finding the smallest set of high-signal tokens — for long-horizon reliability.
Metadata
Skill file
# Context Engineering for Agents
Use when a single context window is not enough for a task — multi-hour coding
sessions, deep research, migrations — and you need the agent to stay coherent without
drifting or silently forgetting. Context engineering (Anthropic, "Effective context
engineering for AI agents", 2025-09-29) is the discipline of curating *which tokens*
enter the finite context window, as the natural evolution of prompt engineering.
## The guiding principle
Context is a finite, high-value resource. The goal is not "fit more in" but *find the
smallest set of high-signal tokens that maximizes the desired outcome*. Every token
you add competes with everything else for the model's attention; noise degrades
decision quality long before you hit the hard token limit. Most production failures
are not raw context exhaustion — they are *agent drift*: the model losing the thread
because early context got buried.
## The three levers (from cheapest to most destructive)
1. **Compaction** — when the conversation nears the limit, summarize its contents and
re-initiate a fresh window carrying the summary. The summary must be
*high-fidelity*: capture goals, decisions, constraints, and unresolved items;
discard redundant tool output. Think "maximize recall, then maximize precision."
2. **Tool-output clearing** — drop old tool results (large file reads, search output)
once consumed, keeping only the few most recent. Cheaper than compaction because
you aren't re-summarizing — you're discarding already-used content.
3. **Manual restructuring / scrubbing** — programmatically rewrite or prune the
message list (remove stale branches, de-duplicate, reorder). Most control, most
engineering.
Platforms increasingly expose these as first-class knobs — e.g. the Anthropic API's
context-management betas: compaction (`compact-*`, default trigger ~150K input
tokens) and tool-use clearing (`clear_tool_uses_*`, default trigger ~100K tokens,
keeping the N most recent tool results).
## What belongs in the summary
Compaction is a *distillation*, not a transcript shrink. Preserve:
- The original goal and any constraints/acceptance criteria.
- Decisions made and *why* (rationale beats conclusions).
- Current state: what's done, what's blocked, next concrete action.
- Unresolved questions and open hypotheses.
- Key factual findings and file/path locations.
Drop: full tool outputs, verbatim transcripts, superseded intermediate drafts.
## The trap: summarization isn't free
JetBrains Research (SWE-bench Verified, 2025) found LLM summarization can
*paradoxically lengthen* trajectories by 13-15% — summaries obscure natural stopping
signals, so agents keep working past the optimal stop point — and summarization cost
exceeded 7% of per-instance spend in their study. Compaction helps coherence but is
not a complete strategy: instrument trajectory length when you enable it, and pair it
with explicit stop conditions.
## Instrumentation is non-negotiable
You cannot engineer context you can't see. Log, per turn: input token count, what was
cleared/summarized, and the quality of the next few decisions. Watch for the moment
the agent starts re-asking questions it already answered — that's the drift signal
that your context policy failed.
## Pitfalls
- Summarizing too early and too often — each compaction is lossy; you pay a
fidelity tax every time.
- Summaries that keep conclusions but drop rationale, so the agent can't re-derive or
reverse a bad decision.
- No instrumentation — you're tuning blind and can't tell drift from a bad prompt.
- Ignoring stop conditions; a good context policy should also know when to *stop*.
## Verify
- Run the same long-horizon task with and without your context policy; compare
completion rate, trajectory length, and cost.
- Log compaction events and inspect a few summaries for fidelity (did the summary
retain the goal + rationale?).
- Confirm the agent doesn't re-derive already-known facts after a compaction.Attached files
No attached files.