Context Engineering: The Hardest Problem in Agent Harness Design

Part one of this series took apart the agent loop. This part is about the resource that loop burns fastest.

Watch an agent’s token meter during a real task and you’ll notice something uncomfortable. Your prompts are a rounding error. What actually devours the window is tool output: file contents it read along the way, test failures, directory listings, that one npm install log it never asked for but got anyway. An agent that has been working for an hour is usually carrying megabytes of other people’s stack traces into every single decision.

I used to think prompt engineering was the skill here. It isn’t, or not anymore. The discipline that separates agents that finish from agents that wander off a cliff is context engineering: deciding what deserves a slot in a finite window, for how long, and in what form. Anthropic’s engineering team published an entire guide calling it the evolution of prompt design, and their framing matches what I’ve seen: attention is a finite resource, every token competes for it.

Here’s the mental model I keep coming back to: the context window is a whiteboard that erases itself from the middle. New work gets written at the end. Old work quietly smudges as summarization passes over it. The harness’s job is making sure that when something gets erased, the right things survive.

---

Compaction: summarize the past, protect the present

The standard move when the window approaches its limit is compaction. Take the old turns, ask the model (or a cheaper model) to compress them into a summary, replace history with the summary, carry on.

Naive compaction loses exactly the things that matter. A summary of “the agent tried three database schemas and settled on the second” can drop why the first two failed, and then hour two of the run cheerfully re-proposes schema one. Good harnesses treat compaction as lossy compression with a protection list:

• Decisions and their rationale get pinned verbatim, never summarized.
• Recent turns stay raw, since the current task’s details live there.
• Errors encountered survive, because retrying a failed approach is the classic compaction-amnesia failure.

The Manus team’s writeup on building their agent describes this precisely: they reconstruct the todo list from the last assistant message after every compression step, so the plan survives even when the reasoning that produced it doesn’t. That single trick, restating goals inside the post-compaction context, does more for long runs than any clever retrieval scheme I’ve tried.

Stop stuffing, start referencing

The other half of the problem happens before the run even starts. Teams cram style guides, API docs, architecture notes, and conventions into the system prompt “just in case”. Then the model reads ten thousand tokens of deployment policy while debugging a CSS grid.

The better pattern is referencing: keep knowledge in files, tell the model those files exist, and let it load them on demand. This is the core insight behind the skills pattern; I wrote about building agent skills that hold up separately. Progressive disclosure, applied to context. Your system prompt carries a map, not the territory.

There’s a billing angle too. Manus reported that cached input tokens cost roughly an order of magnitude less than uncached ones, which means stable prefixes aren’t just tidy, they’re cheap. Every byte you append mid-conversation invalidates cache for everything after it. Append-only context, minimal churn, is performance work disguised as hygiene.

Subagents: isolation as a feature

When one task’s exploration would poison another’s context, don’t share a window. Spawn a subagent with a fresh one, give it a narrow brief, and let it return only the conclusion.

Search is the canonical example. Finding where auth is implemented might require skimming thirty files. You want the answer (“it’s in src/auth/session.ts, uses rotating refresh tokens”) without the thirty files riding along forever. The subagent burns its own window doing the digging and hands back a paragraph.

Cognition’s contrarian classic Don’t Build Multi-Agents adds the necessary caution: parallel agents sharing partial state produce conflicting edits and confidently wrong synthesis. Their rule was that a single agent should own the context for a task, and if you delegate, hand over a complete, self-contained brief. Isolation helps when boundaries are clean. When they’re fuzzy, it just hides the confusion until later.

---

My checklist

After enough burned windows, mine looks like this:

1. Biggest offender first. Instrument what’s actually consuming tokens before optimizing anything. It’s almost always tool output.
2. Pin decisions, summarize events. The “we chose Postgres because RLS” line survives every compaction. The forty files read along the way do not need to.
3. Files over prompts. If an instruction only matters sometimes, it lives in a referenced file, not the system prompt.
4. Fresh window per subtask, complete briefs across boundaries, no shared mutable state between concurrent agents.

None of this requires a smarter model. All of it lives in the harness, which is exactly why harness design is worth your time. Next up: the parts of the harness that keep an agent from doing damage, permissions, sandboxes, and hooks, in part three.

Check your understanding

Three questions on the checklist above. Open each for the verdict.

Compaction summarized your run and the agent immediately retries a schema you already rejected. What was missing?

Pinned rationale. Decisions and their why must survive verbatim; a summary of events alone does not stop the retry.

Why does appending context mid-run cost more than a stable prefix?

Cache invalidation. Cached input tokens cost an order of magnitude less, and every append invalidates the cache for everything after it.

When do subagents hurt instead of help?

When boundaries are fuzzy. Isolation pays off for clean briefs like search; shared mutable state across agents produces conflicting edits.

What’s the worst thing compaction ever forgot mid-run for you? Swap war stories on Twitter/X.

Next in this series (3/4)Agent Harness Guardrails: Permissions, Sandboxes, and Hooks→