Claude Code patterns: structuring prompts, tools, context

After you have shipped a few Claude Code agents, you stop thinking in one-off prompts and start thinking in patterns — the small, repeatable ways of shaping prompts, tools, and context that consistently produce reliable behavior. These patterns are not magic incantations. They are structural habits, and most of them come down to the same idea: give the model clearly bounded, named regions to read, the way HTML gives a browser a clean tree to render. This post collects the patterns I reach for on every build.

Pattern 1: the system prompt as a contract, not a pep talk

The weakest system prompts are motivational ("You are a brilliant senior engineer who cares deeply about quality"). The strongest ones are contracts: they state the agent's role in one line, then enumerate concrete operating rules, then declare the output shape. Adjectives do nothing; rules do everything.

Structure the prompt in labeled sections — role, constraints, available tools, output format — each under its own heading so the model can find them. Put hard prohibitions in their own block ("Never modify files under /generated"). Keep it stable across turns; volatile, task-specific detail belongs in the user message, not the system prompt. A contract you can read top to bottom in fifteen seconds is usually the right length.

Pattern 2: design tool surfaces to be narrow and obvious

Tools are an API you are exposing to a probabilistic caller, so design them like one. Prefer a few sharp tools over many overlapping ones. Give each a description that says what it does, what it returns, and when to use it — written for the model, not for a human reading docs. Make arguments unambiguous: a single path string beats a target that might be a path, a glob, or an id depending on mood.

The anti-pattern is the kitchen-sink tool with a mode flag that changes its behavior. Splitting fileOp(mode) into readFile, writeFile, and deleteFile makes each call self-describing and lets the permission layer treat them differently. The map below shows how a clean tool surface routes a request.

flowchart TD
  A["Claude reads task + tool defs"] --> B{"Which capability?"}
  B -->|Inspect| C["readFile / search (safe)"]
  B -->|Change| D["writeFile (gated)"]
  B -->|Verify| E["runTests (shell)"]
  C --> F["Labeled result block"]
  D --> F
  E --> F
  F --> G["Claude decides next step"]
  G --> B

Pattern 3: lay out context like a document tree

The context you assemble each turn should read like a well-formed document, not a pile of strings. Open with the standing instructions, then the current task, then the live working set — files, prior tool results, relevant skill content — each wrapped in a named, bounded block. The model spends fewer reasoning tokens orienting itself when the layout is predictable, which leaves more for the actual problem.

A reliable ordering is: system contract, task, retrieved/loaded knowledge, working files, recent results, and finally the explicit next-step question. Keep that order stable across turns so the model learns where to look. When you inject a freshly-read file, wrap it the same way every time. Consistency of structure is itself a form of prompting.

Pattern 4: make results carry their own metadata

Every tool result should announce what it is. A file block names its path and includes line numbers. A search result lists matches with file and line, not a wall of concatenated snippets. A command result separates exit code, stdout, and stderr. This metadata is what lets the model act precisely on the next turn instead of re-deriving context.

The same discipline applies to truncation. When you cut a large result, leave a visible marker ("[showing first 200 of 3,400 lines]") so the model knows there is more and can ask for it. Silent truncation is a classic bug: the agent confidently reasons over data it cannot see was incomplete.

Pattern 5: separate planning from acting

For non-trivial tasks, a two-phase pattern pays off: first ask the agent to produce a short plan as structured text, then execute it. The plan turns vague intent into a checklist the agent can work against and you can inspect before any tool fires. It also gives the model a place to surface unknowns ("I need to confirm where auth middleware lives") before it commits to edits.

You can enforce this with a hook or simply with a system-prompt rule: produce a plan, wait, then act. Either way, the value is that planning is cheap and reversible while acting touches the world. Front-loading the thinking reduces the number of expensive wrong turns.

Pattern 6: compact deliberately, not desperately

Long sessions outgrow the window. The pattern that keeps them coherent is deliberate compaction: when history gets large, summarize completed work into a dense "progress so far" block and drop the verbatim turns it covers. Because every region was named and bounded, you know exactly which spans are safe to fold. The agent keeps a faithful summary of what it did and a clean window for what is next.

Do this before you are forced to, not after. An agent that compacts at eighty percent of budget stays sharp; one that waits until it is overflowing makes the model reason over a window that is mostly noise. Compaction is a maintenance habit, like garbage collection, not an emergency measure.

Frequently asked questions

How long should a system prompt be?

Long enough to state the role, the hard rules, the tool list, and the output format — and no longer. If you cannot skim it in about fifteen seconds, it probably mixes stable contract material with task-specific detail that belongs in the user message instead.

Few broad tools or many narrow ones?

Favor a handful of narrow, single-purpose tools with unambiguous arguments. Narrow tools are self-describing, easier for the model to choose correctly, and let the permission layer treat reads and writes differently, which broad mode-flag tools cannot.

What does "context like a document tree" mean in practice?

It means assembling each turn's context in a stable order with named, bounded regions — contract, task, knowledge, files, results, next-step question — and wrapping every injected artifact consistently, so the model spends fewer tokens figuring out what it is looking at.

Why plan before acting?

Because planning is cheap and reversible while acting changes real files. A short structured plan turns vague intent into an inspectable checklist, surfaces unknowns early, and reduces the number of costly wrong edits the agent makes.

Bringing agentic AI to your phone lines

These prompt, tool, and context patterns are exactly what CallSphere uses to keep its voice and chat agents reliable on live calls — narrow tools, structured context, plan-then-act — so every caller is answered and work gets booked 24/7. See it 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.