Most Claude API integrations underperform not because of the model — but because of a poorly structured system prompt. The system prompt is the primary control layer for every response Claude generates. Get it wrong, and no amount of parameter tuning will fix the output.
This guide covers the core system prompt architecture from the Anthropic Cookbook, including the 5-layer structure, prompt patterns that work, anti-patterns to avoid, and the model selection rules that keep production code maintainable.
All examples come directly from the Anthropic Cookbook: System Prompts & Best Practices.
The 5-Layer System Prompt Architecture
A well-structured system prompt contains five layers, written in this specific order:
| Layer | What It Controls | Example |
|---|---|---|
| 1. Role & Persona | Who Claude is | "A senior Python engineer who favors clean, minimal code" |
| 2. Context & Scope | Domain, user needs, what to avoid | "Answer questions about orders and returns only" |
| 3. Output Format | Structure of responses | "Respond in JSON with keys: summary, confidence, source" |
| 4. Constraints | Hard limits and rules | "Never discuss competitors. Max 4 sentences." |
| 5. Tone & Style | Voice and register | "Friendly, empathetic, and professional" |
Every layer controls a distinct dimension of your output. Skip a layer and the model fills it in unpredictably. The order matters — Claude processes the system prompt top to bottom, so role and scope should establish context before format and constraints narrow it.
A Complete System Prompt Example
Here is a production-ready customer service system prompt from the Cookbook:
SYSTEM = """
You are a helpful customer support agent for Acme Corp.
## Scope
- Answer questions about orders, shipping, and returns.
- Escalate billing disputes by saying: 'I'll connect you with billing.'
- Never discuss competitors.
## Format
- Respond in plain English, 2-4 sentences max.
- If you need an order number, ask for it politely.
## Tone
Friendly, empathetic, and professional.
"""
Notice what each section does: the opening line sets role and company context, ## Scope defines what the agent handles and provides an exact escalation phrase, ## Format specifies response length explicitly, and ## Tone closes with voice guidance. All five layers, clearly organized.
Prompt Patterns That Work
The Cookbook documents five prompt patterns with consistently strong results across use cases.
Be positive, not negative. Frame instructions as what Claude should do, not what it shouldn't. "Respond only in French" outperforms "Do not respond in English" — same instruction, measurably better compliance. When you must prohibit something, always specify the replacement behavior.
Use XML tags for structure. Claude is specifically trained to respect XML-like delimiters. Wrapping instructions in <instructions>...</instructions> and data in <document>...</document> creates clean separation that prevents the model from confusing context with commands. This is especially valuable in RAG applications where retrieved chunks must not be treated as instructions.
Give examples (few-shot prompting). Include 1–3 input/output pairs to demonstrate the exact format you want. This is the most reliable technique for JSON extraction tasks — showing the target structure once is more effective than describing it in prose.
Specify length explicitly. Vague prompts produce variable-length outputs. Write "Respond in exactly 3 bullet points, each under 20 words" instead of "Be concise." Give Claude a measurable target.
Ask for step-by-step reasoning. Adding "Think step by step before answering" to complex tasks dramatically improves accuracy on reasoning-heavy problems. This works because it forces the model to allocate reasoning budget before committing to an answer.
Anti-Patterns to Avoid
The Cookbook documents five common prompt mistakes that consistently degrade output quality:
Saying "don't do X" without saying what to do instead. The model needs a replacement behavior, not just a prohibition. Without it, it will make its own choice about what to do when the forbidden path comes up.
Packing too many instructions into one run-on sentence. Every constraint competes for attention in a dense block of text. Use headers and bullet points to separate concerns — the customer service example above uses ## headers for exactly this reason.
Using ambiguous pronouns. "It," "this," and "that" without clear referents cause the model to make assumptions. Be explicit: name the entity you're referring to every time.
Forgetting to specify output format for structured data. If you need JSON, say so. If you need markdown, say so. If you need a numbered list, say so. Without explicit format instructions, output structure is unpredictable across calls.
Hard-coding model IDs with dates. This is a production maintenance issue, covered in the next section.
Claude Model Selection: Use Aliases, Not Dated Strings
Anthropic maintains non-dated model aliases that always point to the latest stable version of each tier. The current aliases are:
| Model Alias | Best For | Speed |
|---|---|---|
claude-opus-4-6 |
Most capable, long documents, complex reasoning | Slower |
claude-sonnet-4-6 |
Complex reasoning, code generation | Medium |
claude-haiku-4-5 |
Fast tasks, classification, summarization | Fast |
Never hard-code dated strings like claude-sonnet-4-6-20250514 in your code. When Anthropic releases an update, your code automatically benefits if you use the alias — and stays stuck on the old version if you don't.
The correct pattern in Python:
import anthropic
client = anthropic.Anthropic()
message = client.messages.create(
model="claude-sonnet-4-6", # always use the alias
max_tokens=1024,
messages=[
{"role": "user", "content": "Explain RAG in 3 bullet points."}
]
)
print(message.content[0].text)
For AWS Bedrock deployments, the model ID format is different. Prepend global. for cross-region inference endpoints, which Anthropic recommends for production:
| Model | Bedrock ID |
|---|---|
| Opus 4.6 | global.anthropic.claude-opus-4-6-v1 |
| Sonnet 4.5 | global.anthropic.claude-sonnet-4-5-20250929-v1:0 |
| Haiku 4.5 | global.anthropic.claude-haiku-4-5-20251001-v1:0 |
API Key Security: The Rule That Cannot Be Skipped
The Cookbook includes one non-negotiable security rule: never hard-code your API key. Always load it at runtime using python-dotenv:
import os
from dotenv import load_dotenv
import anthropic
load_dotenv() # reads .env into environment
client = anthropic.Anthropic(
api_key=os.environ["ANTHROPIC_API_KEY"]
)
The .env file must be listed in .gitignore. Never commit it. Never log os.environ['ANTHROPIC_API_KEY']. If you accidentally push a key to a public repository, rotate it immediately at console.anthropic.com.
What This Article Covers — And What It Doesn't
This article covers the system prompt architecture, prompt patterns, model selection, and API key security from the Anthropic Cookbook. The full Cookbook goes significantly further across six additional capability areas:
Classification & RAG — text classification pipelines, retrieval-augmented generation grounded in your own documents, and long-document summarization. Each is a self-contained Jupyter notebook.
Tool Use & Integrations — a full customer service agent with function calling and state management, a calculator integration for routing math operations to Python tools, and SQL query generation from natural language.
Third-Party Integrations — Pinecone vector DB for embeddings at scale, Voyage AI embeddings optimized for Claude, and Wikipedia search for real-time grounding.
Multimodal & Vision — sending images to Claude and interpreting results, chart and graph interpretation, and form/document transcription pulling structured data from PDFs.
Advanced Techniques — prompt caching to reduce latency and cost on large system prompts, JSON mode for guaranteed structured output on every API call, automated evaluations using Claude to score other Claude outputs, and Extended Thinking for deeper step-by-step reasoning chains.
Contributing & CI/CD — the full Git workflow, conventional commit standards, pre-commit hooks with Ruff formatting, and the checklist for submitting new recipes to the open-source repository.
Every recipe in the Cookbook is self-contained, copy-paste-ready, and tested from top to bottom in a clean kernel environment. Cell outputs are kept in the notebooks so you can see reference output before running anything.
Quick Reference: System Prompt Checklist
Before deploying any Claude-powered feature, run through this checklist:
- [ ] Does the system prompt define a specific role and persona (not just "assistant")?
- [ ] Is the scope of topics clearly defined — including what Claude should never discuss?
- [ ] Is the output format specified explicitly (length, structure, example)?
- [ ] Are constraints written as positive instructions, not just prohibitions?
- [ ] Is tone and register defined?
- [ ] Are all instructions separated clearly, not packed into run-on paragraphs?
- [ ] Does the code use model aliases, not hard-coded dated strings?
- [ ] Is the API key loaded from environment, never hard-coded?
Every production-ready Claude integration passes this checklist. Every one
The Anthropic Cookbook: System Prompts & Best Practices is a developer's guide to building production-ready AI applications with the Claude API. Includes Jupyter notebooks, Python examples, and copy-paste-ready patterns for classification, RAG, tool use, multimodal, and advanced techniques. Available now — link below.
.webp)
){kind=link}
0 Comments