Context Engineering for Coding Agents (2026 Guide)

Context engineering is "the set of strategies for curating and maintaining the optimal set of tokens (information) during LLM inference."¹ For a coding agent, that means one thing in practice: deciding what the model sees on every single call, not just the first one. A task you kick off with one sentence might take forty model calls before it opens a pull request. Context engineering is what happens across all forty.

This matters because agents fail in a specific, recognizable way. The model isn't too dumb to write the code. It writes code that would be correct in a different repository, ignores a convention you stated twenty turns ago, or re-solves a problem it already solved. Those are context failures, and you fix them by changing what the agent sees.

What context engineering actually is

The term got popular after Andrej Karpathy pushed back on "prompt engineering" as too small a word for what people were doing. His framing: context engineering is "the delicate art and science of filling the context window with just the right information for the next step."² Cognition put it more bluntly, quoted in LangChain's write-up, calling it "effectively the #1 job of engineers building AI agents."³

The core constraint is that attention is finite. Anthropic describes an "attention budget" that models draw on when parsing large volumes of context, where every new token depletes the budget by some amount.¹ That reframes a big context window from an asset into a resource you can waste.

And the degradation is measured, not theoretical. Needle-in-a-haystack benchmarking surfaced what's now called context rot: as the number of tokens in the context window increases, the model's ability to accurately recall information from that context decreases.¹ Some models degrade more gently than others. All of them degrade.

So the goal is not to give the agent everything. Anthropic's guiding principle is to find the smallest set of high-signal tokens that maximize the likelihood of your desired outcome.¹ Curation, not accumulation.

Context engineering vs prompt engineering

Prompt engineering isn't dead and it isn't a rival discipline. It's a subset. Prompt engineering asks how you should phrase this. Context engineering asks what information the model needs access to right now, and it asks that question again on every turn.¹

The practical difference shows up in where your time goes. If you're still tweaking the wording of one instruction while your agent burns half its window on a directory listing it didn't need, you're optimizing the wrong layer. We wrote about that transition specifically in from prompt engineering to context engineering.

The five kinds of context a coding agent needs

Five distinct things compete for the same budget. Naming them separately is useful because teams tend to over-invest in the first one and quietly ignore the last two.

Instructions

This is your AGENTS.md, CLAUDE.md, or rules file. AGENTS.md is "a dedicated, predictable place to provide context and instructions to help AI coding agents work on your project."⁴ It emerged across OpenAI Codex, Amp, Jules, Cursor and Factory, and it's now stewarded by the Agentic AI Foundation under the Linux Foundation.⁴ In monorepos, agents read the nearest file in the directory tree, so the closest one wins.⁴

The thing to internalize is that instruction context loads on every request. A 3,000-token rules file is a 3,000-token tax on every one of your forty model calls. That's the most expensive real estate you own, so it should hold only what the agent genuinely cannot infer from reading the code. For the file-level craft, we have a full breakdown in how to write an effective AGENTS.md.

Repository knowledge

This is where most of the measurable wins live, and it's the layer people neglect because it feels like plumbing.

Sourcegraph built a benchmark for exactly this, CodeScaleBench, which runs the same agent over enterprise-scale tasks under two retrieval configurations: local grep and file reads, versus their MCP server.⁵ Sourcegraph reports that on a Kubernetes monorepo task the baseline agent hit its roughly two-hour timeout without finishing while the MCP run completed it in 89 seconds, and that a cross-file refactor went from 96 tool calls and 84 minutes down to 5 tool calls and 4.4 minutes.⁶

Read those as vendor-reported headline cases, because the benchmark's own published results are more mixed than the blog post suggests. Going through the official results bundle in the CodeScaleBench repo, the baseline configuration actually beats the Sourcegraph one on several suites, including cross-repo tasks, investigation tasks, and the PyTorch set, where baseline scores 0.643 mean reward against 0.080 and 0.458 for the two MCP configs.⁵ Dozens of suite and config combinations are flagged as below their minimum task count, so a lot of the comparisons are underpowered. The repo's own summary warns that mixed scorer-family reward means are convenience summaries, not calibrated comparisons.⁵

The part that does hold up under scrutiny is the failure mode rather than the fix. The Kubernetes task, big-code-k8s-001, is in the published results with a baseline reward of 0.000, failed, alongside three other large-repo tasks that also scored zero.⁵ An agent left to grep its way around a repo that size reliably gets nowhere. Whether a specific vendor's retrieval product is the answer is a separate question from whether retrieval is the bottleneck, and only the second one is settled.

The principle underneath is just-in-time retrieval: let the agent fetch what it needs at the moment it needs it, instead of pre-loading a pile of files that might be relevant.¹ Agents are good at navigating a repo when you give them decent tools for it. They're bad at ignoring 40 files you dumped on them.

Tools and MCP

Tool definitions sit in the window permanently, and tool results land in it every time the agent calls one. Both are context, and both are usually badly designed.

Two rules cover most of it. Keep the toolset small, because a model choosing between eight well-named tools is more reliable than one choosing between forty overlapping ones. And make returns terse by default, because a tool that dumps 4,000 tokens of JSON when the agent needed one field is stealing budget from the actual work. Return the field, offer the full payload behind a second call.

Tests and specs

Here's the layer that gets skipped. A coding agent's real problem is that it cannot tell whether its own output is correct. It can tell whether the output looks like the surrounding code, which is a different and much weaker signal.

Tests and specs fix that. They're the only context that gives the agent a checkable definition of done. An agent with a failing test knows it isn't finished. An agent without one has to guess, and it will usually guess that it's finished. Writing the test first is not a purity exercise here, it's the cheapest way to give the agent ground truth.

Runtime feedback

Test output, type errors, stack traces, linter complaints, actual program output. This is information the agent cannot get by reading source code, which makes it the highest-signal context available.

The mistake is running the checks yourself and pasting a summary. Wire them into the loop so the agent sees raw output and reacts. If you're on Claude Code, hooks turn this from a suggestion into a guarantee: a PostToolUse hook that runs your type checker after every edit feeds real errors back automatically, whether or not the model remembered to check.

Tactics that hold up

Write a lean AGENTS.md

Start smaller than feels right. A workable skeleton:

# Project

Next.js 15 (Pages Router), TypeScript strict, Tailwind. Postgres via Prisma.

## Commands
- `npm run dev` for local dev
- `npm run type-check` must pass before any commit
- `npm test -- <path>` runs one test file

## Conventions
- Components under 250 lines; extract instead of growing
- No `any`. Use `unknown` plus a type guard
- Server-only code in `src/server/`. Never import it from a client component

## Boundaries
- Never edit `src/generated/` (regenerated by `npm run codegen`)
- Never commit to `main`

## Deeper docs (read on demand)
- Auth flow: `docs/auth.md`
- Data model: `docs/schema.md`

Every line answers something the agent can't infer by reading the repo. The commands aren't guessable. The boundaries aren't guessable. "Use TypeScript" is guessable, so it isn't there.

Progressive disclosure

Notice that last section in the skeleton. Deep documentation gets referenced, not inlined. The agent reads docs/auth.md when it's touching auth and never pays for it otherwise.

This is the single highest-leverage change for most repos, because instruction context is the one thing you pay for on every request. Splitting a 3,000-token rules file into a 400-token core plus five linked documents doesn't lose information. It just stops charging you for all of it all the time.

Compaction, notes, and sub-agents

When a session runs long, you have three moves.

Compact. Compress the history into a summary and keep going. If you wait for your tool's automatic compaction to fire, the window is already near full, which means the model has been degrading for a while before anything kicks in. Dex Horthy of HumanLayer runs frequent intentional compaction instead, compressing progress into a Markdown plan and restarting from it, with the explicit goal of keeping context utilization in the 40% to 60% range depending on how complex the problem is.⁷ Working that way, he and a BAML maintainer got two draft PRs ready in about 7 hours, roughly 3 on research and planning and 4 on implementation, adding 35k lines to BAML, a 300k-line Rust codebase Horthy had never worked in and whose language he describes himself as an amateur in.⁷ The loop is research, plan, implement, with compaction between phases.⁷

Write notes. Have the agent keep a scratchpad file outside the window. This is LangChain's "write" strategy, saving context outside the window so it survives a reset.³ A PROGRESS.md the agent updates as it goes means a fresh session picks up where the old one stopped.

Isolate. Give a subtask its own window. A sub-agent reads twenty files, runs six searches, and returns three sentences. The exploration cost stays in its window rather than permanently occupying yours. We covered the mechanics in the Claude Code subagents guide.

LangChain's four strategies are a clean way to remember the whole set: write (save context outside the window), select (pull it in), compress (retain only the tokens required), and isolate (split it up).³

Knowing which of the three moves to reach for is the part nobody spells out, so here's the rule I use.

That last row is the one people get wrong. Compaction summarizes what's in the window, so if an early mistake got baked in, compacting carries it forward in a more confident and less traceable form. Once an agent is wrong about a premise, you want a clean window and a corrected written plan, not a summary of the confusion.

Anthropic published numbers on the compress side that are worth knowing. Context editing alone improved performance 29% on an internal agentic-search evaluation, and pairing it with a memory tool improved it 39% over baseline. On a 100-turn web search evaluation, context editing completed workflows that would otherwise have failed on context exhaustion, using 84% fewer tokens.⁸

Design tools for token efficiency

If you're building MCP servers or custom tools, a short checklist:

• Return the answer, not the payload. Paginate or summarize by default.
• Name tools so a model can pick correctly without reading the description twice.
• Collapse overlapping tools. Two tools that do nearly the same thing produce wrong picks.
• Make errors instructive. File not found: src/uti1s.ts. Did you mean src/utils.ts? saves a turn.

Failure modes and how to spot them

The tell for most of these is repetition. An agent that re-reads the same file, re-asks a question you answered, or re-introduces a bug you already fixed is telling you its window is degraded. That's a compaction signal, not a prompting problem. Our anti-drift workflows piece goes deeper on catching this early.

A minimal workflow

If you want one loop to start with, this is it.

1. Write the check first. A failing test, or a spec precise enough to verify against. The agent now has a definition of done it can't fake.
2. Give it a lean instruction file. Commands, conventions, boundaries. Link out to anything deeper.
3. Let it retrieve. Don't paste files. Give it search and let it find what it needs.
4. Keep runtime feedback in the loop. Type checker and tests run automatically, output goes back to the agent.
5. Compact on purpose. At the end of each phase, write the plan and state to a file, then start fresh from that file.
6. Delegate exploration. Anything that means reading a lot to learn a little goes to a sub-agent.

That's the whole discipline. Everything else is refinement.

When context engineering is the wrong fix

Worth saying plainly, because "curate your context" has become the answer to everything.

Context engineering doesn't help when the task is genuinely beyond the model, when your codebase has no tests and no types so there's no ground truth to feed back, or when the real problem is that nobody has decided what the software should do. Ambiguity in a spec doesn't get fixed by a better rules file.

It also has a cost. Splitting docs, building retrieval tooling, and running compaction discipline is work. On a small project where the whole relevant surface fits comfortably in the window, pasting the three files and moving on is faster and there's no shame in it. The techniques here earn their keep on large repos, long sessions, and tasks that span many files. Below that threshold they're overhead.

The counter-position deserves a fair hearing too. Frontier models keep getting better at ignoring irrelevant context, and some of today's tactics will look like workarounds in two years. That's probably true for the manual parts, like hand-compacting a session. It's much less likely to be true for retrieval quality and for tests as ground truth, since those aren't compensating for model weakness, they're supplying information that doesn't otherwise exist.

FAQ

What is context engineering for coding agents? It's curating and maintaining the optimal set of tokens the model sees during inference,¹ applied to the multi-step loop of a coding agent. In practice you're controlling instructions, retrieved code, tool definitions and results, tests, and runtime output across dozens of model calls per task.

How is it different from prompt engineering? Prompt engineering is a subset. You write a prompt once; context curation repeats each time the agent decides what to pass to the model.¹

Why do coding agents need this more than chatbots? A chat turn is one call with a window you can eyeball. An agent task is many calls, each one inheriting whatever the last one left behind. Errors and clutter compound.

What are the main kinds of context? Instructions, repository knowledge, tools, tests and specs, and runtime feedback. They compete for the same budget.

What is AGENTS.md? A dedicated, predictable place to provide context and instructions to help AI coding agents work on your project.⁴ It's cross-tool and stewarded by the Agentic AI Foundation under the Linux Foundation.⁴

What is context rot? As tokens in the window increase, the model's ability to accurately recall information from that context decreases.¹

Should I put everything in AGENTS.md? No. It loads on every request, so every line is a recurring cost. Keep the core small and link out to documents the agent reads on demand.

What is intentional compaction? Deliberately compressing a long context into a written summary and restarting from it, rather than waiting for automatic compaction. HumanLayer aims to keep utilization in the 40% to 60% range, depending on problem complexity.⁷

How do sub-agents help? They run a subtask in a separate window and return only the result, so exploration cost doesn't permanently occupy the main window.³

What's the highest-value context for correctness? Specs and executable tests, plus runtime feedback. That's ground truth the agent can't invent by reading source.

Where to start

Pick the cheapest change first. Open your rules file and cut it in half, moving the detail into linked documents. That single edit refunds budget on every request for the rest of the project.

Then add one failing test before your next agent task and watch what changes. An agent that can check its own work behaves differently from one that can't, and the difference is more obvious than any prompt tweak you'll make this month.

If you want the wider picture on how these pieces fit into a working setup, our AI developer workflows hub collects the tooling, and Claude Code and Cursor both ship most of what's described here out of the box.

Sources

Footnotes

1. Effective context engineering for AI agents, Anthropic Engineering. ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹

2. Andrej Karpathy on context engineering, X. ↩

3. Context Engineering for Agents, LangChain. ↩ ↩² ↩³ ↩⁴

4. AGENTS.md, the open format for guiding coding agents. ↩ ↩² ↩³ ↩⁴ ↩⁵

5. CodeScaleBench, Sourcegraph, including the official results bundle generated 2026-03-12. ↩ ↩² ↩³ ↩⁴

6. Context Engineering: A Practical Guide for AI Agents, Sourcegraph, including CodeScaleBench results. ↩

7. Advanced context engineering for coding agents, HumanLayer. ↩ ↩² ↩³ ↩⁴

8. Managing context on the Claude Developer Platform, Anthropic. ↩