Context Engineering for Coding Agents

Context engineering is the practice of deciding exactly which tokens a coding agent sees at the moment it generates a change: the instructions, the repository knowledge, the tool results, the tests, and the feedback from running the code. It is the successor discipline to prompt engineering. Where prompt engineering asks how to phrase a single request, context engineering asks a broader question that Anthropic frames directly: what configuration of context is most likely to produce the behavior you want, curated fresh on every step of an agent's loop.

That distinction matters more for coding agents than for any other kind of assistant. A one-shot chat completion reads a prompt and answers once. A coding agent strings together dozens or hundreds of model calls: it reads files, edits them, runs commands, reads the output, and decides what to do next. Every one of those calls draws from a finite context window, and the quality of what lands there determines whether the agent writes a correct change or a plausible-looking wrong one.

What context engineering is

Anthropic defines context engineering as "the set of strategies for curating and maintaining the optimal set of tokens (information) during LLM inference." The key word is maintaining. Prompt engineering is largely static: you write a good prompt once and reuse it. Context engineering is iterative, because the curation phase happens every time the agent decides what to pass to the model on the next step. A useful way to hold the difference: prompting is a writing skill, and context engineering is an architecture skill. Prompting decides how you ask. Context engineering decides what the agent knows, sees, and remembers at the moment it acts. For a coding agent working across a large repository, most of what matters is the second question, because the model is fixed for the duration of a task and the context is the variable you actually control.

The constraint that makes this a discipline is the context window. It is finite, and models degrade as it fills, a pattern often called context rot: signal gets diluted, earlier instructions get crowded out, and the agent loses the thread. So the job is not to stuff the window with everything that might be relevant. It is to find, in Anthropic's phrasing, "the smallest possible set of high-signal tokens that maximize the likelihood of some desired outcome."

The kinds of context a coding agent needs

Context for a coding agent is not one thing. It arrives from several sources, each with its own failure mode, and engineering it well means treating each deliberately.

Instructions

The system prompt and any agent configuration files (the CLAUDE.md, AGENTS.md, or rules files a repo ships) set the standing behavior: coding conventions, the commands to run, what to avoid. The common mistake is pitching instructions at the wrong altitude. Too vague and the agent guesses; too prescriptive and you have written brittle if-then logic that breaks on the first unanticipated case. Good instructions are clear and specific enough to constrain behavior without hardcoding every branch.

Repository knowledge

The code itself is the largest and least tractable body of context. A serious codebase does not fit in any context window, so the agent needs a way to pull the right slices on demand: the file it is editing, its direct dependencies, the relevant config, a similar pattern used elsewhere. Retrieval that drags in loosely related files spends budget for little signal. Precise retrieval, guided by structure like imports and directory layout, is what lets an agent reason about a million-line repository through a small window.

Tools and MCP

Tools are how an agent reaches beyond its own text: reading files, running tests, querying a database, driving a browser. The interface matters as much as the capability. A tool that returns a wall of noisy output burns context; a well-designed tool returns token-efficient, high-signal results. This is where the Model Context Protocol comes in, and it earns its own section below.

Tests and specifications

This is the kind of context most teams underuse. A specification states what the change is supposed to do before it is built. A test encodes that intent in a form the agent can execute and check against. Both give the agent a target that is external to its own reasoning, which is exactly what a probabilistic system needs to avoid confidently building the wrong thing.

Runtime feedback

The final kind of context is what happened when the code ran: the test result, the stack trace, the screenshot of the rendered UI, the error from the failed request. This is the only category the agent cannot produce by reading. It has to come from executing the change in a real environment and feeding the observed behavior back in. An agent without runtime feedback is writing with its eyes closed.

Principles for engineering context well

Across those five kinds, a few principles hold consistently.

Optimize for signal, not volume. More context is not better context. Every token that does not help the current step is diluting the ones that do. The discipline is subtractive: what is the minimum the agent needs to get this step right?

Retrieve just in time. Rather than pre-loading everything a task might touch, keep lightweight references (file paths, identifiers, table names) and let the agent fetch the full content when it actually needs it. This mirrors how a human engineer works: you open files as the change requires them, not the whole codebase up front.

Manage long horizons deliberately. Real coding tasks outrun a single context window. Anthropic describes three complementary techniques: compaction (summarizing older history so it stops consuming budget), structured note-taking (writing durable state to an external file the agent can re-read), and sub-agents (delegating a focused sub-task to a fresh context so the main thread stays clean).

Give the agent a way to be wrong safely. The most valuable context is often a signal that the current path is failing, delivered early enough to change course. That is what tests and verification provide, and it is the hinge of the rest of this guide.

For a broader treatment of these tradeoffs in a coding setting, Sourcegraph's practical guide to context engineering is a good companion read.

Tools and MCP: how agents pull context on demand

Most of a coding agent's high-value context is not in the prompt. It lives in systems the agent has to reach into: the file system, the test runner, the browser, the database, the issue tracker. The Model Context Protocol, introduced by Anthropic in late 2024 and now stewarded under the Linux Foundation, is the open standard that makes those connections uniform. Instead of a custom integration per tool, an agent (the MCP host) talks to any number of MCP servers through a single protocol, and each server exposes its data and actions in a way the agent can call.

MCP is, in effect, the plumbing of just-in-time context. An MCP server for a browser lets the agent open a page and read what rendered. A server for a test framework lets it run a suite and read the results. Because the surface is standardized, the same server works across Claude Code, Cursor, Codex, and the 40-plus agents that speak MCP. The design question for any MCP tool is the one from the principles above: does it return token-efficient, high-signal context, or does it flood the window with noise? We go deeper on wiring verification into agent tools this way in the testing layer for AI coding agents.

The highest-value context is a checkable definition of correct

Here is the gap in most context-engineering setups. Teams invest heavily in the first three kinds of context, better instructions, sharper retrieval, more tools, and treat tests and runtime feedback as downstream concerns that happen after the agent is done. That ordering is backwards for a system whose defining weakness is producing confident, plausible, wrong output. A coding agent is a probabilistic generator: left to reason purely from code and instructions, it will sometimes build something that reads correctly and behaves incorrectly. The only reliable defense is a definition of correct that is external to the agent's own reasoning and that it can check against as it works. Two forms of context supply exactly that.

Specifications are the first. Spec-driven development, formalized by open toolkits like GitHub's Spec Kit, puts a written specification at the center of the workflow: you describe what to build, refine it through structured phases, and hand the agent that artifact as context before it writes a line. As GitHub's own writeup puts it, each phase produces a Markdown artifact that feeds the next, giving the agent structured context instead of ad-hoc prompts. The spec tells the agent what correct means at the level of intent.

Tests are the second, and they are stronger, because a test is a specification the agent can execute. A prose spec still has to be interpreted; a test authored from that intent turns correct into a pass or fail the agent can run on demand, read, and act on. That is why tests are among the highest-density context you can put in a repository: they encode intent, they are checkable, and they live in the same git history as the code they guard. We go deeper on this in tests as context for coding agents.

Verification output is context too

Specs and tests define correct. Runtime feedback tells the agent whether it hit the definition, and that feedback is context the agent cannot generate by reading. When an agent edits a UI, the honest signal is not the diff; it is what the page actually did when it rendered and a user flow ran against it. Feeding that observation back into the agent's context closes the loop between generation and verification. Without it, an agent can pass its own tests and still ship a broken product, because it never saw the real behavior.

This is the structural role Shiplight plays in context engineering. Shiplight is the verification platform for AI-native development. It installs into the coding agent as an MCP server plus skills, one line for Claude Code, Cursor, Codex, VS Code, and 40-plus agents, and supplies both kinds of high-value context above.

For the definition of correct, the agent uses /shiplight create-yaml-tests to walk the app and author end-to-end tests from intent. Those tests are readable YAML, not brittle selectors, and they live in your own git repository next to the code, so they travel with the codebase as durable, checkable context rather than sitting in a vendor cloud. For runtime feedback, the agent uses /shiplight verify to open a real browser after an edit and observe what actually rendered, and /shiplight fix to reproduce a failure, root-cause it, and report a genuine bug rather than quietly editing the test to pass. The verification output flows straight back into the agent's context through MCP, where it can act on it.

The payoff of engineering this last mile is concrete. Teams that wire verification into the agent loop reach reliable end-to-end coverage roughly ten times faster with near-zero maintenance, because the tests self-heal in a real browser and surface heals as reviewable pull request diffs rather than silent rewrites. One team's Head of QA went from spending around 60 percent of their time maintaining Playwright tests to close to zero within a month. For the wider picture of how this fits an agent-first workflow, see the AI-native development lifecycle and our guide to adding testing to AI coding tools like Cursor, Copilot, and Codex.

Key Takeaways

• Context engineering is curation under a budget. The job is to find the smallest set of high-signal tokens that produce the right change, not to fill the window.
• A coding agent draws on five kinds of context: instructions, repository knowledge, tools and MCP, tests and specs, and runtime feedback. Each needs its own deliberate handling.
• The highest-value context is a checkable definition of correct. Specs state intent; tests make that intent executable, so the agent can verify its own work instead of guessing.
• Runtime feedback cannot be read, only observed. What actually happened when the code ran is context the agent has to be given, ideally in real time through MCP.
• Shiplight supplies both. Tests authored from intent that live in your repo, and real-browser verification output the agent can act on, delivered through an MCP install.

Frequently Asked Questions

What is context engineering for coding agents?

Context engineering for coding agents is the practice of curating exactly which tokens the agent sees on each step of its loop: the instructions, repository files, tool results, tests, and runtime feedback. It is the successor to prompt engineering. Prompt engineering asks how to phrase one request; context engineering asks what configuration of information across an entire agent run is most likely to produce a correct change.

How is context engineering different from prompt engineering?

Prompt engineering is largely static and concerns a single model call: you write one good prompt and reuse it. Context engineering is iterative and concerns an agent that makes many calls, curating what to pass to the model fresh on every step. Prompting is a writing skill; context engineering is an architecture skill for managing memory, retrieval, tools, and feedback within a finite context window.

What are the main kinds of context a coding agent needs?

Five: instructions (system prompts and rules files), repository knowledge (the code, retrieved just in time), tools and MCP (how the agent reaches external systems), tests and specifications (a checkable definition of correct), and runtime feedback (what happened when the code ran). Most teams over-invest in the first three and under-invest in the last two.

Why are tests the highest-value context for a coding agent?

Because a test is a specification the agent can execute. A prose spec still has to be interpreted, but a test authored from intent turns "correct" into a pass or fail the agent can run, read, and act on. Tests encode intent, are checkable on demand, and live in the same git history as the code.

How does verification feedback fit into context engineering?

Runtime feedback is the one kind of context an agent cannot produce by reading; it has to be observed by running the change. Shiplight supplies it by letting the agent verify UI changes in a real browser and feed the observed behavior back through MCP, so the agent acts on what actually happened rather than on what it assumed the code would do.