Context Engineering Is Interface Design

Most conversations about context begin with quantity.

How many tokens fit? How much of the repository can we send? Can the model read every ticket, design document, database schema, and conversation that might matter?

Capacity is useful. It is not the same thing as clarity.

A model with access to everything still has to decide what deserves attention, which instruction has authority, what changed recently, and which artifact represents the current truth. When a context window becomes a warehouse, the model is asked to be the archivist, editor, conflict resolver, and worker at the same time.

I think context engineering becomes easier to reason about when we stop treating it as prompt expansion and start treating it as interface design.

An interface chooses what to reveal, what to hide, how to group information, and how to make the next action legible. It creates a boundary between a complicated system and a participant who needs to do something inside it. Context does the same job for an AI agent.

The quality of that interface often matters more than the size of the window behind it.

The Agent Sees a Representation, Not the World

An agent never works directly on a repository, company, customer, or incident. It works on a representation assembled for the current invocation.

That representation may include file contents, search results, tool descriptions, memory, policy, conversation history, and summaries produced by other models. Each layer makes choices. A retrieval system ranks some documents above others. A file reader truncates large output. A summarizer decides which details survive. A system prompt assigns priority to one rule and leaves another implicit.

Those choices shape the agent's reality.

If an old architecture document outranks the current code, the model may confidently restore a design the team already abandoned. If an error log is included without its timestamp, the agent may diagnose a fixed incident. If approval policy is buried beneath examples, the model may treat it as optional guidance.

Context engineering is therefore not about “giving the model knowledge.” It is about constructing a faithful task surface from incomplete and competing sources.

Start With the Decision the Agent Must Make

Good interfaces are designed around an action. Good context should be as well.

Before retrieving anything, ask what decision the current step owns. Is the agent deciding how to decompose a migration? Which file to edit? Whether a claim is sufficiently supported? Whether a deployment is permitted?

Different decisions need different context.

A planner may need broad architecture, constraints, and a map of the repository. An implementer needs the selected plan, nearby code, conventions, and a narrow acceptance criterion. A reviewer needs the request, diff, test evidence, and enough surrounding design to notice a regression. Giving all three the same assembled prompt is convenient, but it ignores the job each one has to perform.

This suggests a practical rule:

Build context for the decision in front of the agent, not for every decision the system might eventually make.

The rule reduces noise, but its real value is accountability. When a step has a clear decision, we can ask whether the context was sufficient for that decision and improve it deliberately.

Instruction, Evidence, and State Are Different Things

One of the most damaging context mistakes is presenting unlike information as if it had the same role.

An instruction tells the agent what should happen. Evidence describes the world. State records what has happened in the workflow. Examples demonstrate a pattern. A hypothesis proposes an explanation that may still be wrong.

When these arrive as an undifferentiated wall of text, the model must infer their type and authority from wording alone.

A better context interface makes the categories explicit:

• Goal: the outcome the user has authorized
• Constraints: boundaries that remain true throughout the work
• Current state: completed steps, pending decisions, and durable artifacts
• Evidence: retrieved facts with source and freshness
• Working material: files or records relevant to this step
• Available actions: tools, permissions, and side effects
• Completion test: the evidence required before the step can finish

This does not require a giant XML framework. Clear sections and stable contracts are enough. The point is to reduce the amount of semantic archaeology the model must perform before doing the actual work.

Provenance Is Part of the Interface

Facts without provenance age badly.

Suppose an agent sees: “The payment service uses API version 3.” Did that come from deployed configuration, a two-year-old wiki page, a previous model summary, or a comment in an abandoned branch? The sentence looks equally authoritative in the context window. Its origin changes everything.

Useful context carries lightweight provenance:

• where the information came from
• when it was observed or updated
• whether it is primary evidence or a summary
• which scope it describes
• whether another source contradicts it

Freshness matters most where the world can change between planning and execution. A tool result that was correct ten minutes ago may no longer be a safe precondition for an irreversible action. The harness should be able to mark evidence as stale and require revalidation rather than letting the agent assume that presence in context means current truth.

Provenance also makes debugging possible. When an agent reaches a bad conclusion, we can inspect whether the reasoning failed or whether the interface supplied the wrong version of reality.

Precedence Has to Be Visible

Real tasks contain conflicting instructions.

A repository rule says all database changes require a migration. A ticket says to modify the schema directly. A copied example uses an older pattern. A user asks for speed but also says not to break compatibility.

Models are remarkably capable of resolving many of these conflicts, but we should not make precedence a guessing game. The context interface should distinguish durable policy, task-specific instruction, local convention, retrieved reference, and illustrative example.

It should also surface conflicts instead of smoothing them away.

A summarizer that silently merges two incompatible instructions creates a clean sentence and destroys the decision. A better summary says that the sources disagree, names the disagreement, and leaves the correct resolution to an authorized participant.

This is one reason aggressive context compression can be dangerous. Redundancy is not always waste. Sometimes two similar sentences come from different authorities, and the difference between them is the most important fact in the task.

Retrieval Should Create a Working Set

Retrieval is often discussed as search quality: find the chunks most similar to the query. An agent needs more than similarity. It needs a coherent working set.

If the task is to change an authentication flow, the most similar chunks might come from comments and documentation. The useful working set may also require the entry point, the shared session type, the tests that encode expected behavior, the policy controlling token lifetime, and the recent commit that changed one of those assumptions.

The context layer should be able to expand from a matched artifact to its meaningful neighbors. Code has imports, callers, tests, and ownership. Operational events have timelines, services, deployments, and correlated metrics. Policies have jurisdiction, effective dates, and exceptions.

This is where structure beats indiscriminate volume. The right five files with their relationships exposed can be more useful than fifty isolated chunks selected by embedding distance.

Compaction Should Preserve Decisions

Long-running work eventually exceeds even a large context window. Something has to be dropped or compressed.

The naive approach summarizes the conversation. The stronger approach checkpoints the work.

A checkpoint should preserve decisions, artifacts, unresolved questions, and evidence—not every conversational turn that led to them. It should distinguish facts from tentative reasoning and record why a decision was made when that rationale will matter later.

For example, “Use the existing event bus” is less useful than:

Decision: use the existing event bus for order-status updates. Evidence: it already carries the required customer scope and has retry semantics covered by integration tests. Rejected alternative: direct callback because it creates a second delivery path.

That record gives the next context enough information to continue and enough structure to revisit the choice if new evidence appears.

This is why RLMs and recursive orchestrators are interesting. They do not make context limits disappear. They create smaller information boundaries and explicit products between them.

Context Should Expose Affordances

An interface does not only display information. It communicates what can be done.

Tool definitions are the obvious affordances in an agent context, but the design should go further. The agent should know which actions are read-only, which mutate state, which require approval, and which produce evidence suitable for verification.

It should also know what it cannot do.

If a worker can draft a deployment plan but cannot deploy, that boundary should be explicit. Otherwise the model may spend time searching for an unavailable path or phrase the plan as if execution already occurred. Constraints become easier to follow when they are represented in the available action surface instead of existing only as warnings.

This aligns context with least privilege. The agent sees the tools appropriate to the current step, and the interface describes their consequences honestly.

Design for Handoff, Not Just Consumption

Most context design focuses on what the current model needs to receive. Long-running systems also need to design what the model must leave behind.

Every meaningful step should produce an artifact another participant can understand: a plan, a patch, a structured finding, a decision record, a test result, or a request for approval. The output contract is part of the context interface because it tells the agent how its work will become input elsewhere.

Good handoff artifacts are smaller than transcripts and richer than conclusions. They contain the result, supporting evidence, assumptions, and anything the next step must verify. They make it possible to change models, restart workers, or introduce human judgment without losing the thread.

The agent harness becomes dependable when each context boundary has a deliberate input and a durable output.

Measure Context by Behavior

There is no universal perfect prompt architecture. Context quality has to be evaluated against work.

Track where agents ask unnecessary questions, miss constraints, use stale facts, open irrelevant files, repeat searches, or reach conclusions unsupported by the supplied evidence. Compare failures across versions of the context assembler. Test whether removing an instruction changes behavior. Test whether a summary preserves the decisions required after a restart.

Token count is a cost metric. Retrieval precision is an information metric. Neither tells us whether the agent could make the right decision.

The useful metric is behavioral: did this representation help the agent act correctly, efficiently, and within its authority?

A Clear Window Beats a Large Warehouse

Context windows will keep growing. That is good. Larger capacity gives systems more options and reduces some forms of lossy compression.

But a larger warehouse still needs aisles, labels, current inventory, and a workbench.

The agent should not have to rediscover the goal from the transcript, infer policy from examples, compare unlabeled versions of the same fact, or remember which tool call changed the world. Those are failures of interface design.

Context engineering is the discipline of deciding what reality the agent can see and how clearly it can act within it. The work is not to fill the window. The work is to make the task legible.