# Context engineering for AI coding agents: practical guide

URL: https://agentvera.dev/en/blog/context-engineering-for-ai-coding/ · Published: 2026-10-28

Context engineering for AI coding agents: what fills the context, why context rot happens, and techniques that beat prompt tweaking, from scoped rules to subagents.

**In short:**

- Context engineering is choosing which tokens an agent sees on each turn: system prompt, rules files, tool definitions and results, MCP, retrieved files and history, not just the wording of one prompt.
- Models get less reliable as input grows (context rot), so a smaller, sharper context usually beats a cleverer prompt in a bloated session.
- The core techniques: short scoped rules files, just-in-time retrieval, subagents with clean windows, compaction, a codebase map, notes files and small tool output.

**Context engineering is the work of deciding what an AI coding agent sees on each turn: which instructions, rules files, tool definitions, retrieved files, tool results and history are in its context window, and which are left out.** For coding agents it usually matters more than prompt tweaking, because the prompt you type is a small part of what the model reads. Most of the window is filled by rules files, tool output and the conversation so far. Keep that context small and relevant, and you get better results than any rewording of your prompt.

This guide explains what goes into an agent’s context, why long contexts degrade, the techniques that help, and how to tell if they work. Facts about Claude Code and Codex are as of October 2026.

## What context engineering means

Anthropic’s engineering post [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) (September 29, 2025) defines context as the set of tokens included when sampling from a model, and context engineering as curating and maintaining the best set of those tokens during inference.

The difference from prompt engineering is scope and time:

| | Prompt engineering | Context engineering |
| --- | --- | --- |
| What you shape | The wording of instructions | Everything in the window |
| When | Once, while writing the prompt | On every turn of the agent loop |
| Typical levers | Phrasing, examples, format | Rules files, retrieval, tools, compaction, subagents, memory |
| Failure mode | A vague or brittle prompt | A window full of stale, noisy or conflicting tokens |

A coding agent runs a loop: read, call a tool, read the result, decide, call again. Each step adds tokens, and each step re-reads what is already there. That is why the post calls context engineering iterative: the curation happens again every time the agent decides what to pass to the model.

## What goes into a coding agent’s context

Before your first message, and growing during the session:

- **System prompt and built-in tools.** Set by the CLI. You do not control it, but you pay for it on every turn.
- **Rules files.** `CLAUDE.md` for Claude Code, `AGENTS.md` for Codex and many other agents. These load at the start of a session.
- **Tool definitions and MCP.** Every tool the agent can call has a name and description. MCP servers add more. Claude Code defers full MCP tool definitions until a tool is used, so only names and server instructions load up front.
- **Retrieved content.** Files the agent reads, search results, docs it fetches.
- **Tool results.** Test runs, build logs, `git diff`, database queries, page snapshots.
- **Conversation history.** Your messages, the agent’s replies, and every failed attempt.

For a feel of the fixed part: we measured Claude Code’s first request at about 34.4k tokens with a standard setup, and about 13.3k with a lean one (see [our token usage post](/en/blog/claude-code-token-usage/ "Cut Claude Code token usage by 61%")). That baseline is sent again on every turn. For the Claude Code specifics of `/context`, `/compact` and `/clear`, see [the Claude Code context window guide](/en/blog/claude-code-context-window/ "Claude Code context window").

## Why more context is not better: context rot

A context window is a hard limit, but the soft limit arrives earlier. Anthropic’s post describes an “attention budget”: transformers relate every token to every other token, so n tokens create n² pairwise relationships, and each extra token spreads attention thinner. As the window grows, the model’s ability to recall what is in it decreases.

Independent research shows the same. Chroma’s [Context Rot report](https://www.trychroma.com/research/context-rot) (July 14, 2025) tested 18 models and found that performance degrades with input length across all its experiments, even on simple tasks. A few findings that matter for coding:

- Even one distractor, text that looks relevant but is not, lowered accuracy, and the effect grew with input length.
- On a long-memory benchmark, every model did much better with a focused prompt of about 300 tokens than with the full prompt of about 113k tokens.

For a coding agent, distractors are everywhere: an old version of a file read before an edit, a stack trace from a bug already fixed, a rejected approach. A 1M-token window gives room, not immunity.

## Techniques that work

These are the techniques Anthropic’s post describes, mapped to what you do in a coding agent.

### 1. Keep rules files short and scoped

Rules files are paid for in every session, so each line has to earn its place. Claude Code’s [memory docs](https://code.claude.com/docs/en/memory) recommend keeping each `CLAUDE.md` under 200 lines and note that longer files reduce adherence. Instead of one long file:

- Put rules that apply to part of the code in `.claude/rules/` with a `paths` field. They load only when Claude reads or edits a matching file.
- Use nested `CLAUDE.md` files in subfolders. Claude Code loads them on demand when it works in that folder.
- Know that `@path` imports organize a file but do not reduce its cost: imported files load together with the file that imports them.

```markdown
---
paths:
  - "src/api/**/*.ts"
---

# API rules

- Validate every request body with the shared schema.
- Return errors in the standard error format.
```

Codex works the same way with `AGENTS.md`: it reads a global file from `~/.codex`, then one file per directory from the project root down to the working directory, with closer files later so they take precedence. It stops adding files at `project_doc_max_bytes`, 32 KiB by default. Our [CLAUDE.md and AGENTS.md guide](/en/blog/claude-md-agents-md/ "CLAUDE.md best practices") covers what to put in them.

On the content, Anthropic’s advice is to write at the “right altitude”: specific enough to guide behavior, general enough not to hard-code brittle if-else logic. A few canonical examples work better than a long list of edge cases.

### 2. Retrieve just in time

Rather than loading everything up front, keep lightweight references (file paths, function names, links) and let the agent load the content when it needs it. Anthropic gives Claude Code as the example: it uses glob and grep to find files and `head` and `tail` to look at large data without loading all of it. In practice:

- Point the agent at a file or symbol instead of asking it to “look around”.
- Ask for an outline or a line range before a full read of a big file.
- Keep a short map of the repo in the rules file (where the API lives, where tests are) and let the agent fetch the rest.

### 3. Isolate work in subagents

A subagent runs in its own clean context window. It can spend tens of thousands of tokens exploring and return only a condensed summary; Anthropic mentions summaries of often 1,000 to 2,000 tokens. Good candidates are codebase exploration, reading long logs, and a review of the diff in a fresh context.

Subagents are not free. Anthropic’s [multi-agent research system post](https://www.anthropic.com/engineering/multi-agent-research-system) (June 13, 2025) reports that agents use about 4 times the tokens of chat and multi-agent systems about 15 times. What you buy is a clean main thread, not a smaller bill.

### 4. Compact, and clear old tool results

Compaction summarizes a conversation near its limit and continues from the summary. Anthropic calls clearing old tool results one of the safest forms of compaction: the agent rarely needs the raw output of a test run from forty turns ago. On the API side, Anthropic’s [context management announcement](https://claude.com/blog/context-management) (September 29, 2025) reported that context editing, which clears stale tool calls and results, cut token use by 84% in a 100-turn web search evaluation.

In a coding CLI, steer the summary instead of letting it happen at the limit:

```text
/compact Keep the list of files we changed, the failing test and the API decision
```

And when you switch to unrelated work, start a new session instead of compacting the old one.

### 5. Give the agent notes outside the window

Structured note-taking means the agent writes progress to a file and reads it back later. Anthropic’s examples include a `NOTES.md` file and to-do lists. Claude Code’s auto memory works this way: a per-repository `MEMORY.md` index, of which the first 200 lines or 25KB load at the start of each session. For several agents and sessions, a shared project memory goes further; we cover it in [shared memory for AI coding agents](/en/blog/shared-memory-for-ai-coding-agents/ "Shared memory for AI coding agents").

### 6. Use a codebase map instead of blind search

Grep-and-read exploration fills the window with whole files, most of which turn out to be irrelevant. A [codebase map](/en/blog/codebase-map-for-ai-agents/ "Codebase map for AI agents") is an index of files, symbols, imports and tests the agent can query, so it reads a ranked list and an outline first and only then the lines it needs.

### 7. Keep tool output small

Tool results are often the biggest and noisiest part of the window. Anthropic’s [Writing effective tools for agents](https://www.anthropic.com/engineering/writing-tools-for-agents) (September 11, 2025) recommends pagination, range selection, filtering and truncation with sensible defaults, and says Claude Code restricts tool responses to 25,000 tokens by default. You can apply the same idea from the outside:

- Run one test file, not the whole suite.
- Filter logs with `grep` or `tail` before the agent reads them.
- Prefer a focused CLI command over a tool that returns a whole page or table.
- Disable MCP servers a project does not use.

## Measuring context engineering

Without measurement you are back to guessing. Useful signals:

- **The breakdown.** `/context` in Claude Code shows what is using the window by category and which rules and memory files loaded. Check it after a change to your rules files or MCP setup.
- **Tokens per task.** Compare similar tasks before and after a change, not single sessions.
- **Repeated corrections.** If you keep restating a rule, it is either missing from the rules file or buried in it.
- **First-try success.** Fewer follow-up prompts on comparable tasks is the outcome you actually want.
- **Signs of rot.** Re-reading files, forgetting earlier instructions, repeating a rejected approach. When they show up, compact or clear.

Change one variable at a time. Anthropic’s multi-agent post found that token usage alone explained about 80% of performance variance on its BrowseComp evaluation, which is a reminder that more tokens can look like better results; compare cost and quality together.

## A checklist

| Problem | Technique |
| --- | --- |
| Rules ignored, file keeps growing | Shorter rules file, path-scoped rules, nested files |
| Agent reads half the repo first | Just-in-time retrieval, codebase map |
| Research floods the main session | Subagent with a summary |
| Long session, quality dropping | Steered compaction, or a new session |
| Each new session starts blank | Notes or a shared memory file |
| Huge test and build output | Narrow commands, filtered or compressed output |

## Where AgentVera fits

AgentVera runs Claude Code, Codex and other CLI agents side by side in one desktop app. It does not replace the habits above, but several features apply them for every agent you run. All of this is described on the feature pages:

- **[Token savings](/en/features/token-savings/ "Token savings")**: context profiles that shrink the startup baseline, live context size in each pane, auto-compact on by default at a 150k-token threshold using each CLI’s own command, and RTK, which shortens test, build and git output before it reaches the model.
- **[Project map](/en/features/project-map/ "Project map")**: a local index of symbols, imports, tests and files that change together, which agents query through `agentvera-map` MCP tools such as `map_related` and `map_outline`. The AI ROI tab compares conversations that used the map with those that did not, including tokens per task.
- **[Brain](/en/features/brain/ "Brain")**: a project memory built from docs, commits, PRs and agent conversations. Agents search it with `brain_recall` and keep corrections with `brain_remember`; an optional context pack of up to 2,500 characters goes to new agents.
- **Smart tools** for Claude Code: refuse a re-read of an unchanged file, hand over an outline of a big file first, and narrow full test runs to the affected tests.

If you run a single agent in a single terminal, the techniques in this post work fine on their own, and `/context`, `/compact` and a well-kept rules file get you most of the way. AgentVera helps most when you run several agents and want the same context discipline applied to all of them. You can download it and try it on one project.

## Summary

Context engineering is curating what an agent sees on each turn, and for coding agents it beats prompt tweaking because the prompt is a small slice of the window. Longer contexts get less reliable, so keep rules files short and scoped, retrieve just in time, push exploration into subagents, compact with a focus, keep notes outside the window, use a codebase map, and keep tool output small. Then measure: the context breakdown, tokens per task and first-try success tell you whether a change helped.

## Frequently asked questions

**What is context engineering?** Anthropic defines it as curating and maintaining the best set of tokens during inference. For a coding agent that means deciding what goes into the context window on each turn: instructions, rules files, tools, retrieved code, tool results and conversation history.

**How is context engineering different from prompt engineering?** Prompt engineering is about writing and organizing one set of instructions. Context engineering covers everything that enters the window and is repeated on every turn of an agent loop, so it is an ongoing job rather than a one-time draft.

**What is context rot?** The drop in reliability as the input gets longer. Chroma’s July 2025 report tested 18 models and found performance degrades with input length, even on simple tasks. A big window does not remove the effect.

**Does a 1M-token context window make context engineering unnecessary?** No. A larger window gives room, but every token still competes for the model’s attention and is re-sent on later turns. Old exploration and failed attempts make a session slower, costlier and noisier at any size.

**How do I measure whether my context engineering works?** Look at the context breakdown (/context in Claude Code), tokens per task, how often you have to repeat a rule, and how often a task passes on the first try. Change one thing at a time and compare similar tasks.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/