Context Engineering for Long-Running Agents

An agent can have a large context window and still lose track of the task.

The problem is not only whether the next message fits. The context must contain the right information at the right time:

the current goal
relevant evidence
active constraints
recent decisions
tool results needed for the next step
enough progress state to continue

Everything else competes for the model’s attention and increases token cost.

Context engineering is the design of what enters the model’s working context, when it enters, how long it stays, and where durable information lives outside it.

Context Is Working Space

For a beginner, it helps to think of context as the documents spread across a desk.

The desk may contain:

the current conversation
system and project instructions
files the agent has read
command output
tool definitions
skill content
summaries of previous work
results returned by subagents

The model uses this material to choose its next response. It does not mean every detail is permanently remembered.

As the desk fills, the system may:

remove old tool output
summarize older messages
start a fresh context
delegate work to another context
load reference material only when needed

Durable state must live somewhere more reliable than the current model request.

Five Different Information Stores

Do not put every kind of information into one long prompt.

Store	What belongs there	Example
Active context	Information needed for the next decisions	Current bug, inspected files, latest test failure
Project instructions	Stable rules used across tasks	Build commands, architecture conventions
On-demand knowledge	Detailed guidance needed for certain tasks	Deployment skill, API reference
Durable artifacts	Evidence and decisions that must survive context loss	Plan, investigation notes, test report
Application state	Authoritative workflow progress	Approval status, job state, idempotency key

Subagents add a sixth useful location: an isolated temporary context that returns only a bounded result.

The Context Lifecycle

flowchart TD
    G["Goal and stable constraints"] --> A["Active agent context"]
    A --> R["Retrieve only relevant files and tools"]
    R --> W["Work and collect evidence"]
    W --> D{"Information still needed?"}
    D -->|"Needed now"| A
    D -->|"Reusable later"| K["Project instructions or skill"]
    D -->|"Task evidence"| F["Durable artifact"]
    D -->|"Independent subtask"| S["Subagent with isolated context"]
    S --> B["Bounded result"]
    B --> A
    A --> C{"Context becoming noisy or full?"}
    C -->|"No"| W
    C -->|"Yes"| M["Compact or start a focused handoff"]
    M --> A

Good context management is continuous. It is not a cleanup step performed only after the window is full.

Capacity And Relevance Are Different

A larger context window increases capacity. It does not guarantee good attention.

An agent can still struggle when context contains:

several obsolete plans
full logs when only one error matters
large generated files
duplicated instructions
tool schemas it will never use
findings from unrelated subagents
old assumptions that later evidence disproved

The useful question is not “Can this fit?” It is “Will this help the next decision?”

Gather Context On Demand

Do not preload an entire repository because the task might touch it.

A better sequence is:

identify the question
search for likely entry points
read the smallest relevant files
follow references when evidence requires it
stop gathering when the decision is grounded

For a login failure, the agent may first inspect:

the failing request or test
the authentication entry point
the token validation path
related configuration

It does not need every UI component, migration, and deployment log.

On-demand discovery makes the context smaller and keeps the evidence connected to the current hypothesis.

Prefer Search Before Bulk Reading

Search tools are valuable because they narrow the information surface.

Useful searches include:

symbol or function names
error messages
configuration keys
test names
imports of a deprecated dependency
call sites of a public API

Repository search and code-intelligence tools often provide a better first step than embeddings for local source code because identifiers, paths, imports, and exact strings carry strong structure.

This does not make retrieval-augmented generation obsolete. Semantic retrieval remains useful for large knowledge bases, loosely worded documentation, or material without reliable identifiers. Choose retrieval from the shape of the information, not from a universal rule.

Bound Tool Output

Tool output enters context too.

Weak:

npm test

This may produce thousands of irrelevant lines.

Better:

npm test -- auth-refresh.test.ts

Other useful controls:

request line ranges instead of whole large files
filter logs around the failure
return structured fields instead of complete API responses
cap search results
store large artifacts in files and return their paths
summarize repeated errors without hiding the first full example

A tool should provide enough evidence to act without flooding the model.

Separate Progress State From Conversation

A task list is useful working state:

[done] reproduce refresh failure
[done] trace token validation
[in progress] add regression test
[pending] implement fix
[pending] run focused and integration checks

It helps the agent and user see:

what has been attempted
what remains
where the run is blocked
whether the task stopped prematurely

But conversation text is not an authoritative workflow database.

Persist important progress separately when:

work must survive process failure
several agents coordinate
approvals may take hours or days
side effects must not repeat
operators need an audit trail

Use a database, workflow engine, issue, pull request, or structured task file depending on the reliability requirement.

Use Files As Durable Task Artifacts

Files are useful for information that must survive compaction or a new session:

approved requirements
architecture decisions
investigation findings
migration maps
lists of changed files
test commands and results
unresolved risks

A useful handoff artifact is concise enough to reload but specific enough to verify:

# Current Goal
Preserve login across token refresh without weakening expiry checks.

# Confirmed Evidence
- `src/auth/refresh.ts` accepts the old token.
- `src/auth/session.ts` rejects the refreshed session.
- Focused reproduction: `npm test -- refresh-session.test.ts`

# Decision
Keep validation in the session service. Do not add a client-side retry.

# Remaining Work
- Add the failing regression case.
- Implement the scoped server fix.
- Run auth integration tests.

Do not save every intermediate thought. Save facts, decisions, evidence, and unfinished work.

Project Instructions Versus Skills

Stable instructions and on-demand procedures have different context costs.

Project instructions

Use project-level instructions for rules that usually matter:

package manager
build and test commands
high-level architecture
repository-wide conventions
files that must not be edited

Skills

Use skills for detailed procedures needed only for certain tasks:

release process
incident response
document generation
security-review checklist
product-specific API workflow

Loading a full deployment manual into every debugging session wastes context. Keeping a critical repository rule only in an optional skill risks missing it.

Current Claude Code documentation follows this distinction: CLAUDE.md is persistent context, while skill descriptions are visible for routing and full skill content loads when used.

Use Subagents For Context Isolation

A subagent starts with a separate context, performs a bounded task, and returns a result.

This is useful when a subtask generates information the main agent does not need to retain:

reading a large set of documentation
scanning many files for one pattern
reviewing a diff for one risk category
running and interpreting a verbose test suite
comparing independent implementation options

flowchart LR
    M["Main context<br/>goal and decisions"] --> P["Delegation prompt<br/>scope and output contract"]
    P --> S["Subagent context<br/>independent reads and tools"]
    S --> O["Bounded result<br/>findings and evidence"]
    O --> M

The delegation prompt should contain:

the exact question
allowed scope
relevant starting evidence
required output format
what not to do

Do not copy the whole parent conversation automatically. The isolation is useful only when the subagent receives a curated task.

When not to use a subagent

Keep work in the main context when:

several phases depend on the same detailed history
the task needs frequent user clarification
the change is small
the subagent would need to rediscover everything
the returned summary would omit information required for implementation

Subagents reduce context pressure, but they introduce delegation cost and another place for misunderstandings.

Compaction Is Lossy

Compaction replaces older conversation material with a shorter summary.

It is useful, but it cannot preserve every detail. A good compacted handoff should retain:

the current objective
acceptance criteria
non-goals and safety boundaries
files read or changed
commands and meaningful results
confirmed facts
decisions and their evidence
unresolved questions
the next concrete step

Do not assume that an instruction mentioned near the start of a long chat will survive unchanged. Stable rules belong in project instructions; task decisions belong in durable artifacts.

Current Claude Code documentation says it first clears older tool outputs and then summarizes conversation history when needed. It also allows compact instructions that tell the system what the summary should preserve.

Handoff To A Fresh Context

Sometimes a fresh session is better than repeatedly summarizing a crowded one.

Use a handoff when:

the task is moving from research to implementation
the original context contains many rejected hypotheses
a new specialist needs only approved conclusions
compaction repeatedly refills immediately
the remaining work is now independently understandable

A handoff is not “start over.” It is:

produce a grounded task artifact
open a clean context
load the artifact and relevant files
verify its claims against the repository
continue from the documented state

This reduces inherited noise while preserving evidence.

Context Management For A Large Refactor

Consider a repository-wide dependency migration.

Main context keeps

migration goal and non-goals
dependency graph
batch definitions
accepted architectural decisions
integration status
blockers that affect several batches

Worker context receives

one batch contract
owned files
prerequisite changes
verification commands
relevant conventions

Durable storage keeps

batch status
commits or pull requests
verification evidence
discovered exceptions
integration order

Context deliberately excludes

full transcripts from every worker
unrelated file contents
repeated logs already captured in artifacts
obsolete migration plans

This is why parallel agents need task and repository isolation, not merely more context windows.

Tool Definitions Also Consume Context

Every available tool adds at least a name and description; some runtimes add the full schema.

Large tool catalogs can:

consume tokens before work begins
make tool selection harder
introduce overlapping descriptions
expose capabilities unrelated to the task

Use:

small task-specific tool sets
deferred tool loading where supported
precise names and descriptions
subagent-specific tool permissions
MCP toolset selection instead of enabling every server

Claude Code currently defers full MCP schemas by default and loads them through tool search when needed. Other hosts may load every schema eagerly, so verify the behavior of the runtime you deploy.

Observe Context Behavior

Useful measurements include:

tokens loaded before the first user request
file and tool-output tokens added per turn
number and size of tool results
compaction frequency
repeated reads of the same material
number of active tool definitions
subagent input and returned-summary size
failures after compaction or handoff
decisions lost between sessions

Token count is not the only signal. A smaller context can still be poor if it omits the requirement or contains an incorrect summary.

Common Failure Modes

Failure	Cause	Better approach
Load the whole repository	Capacity is mistaken for relevance	Search, then read on demand
Paste complete logs	Raw output is treated as evidence	Filter and preserve the key failure
Put every rule in project instructions	Always-loaded context grows without limit	Move task-specific procedures to skills
Put critical rules only in skills	Optional content may not load	Keep mandatory rules always available
Delegate with a vague prompt	Subagent must guess the real question	Give scope, evidence, and output contract
Return a complete subagent transcript	Isolation benefit is lost	Return bounded findings and references
Treat compaction as perfect memory	Summaries omit details	Persist facts and decisions in artifacts
Use conversation as workflow state	Restarts can lose progress	Store authoritative state outside the model
Keep extending a polluted session	Rejected hypotheses remain influential	Create a verified handoff to a fresh context

Practical Checklist

Before a long run:

Define the goal, acceptance criteria, and non-goals.
Identify stable project instructions.
Keep optional procedures in on-demand skills or docs.
Scope tools to the task.
Decide where task state and evidence will be persisted.
Define when to delegate, compact, or hand off.

During the run:

Search before reading large areas.
Bound command and API output.
Update progress from evidence.
Save confirmed decisions outside the conversation.
Remove or supersede stale assumptions.
Keep subagent results concise and verifiable.

Before a handoff:

Record the current objective.
List files read and changed.
Preserve test commands and results.
Distinguish facts from assumptions.
Record decisions and remaining risks.
State the next concrete action.

Key Takeaways

Context is temporary working space, not authoritative long-term memory.
Relevance matters as much as context-window capacity.
Gather evidence on demand instead of preloading everything.
Bound tool output and store large artifacts outside the conversation.
Keep stable rules, optional procedures, task evidence, and workflow state in different stores.
Use subagents to isolate verbose independent work, not to avoid clear task ownership.
Treat compaction as a lossy handoff.
Start a fresh context when a verified artifact is cleaner than another summary.
Measure context behavior instead of assuming a larger window solves the problem.