Claude Agent Patterns: Prompts, Tools, and Context (Claude Coding Benchmarks)

Once you've built a working coding agent, the question shifts from "does it run?" to "why does it stay sharp on one task and fall apart on another?" The answer is almost always structure — how you shape the prompts, design the tool surface, and manage context. These are the reusable patterns that separate agents that top benchmarks from agents that flail. None of them require a better model; they're engineering choices you make in your harness.

This post catalogs the patterns I reach for on every Claude coding agent, with the reasoning behind each. Treat it as a checklist of design decisions, not a tutorial — you can apply any of these to an agent you already have.

Key takeaways

• Structure prompts as role + constraints + definition of done, not a wall of instructions.
• Design tools to be orthogonal and high-leverage; fewer, sharper tools beat many overlapping ones.
• Use the plan-then-act pattern to force exploration before editing.
• Manage context with summarize-and-evict so long runs stay coherent.
• Make tools return structured, actionable results, not raw dumps.

Pattern 1: structure the system prompt in layers

A sprawling system prompt is a common failure mode. Claude follows instructions best when they're organized into clear layers: identity (who the agent is), environment (the repo, the stack, conventions), constraints (what it must never do), and the definition of done (the objective success condition). Keep each layer short and unambiguous.

The single highest-value line in any coding agent's prompt is the definition of done. "The task is complete only when pytest exits zero and no new lint errors are introduced" gives the model a crisp termination condition. Without it, the agent guesses when to stop and often stops too early. State the success test in machine-checkable terms whenever you can.

Pattern 2: design an orthogonal tool surface

Tools are the agent's vocabulary. The best surfaces are small and orthogonal — each tool does one thing, and no two tools overlap. A coding agent rarely needs more than read, search, edit, shell, and test. Adding a dozen specialized tools usually hurts: the model spends reasoning budget choosing among them and picks wrong more often.

The flowchart below shows how a well-designed surface routes a typical sub-goal. Notice that search comes before read, and edit is always followed by test — those orderings are conventions you encourage through tool descriptions and the system prompt.

flowchart TD
  A["Sub-goal selected"] --> B{"Know the file?"}
  B -->|No| C["search_code"] --> D["read_file"]
  B -->|Yes| D
  D --> E["edit_file"]
  E --> F["run_tests"]
  F --> G{"Green?"}
  G -->|No| C
  G -->|Yes| H["Next sub-goal"]

When you add a tool, ask: does this let the agent do something it genuinely couldn't before, or does it just slice an existing capability differently? If it's the latter, don't add it.

There's a related anti-pattern: building a tool that does too much. A single "do_everything" tool with a mode parameter forces the model to reason about modes inside arguments, which it does poorly. Prefer a few named tools with obvious purposes over one parameterized monster. The model's tool-selection is strong when names map cleanly to intents and weak when the real choice is buried in a string field. Naming is part of the interface — search_code and read_file are self-documenting in a way that file_op(mode=...) never is.

Pattern 3: plan, then act

Coding agents that edit on their first instinct tend to thrash. The plan-then-act pattern fixes this: instruct the model to first produce a short, explicit plan — which files it will inspect and what it suspects is wrong — before it touches anything. You can enforce this softly in the prompt ("explore and state a plan before editing") or hard, by gating edit tools until a plan has been emitted.

This pattern maps directly to how the strongest benchmark runs behave: they spend the early turns reading and forming a hypothesis, then make surgical edits. The plan also becomes a compact artifact you can keep in context as a north star, so the agent doesn't lose track of its own strategy ten steps later.

A subtle but powerful refinement is to make the plan revisable. Real debugging surfaces surprises — the failing test points somewhere unexpected. Rather than forcing the agent to march down a now-wrong plan, instruct it to update the plan when an observation contradicts it. The artifact stays in context, but it's a living document. Agents that can revise their plan recover gracefully from wrong first guesses; agents locked into an initial plan thrash when reality disagrees.

Pattern 4: return structured tool results

How a tool answers shapes what the model does next. A test runner that returns 3,000 lines of raw output forces the model to re-parse failures every turn. A test runner that returns a structured summary — "2 failed, 47 passed; failing assertions: ..." — hands the model exactly what it needs to act. Invest in your tool return formats; they are part of the prompt.

{
  "passed": 47,
  "failed": 2,
  "failures": [
    {"test": "test_parse_date",
     "error": "AssertionError: expected 2026, got 2025"}
  ]
}

This is the same principle that makes a good REST API pleasant: return the signal, not the noise. The model treats your tool result as ground truth, so make the truth easy to act on. A good heuristic: if a human engineer would have to scroll or re-parse to find the actionable bit, your tool is returning too much. Extract the failing assertion, the changed line, or the matching symbol, and lead with it.

The same logic applies to search and read tools. A search tool that returns full file bodies forces the model to skim; one that returns matched lines with a few lines of surrounding context lets it decide what to read in full. Push the parsing work down into the tool, where it's deterministic and cheap, rather than spending model reasoning on it every turn.

Pattern 5: summarize and evict to control context

Even with a million-token window, an unmanaged context degrades. The summarize-and-evict pattern keeps runs healthy: after a tool result has been acted on, replace its full text with a one-line summary in the history, and drop file contents the agent no longer needs. The running plan and the current failing test stay; the 800-line file you read twenty turns ago does not.

The table below contrasts the naive approach with the disciplined one. The difference compounds: on a forty-turn task, a managed context stays focused while an unmanaged one drowns in its own history.

Common pitfalls

• Vague definition of done. If the agent can't tell when it's finished, it stops early or loops. Make completion machine-checkable.
• Tool sprawl. Too many overlapping tools degrade tool-selection accuracy. Prune to the orthogonal core.
• Editing before exploring. Skipping the plan step leads to thrash. Force a hypothesis first.
• Raw tool dumps. Returning unstructured output makes the model re-parse every turn. Summarize at the tool boundary.
• Never evicting. Hoarding every observation poisons long runs. Evict what's been used.

Reliable agent behavior is a property of structure: layered prompts, an orthogonal tool surface, plan-before-act discipline, structured results, and an actively managed context window.

Frequently asked questions

How many tools should a coding agent have?

Usually five or fewer for the core loop: search, read, edit, shell, and test. Add specialized tools only when they unlock a genuinely new capability, because each extra tool dilutes the model's selection accuracy.

Should I force a planning step or just suggest it?

Suggesting it in the prompt works for simple tasks; hard-gating edit tools until a plan exists is more robust for complex ones. Start with the prompt-level nudge and escalate to a hard gate if you see the agent thrashing.

Does the 1M-token window make context management unnecessary?

No. A large window lets you hold more, but unmanaged context still degrades coherence and inflates cost. Summarize-and-evict keeps the agent focused on what currently matters regardless of window size.

Agentic patterns, applied to conversations

CallSphere builds these same patterns — sharp tools, plan-before-act, structured results — into voice and chat agents that handle real customer requests end to end. Hear them in action 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.