Context Engineering for Coding Agents: A Field Guide

Ask an experienced developer why a coding agent produced bad code, and the answer is almost never "the model isn't smart enough." It's "it didn't know we moved that logic," or "it used a pattern we deleted six months ago," or "it never saw the config that would have told it not to." The 2026 generation of agents is capable. What they lack, task to task, is the right context in the window at the right moment.

Getting that right has a name now: context engineering. Anthropic frames it as "the natural progression of prompt engineering" — where prompt engineering optimizes the wording of one instruction, context engineering designs the whole set of tokens a model sees at inference time. For a general chat assistant that's a nice abstraction. For a coding agent working in your repository, it's the difference between a teammate who onboarded and one who's guessing.

This is a practical guide to doing it for a real codebase: the layers that make up an agent's context, the budget they all compete for, how to tell which layer is failing when the output is wrong, and how to keep the whole thing from quietly rotting. If you want the conceptual grounding first, our guide to context engineering covers the general discipline; this post is about applying it to coding agents specifically.

The four layers of a coding agent's context#

Everything an agent knows about your repository during a task arrives through one of four layers. They behave differently, cost differently, and fail differently, so it's worth naming them.

flowchart TD
  Task["Task: add rate limiting to the webhook endpoint"] --> Window

  subgraph Window["The context window (finite)"]
    direction TB
    L1["1 - Instructions: system prompt + AGENTS.md / CLAUDE.md"]
    L2["2 - Retrieval: repo search, grep, @-mentions, RAG"]
    L3["3 - Tools: MCP servers + built-in tools"]
    L4["4 - Memory and history: conversation, compaction, session memory"]
  end

  Window --> Output["Generated code + edits"]

1. Instructions — always on. The system prompt your agent ships with, plus the repo instruction files it loads on every session: AGENTS.md for most tools, CLAUDE.md for Claude Code. This layer is for the handful of facts true for every task: how to install, how to run tests, what the agent must never do. Every line here is a line the agent carries through every conversation, whether it's relevant or not.

2. Retrieval — pulled per task. What the agent reads once it starts working: files it greps for, files you @-mention, chunks a RAG index returns, documentation it looks up. This layer is task-specific and, done well, is where most of the useful context comes from — the agent pulls in the webhook handler and the existing rate-limit helper because this task needs them, and nothing else.

3. Tools — definitions always on, results on demand. Every tool the agent can call — built-in ones like file edit and shell, plus any MCP servers you've connected — costs tokens just to describe, before it's ever used. The results come back only when the agent calls the tool. Tools are the only layer that can reach data that changes independently of your repo (a live database schema, the current contents of a ticket) or take actions against other systems.

4. Memory and history — accumulates. The conversation so far, any long-term session memory, and whatever survives compaction when the window fills. This layer grows on its own during a long task, and it's the one most likely to crowd out the others if nothing prunes it.

The instinct is to treat these as independent knobs. They aren't. They all draw down the same budget.

The budget you're actually working with#

A modern coding agent might have a 200,000-token window. That sounds enormous until you account for what's already in it before the agent reads a single line of your code:

The numbers vary by tool and task, but the shape holds: context is a resource you spend, and every layer is spending it. More context is not better context. A window packed to 90% runs slower, costs more, and — the counterintuitive part — often produces worse code, because the model has to locate the one relevant detail inside a wall of marginally relevant text.

This is why the single most common context-engineering mistake in coding setups is pasting things in "to be safe": the entire docs/ folder, six files that might be related, a 600-line rules doc covering every scenario the team ever hit. We wrote about that failure mode specifically in managing AI agent context without the bloat. The fix is almost always to make the big stuff queryable rather than pasted — move it to layer 2 or 3, where the agent pulls only what a task needs.

When the output is wrong, which layer failed?#

Anthropic's engineering team describes four ways context goes bad: poisoning (a wrong fact enters early and gets treated as ground truth), distraction (so much history accumulates the model loses the thread), confusion (irrelevant tools and documents pull the model off-task), and clash (two pieces of context contradict each other). Each maps cleanly to one of the four layers, which makes debugging faster than it sounds.

The habit worth building: when an agent does something wrong, don't just re-prompt. Ask which layer put that idea in its head, and fix the layer. Re-prompting works around a bad context once; fixing the layer stops it recurring for every future task and every teammate.

Setting it up for a real repository#

A workable method, in order:

1. Keep the instruction layer lean. Build command, test command, the two or three hard boundaries, a one-paragraph map of the repo. That's it. If you're adding a fourth procedure to AGENTS.md, that content wants to be a Skill or an MCP tool, not another section the agent re-reads every turn. For a monorepo, a short root file plus a nested AGENTS.md per package beats one long root file — agents read the nearest one first.

2. Make the large, changing stuff queryable. Architecture docs, conventions, API surfaces, the "why is it like this" context — none of it belongs pasted into every prompt. Put it behind retrieval or an MCP server so the agent pulls the slice a task needs. Our MCP documentation server guide goes deeper on that tradeoff.

3. Choose Skill vs. MCP server deliberately. A repeatable procedure whose facts rarely change (your release checklist, how you write a migration) is a Skill. Live data or an action against another system (current schema, cross-repo search, "what conventions apply to this file right now," open a PR) is an MCP server. Putting facts about the current codebase into a static Skill guarantees they go stale.

4. Keep MCP scoped and read-only where you can. Every connected server is code running with the access you grant it and tokens spent on its tool definitions. Connect the two or three that match your workflow, prefer read-only or least-privilege modes, and read MCP security risks before you wire in anything that can write.

5. Keep the retrieved layer fresh. This is the one most teams skip, and it's the one that causes the worst failures.

The stale-context trap#

Of the four failure modes, clash is the one that scales badly. Poisoning, distraction, and confusion mostly hurt the current task. Clash — a doc in context that contradicts the code — is structural, and it gets worse every week you ship.

Here's the mechanism. Your retrieval layer is only as good as what it retrieves. If it's pulling from an architecture page that still describes a service you merged away, or an AGENTS.md that documents last quarter's test runner, the agent now has two sources that disagree and no reliable way to pick the winner. Sometimes it trusts the code. Often it trusts the doc, because the doc reads like an authoritative statement of intent. Either way you've spent tokens making the agent less sure.

This is just documentation drift wearing a new hat. The same gap that has always misled new hires now misleads the agent — and the agent acts on it faster, more confidently, and at higher volume. Living documentation — docs coupled to the code and updated as it changes — was already the fix for the human problem. Coding agents raise the stakes: stale docs don't just cost you a confused onboarding, they teach your agents the wrong patterns and then those patterns land in pull requests.

This is the layer Moxie Docs is built for. It indexes your GitHub repository into living, source-cited documentation, serves your conventions, docs, gaps, and verified commands to coding agents over an MCP server, and opens reviewable Cleanup PRs when the docs fall behind the code. The agent retrieves context that's current and carries a path back to source — instead of a snapshot that quietly went wrong. You can see what the first index finds on your own repo on the free plan, one repository, no card required.

Measuring whether your context is working#

You don't need an eval harness to get signal. A few cheap observations, tracked loosely over a week:

• First-try correctness. How often does the agent's first attempt pass the test suite and follow the convention, without a correction turn? This is the headline number.
• Re-reads. Does the agent grep for the same file three times in one task? That usually means retrieval isn't surfacing it, or history is dropping it.
• Tool-call count. A sudden jump in tool calls to accomplish something simple points at confusion — too many options in the window.
• Convention adherence. Pick five conventions your team actually enforces. Does agent-written code follow them without being told? If not, they're either missing from context or buried where the model isn't weighting them.
• The "wait, that's wrong" rate. How often does a reviewer catch the agent asserting something the code contradicts? Every instance is a clash worth tracing to its source doc.

When a number moves the wrong way, use the layer table above. The point of context engineering isn't a perfect setup on day one — it's a short feedback loop between "the agent did something dumb" and "the layer that caused it is now fixed."

Frequently asked questions#

What is context engineering for coding agents?#

It's the practice of deliberately managing everything a coding agent has in its context window during a task — instruction files, retrieved code and docs, tool definitions, and conversation history — so the agent works from accurate, relevant, current information instead of guessing or acting on stale context. It treats the context window as a finite budget to be spent well, not filled.

How is it different from prompt engineering?#

Prompt engineering optimizes the wording of a single instruction. Context engineering designs the whole system that assembles what the model sees: which files get retrieved, which tools are connected, what survives compaction, how the instruction file is structured. For a multi-step agent working in a repo, that system determines outcomes far more than any single prompt.

How big should my AGENTS.md or CLAUDE.md be?#

Small. It's the always-on layer, so every line taxes every task. Aim for build and test commands, a short repo map, and the few hard boundaries. If a section only matters for one kind of task, it belongs in a Skill or an MCP tool the agent loads on demand, not in the file it re-reads on every turn.

Is a bigger context window the answer?#

No. A larger window raises the ceiling but doesn't fix the underlying problem — models still struggle to find the relevant detail inside a large, noisy context, and a fuller window costs more and runs slower. Curating what goes in beats having room for more.

How do I tell which part of my setup is causing bad output?#

Map the symptom to a layer. Wrong command usually means a stale instruction file. A deleted pattern reappearing means retrieval surfaced old code. The wrong tool getting picked means too many are connected. The agent contradicting the code means a doc in context is stale. Fix the layer, not just the prompt.

The short version#

Coding agents in 2026 fail on context, not capability. That context arrives in four layers — instructions, retrieval, tools, memory — and they all spend the same finite budget, so more is not better. When the output is wrong, trace it to the layer that caused it and fix that layer. Keep the always-on instruction layer lean, make the large stuff queryable, connect MCP deliberately, and — the part that scales worst if you skip it — keep the docs the agent retrieves true to the code. The teams whose agents ship good code aren't using smarter models. They're feeding them a better-engineered context.