Context Engineering for Coding Agents

TL;DR: Context engineering is deciding what a coding agent sees on each turn, in what order, and what it never sees. It is not prompt engineering with a new name. Context is finite and shared, so every line of instruction competes with file contents, tool output and conversation history for the same budget.

What is context engineering, exactly?

Context engineering is deciding what goes into a model's context window on a given turn: instructions, file contents, tool results, the conversation so far, and everything you deliberately keep out.

The most-cited definition is Anthropic's, from an engineering post published 29 September 2025, Effective context engineering for AI agents. It defines the term as "the set of strategies for curating and maintaining the optimal set of tokens (information) during LLM inference, including all the other information that may land there outside of the prompts." That last clause is the whole idea: most of what a coding agent reads is not something you typed.

Be clear about what that definition is. It is one vendor's framing, nearly a year old, from a team that also sells an agent. There is no standards body and no cross-vendor agreement. I checked: the string "context engineering" appears zero times across Claude Code's documentation on memory, best practices, context window, costs and extensions, and zero times in either of Cursor's two rules pages, all read 28 August 2026. The essays use the term; the documentation describing the mechanisms does not.

How is context engineering different from prompt engineering?

Prompt engineering is about the instruction you write. Context engineering is about the entire window, most of which you did not write.

Anthropic's post draws the line the same way, describing prompt engineering as "methods for writing and organizing LLM instructions for optimal outcomes" and the newer term as "the natural progression of prompt engineering." In a single-turn chat the two nearly coincide. In an agent running for an hour across hundreds of tool calls, the prompt is a rounding error.

The practical test: if your improvement is a better sentence, that is prompt engineering. If it is a decision about whether a thing enters the window at all, that is context engineering. Moving a 400-line style guide out of an always-on file and into a glob-scoped rule changes no word of instruction. It changes what the model sees on most turns.

Why is context a budget rather than a bucket?

Because it is finite and shared, and because quality degrades before capacity runs out.

Anthropic's post describes the failure as context rot: "as the number of tokens in the context window increases, the model’s ability to accurately recall information from that context decreases." Its conclusion is the line to tape to your monitor: context "must be treated as a finite resource with diminishing marginal returns."

So the discipline is not more context. It is deciding what earns its place. Every line in an always-on instructions file is one you have chosen to charge on every request, forever, for the behaviour it buys. Some are worth it. Most are not. Anthropic's summary of the goal: "finding the smallest possible set of high-signal tokens that maximize the likelihood of some desired outcome."

The same caution applies to context-window sizes and per-token costs, which I am deliberately not printing here. They change in weeks, differ per model and per plan, and a stale number is worse than none.

What belongs in always-on context, and what should be fetched on demand?

Always-on context is for what is true on every task. Everything else should load when it becomes relevant. The table below summarises Claude Code's extensions page, read 28 August 2026.

Anthropic's best-practices page states the rule directly: "CLAUDE.md is loaded every session, so only include things that apply broadly." For what only matters sometimes, it points you at skills, which load on demand.

The sorting question, from the same page, is one line: "Would removing this cause Claude to make mistakes?" If the honest answer is no, cut it. Not is this true, not is this nice to know. Below is a file that passes that test.

# Build and test
- Package manager is pnpm. Never run npm or yarn.
- `pnpm verify` runs typecheck + lint + unit tests. Run it before saying a change is done.
- Integration tests need `docker compose up -d db` first. They fail with ECONNREFUSED otherwise.

# Conventions that differ from defaults
- Dates are stored as UTC epoch milliseconds, never ISO strings. See `src/lib/time.ts`.
- Server actions live in `actions/`, one file per domain. Do not add API routes for them.

# Gotchas
- `src/generated/` is machine-written. Edits there are overwritten on the next build.
- The staging env var names differ from production. Check `.env.example` before assuming.

Notice what is absent: no directory listing, no dependency inventory, no "write clean code". Anthropic's exclude column names "Self-evident practices like" that one, alongside "File-by-file descriptions of the codebase", and its /doctor checkup proposes cutting directory layouts and dependency lists from a checked-in file. For more on that file specifically, see CLAUDE.md best practices.

How do you scope rules by glob so they load only when relevant?

By putting the scope in the rule file's frontmatter, so it loads only when a matching file enters the picture. Claude Code uses a paths field in a file under .claude/rules/; its documentation says such rules "only load into context when Claude works with matching files, reducing noise and saving context space", triggering when Claude reads a matching file rather than on every tool use.

---
paths:
  - "src/api/**/*.ts"
  - "src/api/**/*.test.ts"
---

# API conventions

- Every handler validates input with the shared zod schema before touching the DB.
- Errors return the `{ code, message }` envelope from `src/api/errors.ts`. Never throw raw strings.
- New endpoints need an entry in `openapi.yaml` in the same commit.

Cursor's project rules live in .cursor/rules/ and must use the .mdc extension: its reference page is blunt that a plain .md file there "is ignored by the rules system because it has no frontmatter". The frontmatter is exactly three fields; below is the glob-scoped combination.

---
globs: src/components/**/*.tsx
alwaysApply: false
---

- Use named exports, not default exports.
- Co-locate styles in a module CSS file next to the component.
- Prefer composition over prop drilling.

Two Cursor caveats: its documentation is split across two pages that do not cover the same ground, with the reference page the less complete one, and rules reach only the agent. "Rules only apply to Agent (Chat)." Tab completion and Inline Edit do not read them. Both, plus the legacy .cursorrules situation, are in Cursor rules and prompt templates.

Why does a giant always-on instruction file make the agent worse?

Because it dilutes the instructions that matter, and because all of it competes with the code the agent needs to read.

This is not a theory I am floating. Anthropic's best-practices page says it outright: "Bloated CLAUDE.md files cause Claude to ignore your actual instructions!" With a diagnostic attached: if the agent keeps doing something you have a rule against, the file is probably too long and the rule is getting lost.

The emphasis trap follows. People answer a skipped instruction by shouting, in bold, in caps, with IMPORTANT. Anthropic's guidance is to emphasise a single line, because "If you emphasize many lines, none of them stands out." A file where every rule is critical has no critical rules.

Cursor's page lists bloat patterns that generalise: copying entire style guides (use a linter), documenting every possible command, writing for rare edge cases, duplicating what is already in the codebase. Its advice on when to add a rule is one sentence: "Start simple. Add rules only when you notice Agent making the same mistake repeatedly."

Two more failure modes. Contradictions are the quiet one, because Claude Code concatenates files across its four scopes in load order rather than overriding, so a stale user-level preference sits in the window next to the project rule it contradicts, and the docs warn that Claude may pick one arbitrarily. And imports do not help: the documentation is explicit that splitting a file into @path imports "helps organization but doesn't reduce context, since imported files load at launch." Four files of 100 lines cost what one file of 400 costs.

What actually survives compaction?

Some things reload from disk. Some are summarised into prose and lose their detail. Knowing which separates a harmless compaction from one that quietly drops your build command.

Compaction, in Anthropic's words, is "the practice of taking a conversation nearing the context window limit, summarizing its contents, and reinitiating a new context window with the summary." Per Claude Code's context-window documentation, read 28 August 2026:

• Re-injected from disk: the system prompt and output style, the project-root CLAUDE.md and unscoped rules, auto memory, and any plan written in plan mode.
• Reloaded only on a trigger: rules with paths frontmatter, and nested CLAUDE.md files. They return when the agent next reads a matching file, not before.
• Partially recovered: files the agent read or edited, of which it re-reads up to five, most recently modified first. A file over 5,000 tokens returns as a path reference rather than content. Invoked skill bodies come back capped, at 5,000 tokens per skill and 25,000 total.
• Summarised away: everything you said in conversation, and any context a hook added earlier.

That last bullet bites, and the fix is boring: if it matters, write it into a file rather than saying it. You can also steer a pass with /compact focus on the auth bug fix, or leave standing instructions in your project file:

# Compact instructions

When you are using compact, please focus on test output and code changes

When should you start a fresh session instead of continuing?

When the task changes, and when you have corrected the agent more than twice on the same problem.

Anthropic's best-practices page gives the second as a hard rule. Past two corrections on one issue, "the context is cluttered with failed approaches", and the fix is to clear and restart with a prompt that incorporates what you learned: "A clean session with a better prompt almost always outperforms a long session with accumulated corrections."

That is the part people resist. A long session feels valuable because it contains work. What it contains is three failed approaches, the files that led to them, and your increasingly irritated corrections, all competing with the fourth. A workable habit:

1. New task, new session. Old conversation crowds out the files you need next.
2. Two strikes, then restart. Write the lesson into the prompt and start clean.
3. Name sessions before you clear them, so you can resume the one you want rather than keeping ten alive out of fear.
4. Route side questions away from history. Claude Code's /btw answers never enter conversation history, so you can check a detail without paying for it on every later turn.

The same instinct applies to ordinary chat work: when to start a new chat versus keep going.

How do you give an agent a way to find information instead of pre-loading it?

By giving it pointers and tools rather than contents, and letting it fetch what it needs.

Anthropic calls this just-in-time context: rather than pre-processing everything up front, agents "maintain lightweight identifiers (file paths, stored queries, web links, etc.) and use these references to dynamically load data into context at runtime using tools." Claude Code runs a hybrid, dropping CLAUDE.md in up front while using glob and grep on demand. Cursor reaches the same principle from the other side, advising you to "Reference files instead of copying their contents", which also stops them going stale. In practice, write rules that point:

---
paths:
  - "src/services/**/*.ts"
---

# Service conventions

- The canonical example is `src/services/billing.ts`. Read it before writing a new service.
- The error envelope and retry policy are defined in `src/services/_shared/`. Do not reinvent them.
- Public API surface is generated from `openapi.yaml`. Regenerate with `pnpm gen:api`; never hand-edit.

Three lines, no copied code, and it stays correct when billing.ts changes.

The other half is delegation. Subagents run in their own context window and return a summary, which is why Anthropic's best-practices page calls them one of the most powerful tools available, on the grounds that "context is your fundamental constraint". Its blog post sketches the saving: a subagent may burn tens of thousands of tokens exploring and return a summary "often 1,000-2,000 tokens" long. That is a September 2025 illustration, not a measured constant, but the ratio is the point. See understanding an unfamiliar codebase for the exploration pattern.

How do you keep tool output small?

By filtering before the output reaches the model, preferring narrow tools over broad ones, and not connecting tools you do not use.

Tool results are the largest uncontrolled input in most agent sessions. A test run, a log file, a query and a full-file read all dump their whole output into the window, and it stays there.

1. Filter at the source with a hook. Claude Code's cost documentation gives the canonical example: instead of the agent reading a 10,000-line log to find errors, a hook greps the error lines first, "reducing context from tens of thousands of tokens to hundreds". The same trick works on test output.
2. Prefer a CLI to an MCP server when both exist. The same page notes that tools like gh and aws are "still more context-efficient than MCP servers because they don't add any per-tool listing".
3. Disconnect servers you are not using. MCP tool names load at session start, so idle servers are a standing charge for capability your agents never reach for.
4. Keep tool sets small and unambiguous. Anthropic names this as a top failure: "One of the most common failure modes we see is bloated tool sets that cover too much functionality or lead to ambiguous decision points about which tool to use." If a human engineer cannot say which tool applies, the agent will not do better.

Stale results deserve the same scrutiny: "once a tool has been called deep in the message history, why would the agent need to see the raw result again?"

What context engineering cannot do

It cannot make an agent obey, and it cannot be done once.

Most content on this topic skips the honest limit. Claude Code's memory documentation states that it treats these files "as context, not enforced configuration", that content is "delivered as a user message after the system prompt", and that there is "no guarantee of strict compliance". Cursor makes no obedience claim either.

That has a design consequence. If a step must happen every time, a rules file is the wrong mechanism and a deterministic one is right: a hook on a lifecycle event, a pre-commit check, a CI gate. Instructions raise the probability of the behaviour you want; only enforcement guarantees it. If you are fighting a rules file that keeps getting ignored, the diagnosis in why the agent ignores your rules file is usually mechanism, not wording.

Second, nothing here is set-and-forget. Rules describing a directory you renamed are worse than no rules, because the agent trusts them. Prune on a schedule and delete anything that fails the removal test.

Third, much of the interesting behaviour is undocumented. Neither vendor publishes how instruction files are weighted against conversation, or what compaction discards in a given run. Where I described behaviour above, a vendor page said so and I dated it. Everything else is observation, and deserves that label when you pass it on.

A context audit you can run this week

Nothing here needs a purchase. Work through it in order.

1. Measure before you cut. Run /context and read what is actually loaded, including which memory files were picked up. Most people are surprised by at least one entry.
2. Apply the removal test line by line. For every line in your always-on file, ask whether deleting it would cause a mistake. Delete everything that fails.
3. Move the sometimes-relevant material out. Anything scoped to one directory becomes a glob-scoped rule; anything multi-step becomes a skill.
4. Check for contradictions across scopes. Read your user-level file and your project file side by side and delete the loser rather than letting the model choose.
5. Disconnect unused tool servers, then re-run /context and compare.
6. Add one filtering hook for your noisiest output, usually the test runner.
7. Set a clearing habit for a week: new task, new session; two strikes, restart.

Success is not a smaller file. It is the agent no longer making a mistake you had already written a rule about.

Where Prompt Architects fits, and where it does not

Straight answer, because the mechanics above are things you do in your own repository. Prompt Architects does not write your CLAUDE.md, your .claude/rules/*.md, or your .cursor/rules/*.mdc files. There is no Cursor extension and no rule-file generator.

What we do run is an MCP server at https://mcp.prompt-architects.com/mcp that Claude Code, Cursor, Claude Desktop, Claude.ai, Codex and Codex CLI can connect to, per our integrations page, with OAuth sign-in or a personal access token. It exposes prompt tools named improve, refine, shorten and enhance, so the instruction you hand the agent gets tightened without leaving the editor, plus a saved library so the version that worked is the one you reuse next month.

That is the honest boundary. Context engineering is mostly a repository discipline. We help with the sentence, not the filesystem.