---
title: "Reusable patterns for structuring Claude agent prompts"
description: "Code-level patterns from a Built-with-Opus hackathon: contract prompts, typed tools, tiered context, plan-then-act, and structured errors."
canonical: https://callsphere.ai/blog/reusable-patterns-for-structuring-claude-agent-prompts
category: "Agentic AI"
tags: ["agentic ai", "claude", "prompt engineering", "tool use", "context engineering", "claude code", "agent patterns"]
author: "CallSphere Team"
published: 2026-04-20T08:46:22.000Z
updated: 2026-06-06T21:47:43.337Z
---

# Reusable patterns for structuring Claude agent prompts

> Code-level patterns from a Built-with-Opus hackathon: contract prompts, typed tools, tiered context, plan-then-act, and structured errors.

By the end of a Built-with-Opus hackathon, five or six patterns kept reappearing across every team's codebase, regardless of what they built. They were not framework features — they were ways of structuring prompts, tools, and context that consistently worked. This post collects the reusable patterns at the code level: the building blocks you can lift into your next Claude Code agent and trust.

These are patterns, not facets of a single system. Each one is independently useful, and together they form a vocabulary for designing agents that stay legible as they grow.

## Pattern 1 — The contract system prompt

Treat the system prompt as a contract with three named sections: **Role**, **Rules**, and **Done**. Role is one or two sentences of identity. Rules is a short numbered list of hard constraints — what the agent must always and never do. Done is an explicit, checkable description of completion. The power of the structure is that it is scannable both for you and, crucially, for the model: when the agent drifts, you can point at the exact rule it violated and tighten that one line rather than rewriting prose.

The anti-pattern this replaces is the stream-of-consciousness system prompt that mixes identity, instructions, examples, and pleading into one wall of text. That style is impossible to debug because you cannot isolate which sentence caused a behavior. The contract structure makes the prompt a maintainable artifact.

## Pattern 2 — Tools as typed, model-facing contracts

Every tool should expose three things written deliberately for the model: a verb-first name, a description that explains *when* to use it (not just what it does), and a strict argument schema with descriptions on each field. The reusable trick is to write the description as guidance: "Use this after X and before Y." The model reads tool descriptions as part of its planning, so a description that situates the tool in a workflow produces far better tool selection than one that merely defines it.

```mermaid
flowchart TD
  A["Incoming request"] --> B["Contract system prompt sets Role/Rules/Done"]
  B --> C["Model plans next step"]
  C --> D{"Which tool fits the workflow?"}
  D -->|Selected by description| E["Typed tool runs, returns structured result"]
  E --> F["Context store compresses + tags result"]
  F --> G{"Done criteria satisfied?"}
  G -->|No| C
  G -->|Yes| H["Structured final output"]
```

A second reusable rule: tool outputs should be structured data, not prose, whenever possible. Returning JSON with named fields lets the model — and your own code — reference results precisely. Returning a paragraph forces the model to re-parse natural language on every subsequent turn, which is both wasteful and error-prone.

## Pattern 3 — The context budget with named tiers

Context is a resource you allocate, not a bucket you fill. The reusable pattern is to tag every item entering context with a tier: `pinned`, `working`, or `archive`. Pinned items (the task, key constraints) survive every turn untouched. Working items (recent tool results) live for a few turns then get summarized. Archive items get a one-line digest and are dropped, retrievable later through a tool. Implement this as a small function that runs before each model call and trims the transcript according to the tags. It is maybe forty lines and it is the highest-leverage code in the whole agent.

The reason this matters is attention. A model reasoning over a context that is ninety percent stale tool output performs worse than one reasoning over a tight, relevant slice — even though the larger context technically "contains more information." Curation beats accumulation.

## Pattern 4 — Plan-then-act for multi-step tasks

For any task with more than two or three steps, prompt the agent to produce an explicit plan as its first action, then execute against it. The reusable structure is: the model writes a short numbered plan to a scratch area, the harness pins that plan, and each subsequent turn references the current step. This does two things — it makes the agent's intentions inspectable before any side effects occur, and it gives the model a stable backbone so it doesn't lose the thread mid-task. With Opus 4.8's stronger planning, the plans are good enough that you can largely trust them while still reviewing for anything destructive.

The pitfall is letting the plan become rigid. Good agents revise the plan when reality disagrees with it. Build in an explicit "revise plan" tool or instruction so the model can adapt rather than stubbornly executing a plan that no longer fits the facts it has discovered.

## Pattern 5 — Skills for know-how, tools for hands

Keep a hard line between capabilities and competence. Tools are the agent's hands — they perform actions. Skills are the agent's know-how — bundles of instructions loaded only when relevant. The reusable discipline is: if you are tempted to stuff domain instructions into the system prompt, ask whether they belong in a skill instead. Anything that applies only to a subset of tasks should be a skill, so it loads on demand and keeps the base prompt lean. This keeps every individual context window focused and your agent broadly capable without being perpetually bloated.

## Pattern 6 — Structured errors over exceptions

The last reusable pattern is the cheapest and most overlooked: never let a tool throw a raw exception into the loop. Catch failures and return them as structured results the model can read — `{ ok: false, error: "rate_limited", retry_after: 30 }`. A model that sees a readable error can decide to wait, try a different approach, or report the problem to the user. A model that sees a stack trace, or worse a crashed loop, can do none of those. Treating errors as data the agent reasons over is what separates a brittle demo from an agent that recovers gracefully.

## Frequently asked questions

### Which pattern should I adopt first?

The contract system prompt and structured errors, because they pay off on the very first task and cost almost nothing. The context-tier pattern matters more as tasks get longer, so add it once you feel context pressure.

### Do these patterns depend on a particular framework?

No. They are structural conventions that work whether you hand-roll the loop or use the Claude Agent SDK. The SDK makes some of them easier to implement, but the patterns themselves are framework-agnostic design choices.

### How do tools and skills avoid overlapping?

A clean test: if it *does* something with a side effect, it's a tool; if it *tells the model how* to do something, it's a skill. Keep that boundary strict and you'll never be confused about where a piece of behavior belongs.

### Won't plan-then-act waste tokens on planning?

A short plan costs a few hundred tokens and routinely saves thousands by preventing the agent from wandering. On any genuinely multi-step task the trade is strongly positive; skip it only for trivially short tasks.

## Bringing agentic AI to your phone lines

CallSphere builds its **voice and chat** agents on exactly these patterns — contract prompts, typed tools, tiered context, and structured errors — so they handle real calls and book work without falling over. See the patterns in production at [callsphere.ai](https://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.*

---

Source: https://callsphere.ai/blog/reusable-patterns-for-structuring-claude-agent-prompts