Context Engineering

How the harness controls what an agent sees, when it sees it, and what contract applies

Context engineering is the work of shaping the environment around the agent.

The useful question is: what should the agent know, from which source, at which moment, under which workflow contract, and with which proof standard?

A root prompt gives the broad behavior. Scoped guidance narrows it near the code. Skills define how work should proceed. Source files, specs, logs, docs, and external package source provide evidence. Validation tells the agent what counts as done. The point is to keep the right constraints available at the right time.

The theory matters because context is an operating surface with costs. Each layer has a job, and each extra layer creates token pressure, stale residue, and another chance for the run to anchor on material that no longer applies.

Context Layers

Harness context is layered:

Root behavior: broad runtime policy, interaction norms, and general engineering quality expectations.
Project policy: root repo identity, app/package boundaries, command conventions, and source-of-truth rules.
Scoped guidance: app, package, docs, or wiki ownership rules located near the files they govern.
Skills: task-shaped workflow contracts activated by name or by scoped guidance.
Source material: current code, docs, specs, implementation notes, logs, generated scaffold specs, and legacy pages mined as evidence.
External source inspection: official docs and opensrc package or repository source when dependency behavior matters.
Memory notes: compact non-obvious gotchas and project decisions that should survive future sessions.
Validation feedback: tests, typecheck, browser evidence, runtime logs, review findings, and manual checklist results.

Each layer should answer a concrete question. A harnessed run starts from repo guidance, activates the relevant skills, reads the evidence it needs, and stops loading context once the decision is clear enough to act.

Context Decay

Context has half-life. A long run starts with useful instructions, evidence, and a tractable objective. Then the transcript starts collecting residue: old guesses, failed commands, partial plans, stale file reads, rejected paths, and whatever happened most recently.

The window behaves like a working environment. Older material can keep affecting newer decisions.

That decay changes the model of the run. A fact that was correct at discovery can become wrong after an edit, a user correction, a newer source read, or a narrower scoped rule.

Rot vs Poison

Context rot is expired truth. The agent saw something useful earlier, but the run moved on. A test failure was fixed. A plan was replaced. A file moved. Root guidance was narrowed by scoped guidance. The old fact has passed its sell-by date.

Context poisoning is wrong material that keeps exerting force because it remains visible. A bad hypothesis, a noisy log excerpt, a hallucinated constraint, or an abandoned implementation path can keep nudging the model back toward work that should be dead.

Rot asks for pruning. Poison asks for quarantine. Both make raw transcript continuity a weak default for long work.

Token Pressure

A context window does not need to be full before it starts changing the run.

Every extra chunk of old material adds work. The model has to separate current signal from stale residue. The user pays for more tokens. The turn takes longer. The agent has more chances to anchor on old details because those details are still present and linguistically available.

The question is wider than "will the next message fit?" A run can become slower, more expensive, and less precise while it still technically fits.

Manual Handoff

Manual handoff is curated continuation. The agent selects the pieces that still matter: current objective, accepted decisions, changed files, verification evidence, unresolved questions, durable artifact links, and the skills the next run should activate.

Automatic compaction can still help, but it summarizes what happened. Handoff declares what remains operational.

The handoff skill keeps that reset narrow:

write a continuation document to the operating system's temporary directory
include suggested skills
reference durable artifacts by path or URL
avoid duplicating specs, plans, ADRs, issues, commits, and diffs
redact sensitive information

Use a manual handoff when:

a requirements pass is done and planning is next
a plan is accepted and implementation will be long
debugging produced enough evidence for a cleaner resolution run
implementation is done and docs ingest should begin with curated state
the next session should start fresh with proper context before a long phase

Avoid manual handoff inside the same active phase. Interrupting implementation halfway through a coherent edit, stopping a debugging hypothesis before verification, or breaking a writing pass while the shape is still forming can destroy useful continuity.

Preserve flow inside a phase. Reset between phases.

Bad Handoff vs Good Handoff

A bad handoff copies the transcript. It carries every false start, noisy command, abandoned theory, and accidental detail into the next run. It recreates the same context pressure in a smaller file.

A worse handoff happens too early. It interrupts the same phase and forces the next agent to reconstruct useful working memory: why an edit is half-finished, which branch of the hypothesis tree is active, or which local assumption still needs a test.

A good handoff is selective. It says what the objective is now, what changed, what was verified, what remains open, which artifacts to read, which skills to activate, and what to avoid repeating.

The goal is a next session that begins cleanly without becoming naive.

Failure Patterns

Common failure patterns:

a one-off prompt carries rules that should live in scoped guidance
a scoped AGENTS.md lists global phase skills as local primary skills
docs describe planned behavior as if it already shipped
package behavior is inferred from memory when upstream source is cheap to inspect
validation is implied by confidence instead of recorded as evidence

These are context failures. The harness fixes them by moving durable rules into stable surfaces and by making validation part of the work contract.

On this page