Prompt and Context Design for Claude Coding Agents

Two teams give Claude the same coding task on the same model and get wildly different results. The usual reason isn't the prompt's wording — it's what's in the context window and what isn't. Context design is the most underrated lever in agent engineering. A million-token window doesn't save you; it just gives you more rope. The skill is deciding, every turn, what the model needs to see and what would only distract it.

This post is a practical guide to that decision. We'll cover what belongs in context, what to deliberately leave out, how to budget a window, and how retrieval fits in. The throughline: context is a curated working set, not a dumping ground.

Key takeaways

• Context is a working set — include only what the current sub-goal needs.
• Always include the goal, the definition of done, and the relevant code; rarely the whole repo.
• Leave out stale tool output, unrelated files, and verbose logs — they crowd out signal.
• Budget the window into fixed (instructions, plan) and fluid (current files, recent results) regions.
• Use retrieval to pull code in on demand rather than pre-loading everything.

What always belongs in context

Some things earn a permanent seat. The system instructions and the agent's identity stay throughout. So does the definition of done — the agent must keep its success condition in view or it drifts. The running plan belongs here too: a compact statement of strategy that anchors long runs. And the immediately relevant code — the specific files and symbols the current sub-goal touches — must be present, or the model will hallucinate APIs that don't exist.

The mistake teams make is stopping at "relevant code" and interpreting it generously. Relevant means the function being changed and its direct collaborators and tests — not the entire module, and definitely not the whole repository. Generosity here is exactly what poisons the window.

What to deliberately leave out

Just as important is the negative space. Leave out files the agent isn't working on right now, even if they might matter later — you can retrieve them when the time comes. Leave out raw, verbose tool output once it's been acted on; keep a one-line summary instead. Leave out earlier reasoning that has been superseded by the current plan. Every token of noise competes with signal for the model's attention.

The diagram below shows the decision an effective context engine makes for each candidate piece of information before a turn. Run everything through this filter and the window stays lean.

flowchart TD
  A["Candidate info"] --> B{"Needed for current sub-goal?"}
  B -->|No| C["Exclude or evict"]
  B -->|Yes| D{"Already acted on?"}
  D -->|Yes| E["Replace with summary"]
  D -->|No| F{"Verbose?"}
  F -->|Yes| G["Compress, keep signal"]
  F -->|No| H["Include in full"]
  E --> I["Assemble window"]
  G --> I
  H --> I

Budgeting the window: fixed versus fluid

Think of the context window as two regions. The fixed region holds things that persist across turns: system instructions, the definition of done, the plan, and durable project conventions. The fluid region holds the current working set: the files under edit, the most recent tool results, and the last few turns of action. Fluid content rotates in and out as the agent moves through sub-goals.

Allocating explicitly helps. You might reserve a slice of the budget for fixed instructions and let the rest flex for fluid content, evicting oldest-first when you approach your soft limit. The exact split matters less than the discipline of having one — drifting into "keep everything" is the failure mode.

A useful mental model is a soft limit well below the model's hard ceiling. If your window can technically hold a million tokens, target a working budget far smaller and treat crossing it as a signal to compress, not as headroom to fill. Agents that run near a soft limit they actively defend stay fast and coherent; agents that fill the window just because they can degrade slowly and pay for every wasted token on every subsequent turn. The cost is cumulative — a bloated turn doesn't just cost once, it taxes the rest of the run.

Retrieval as the alternative to pre-loading

The instinct to dump the whole codebase into context comes from a fear of missing something. Retrieval dissolves that fear. Instead of pre-loading, give the agent a search tool and let it pull in code exactly when a sub-goal needs it. This keeps the baseline window small and means the model only pays attention to code it actively chose to read.

# Agent retrieves on demand instead of pre-loading
hits = search_code("def parse_date")
# -> returns 2 matches with file paths
content = read_file(hits[0].path)
# only now does parser.py enter context

This on-demand pattern scales to large repositories that could never fit in a single window, and it naturally keeps context relevant: the agent reads what it needs, when it needs it, and you summarize or evict afterward.

Retrieval quality, though, depends on giving the agent good search primitives. A grep-style exact-match search and a symbol-aware search cover most coding needs; a semantic search over docs or commit history helps for fuzzier "where is this handled?" questions. The point is that retrieval is only as good as what the agent can ask for. Invest in the search tools and the agent's context stays both small and correct — it pulls precisely the function it needs instead of loading a whole file to find one line, then carrying the rest as dead weight.

A worked contrast

Consider an agent fixing a date-parsing bug. The naive approach loads the whole utils package, the full test suite, and every prior log. The disciplined approach loads the failing test, the one function it exercises, and the running plan — then retrieves neighbors only if the fix turns out to need them. Same model, same task; the second agent is faster, cheaper, and far less likely to wander.

Common pitfalls

• Dumping the repo. A big window invites loading everything; resist it. Pre-loading buries the relevant code in noise.
• Hoarding tool output. Keeping full logs after you've acted on them wastes the budget. Summarize and move on.
• No fixed region. Letting instructions and the plan rotate out causes drift. Pin them.
• Ignoring retrieval. Pre-loading instead of searching doesn't scale past one window. Let the agent fetch on demand.
• Stale plans. Carrying a plan the agent has outgrown misleads it. Update or replace it as the work evolves.

Context design is curation under a budget: keep the goal, the plan, and the code in active use; summarize what's been acted on; retrieve the rest on demand; and treat every excluded token as a feature, not a loss.

Frequently asked questions

If the window is a million tokens, why not load everything?

Because attention is finite even when capacity is large. Irrelevant content competes with relevant content for the model's focus, slows the run, and raises cost. A lean, curated window consistently outperforms a stuffed one on the same model.

How do I decide what's relevant each turn?

Anchor on the current sub-goal. Include the goal, the plan, and the specific code and tests that sub-goal touches; exclude everything else and retrieve it only if the work expands to need it.

Where does retrieval beat pre-loading?

Whenever the codebase is larger than the working set, which is almost always. Retrieval keeps the baseline window small and lets the agent pull in code precisely when a sub-goal demands it, instead of paying upfront for code it may never read.

The right context, on every conversation

CallSphere applies this same context discipline to voice and chat — giving each agent exactly the customer history and tools the moment needs, nothing more, so responses stay sharp and fast. See it live at callsphere.ai.

Source & attribution: This is an independent, original explainer inspired by Anthropic's coverage on the Claude blog. Claude, Claude Code, Claude Cowork, Claude Opus, and the Model Context Protocol are products and trademarks of Anthropic. CallSphere is not affiliated with or endorsed by Anthropic.