3. Prompting
A prompt is everything you send to the model before it generates a response.
The model cannot ask clarifying questions or remember previous API calls —
all of its context comes from the messages you provide. Well-structured prompts
produce consistent, predictable outputs; poorly structured ones produce fluent
but wrong ones.
3.1 Message Roles
Every message in the Anthropic Messages API has a role:
-
system — a top-level instruction block that sets the
model’s behaviour, persona, and constraints for the entire conversation.
Sent as a separate parameter, not inside the messages array.
-
user — input from the human turn. Tool results
are also delivered in user turns (wrapped in a
tool_result content block).
-
assistant — the model’s response. In multi-turn
conversations you append the model’s previous responses to the messages
array so the model can see what it already said.
Roles must alternate: user → assistant → user → …
Sending two consecutive user turns or omitting the role causes a validation error.
3.2 System Prompts
The system prompt is the highest-trust instruction in the request. Use it to:
- Define the model’s role: “You are a code reviewer who responds
only with structured JSON.”
- State constraints: “Never suggest code that allocates on the heap.”
- Supply standing context: “The project uses Rust 2021 edition and targets
no_std environments.”
- Set output format: “Respond with a markdown code block followed by
a numbered list of review comments.”
System prompts are good candidates for prompt caching (Chapter 8) because they
are static across many requests in a session.
3.3 Prompt Patterns
Zero-shot — ask directly without examples. Works well for
tasks the model has seen many times in training: summarisation, translation,
simple code generation.
{"role": "user", "content": "Translate this Python function to Rust:\n\ndef add(a, b):\n return a + b"}
Few-shot — supply 2–5 input/output pairs before the
real query. Teaches the model the exact format, tone, or reasoning style you need.
{"role": "user", "content": "Classify: 'The build failed on CI.' -> "},
{"role": "assistant", "content": "bug"},
{"role": "user", "content": "Classify: 'Added dark mode toggle.' -> "},
{"role": "assistant", "content": "feature"},
{"role": "user", "content": "Classify: 'Renamed variable x to count.' -> "},
Chain-of-thought (CoT) — ask the model to reason step by step
before giving a final answer. Add “Think step by step.” or
“Show your reasoning before the answer.” CoT reliably
improves accuracy on arithmetic, logic, and multi-step code tasks.
3.4 Common Failure Modes
-
Vague task description. “Improve this code” is
under-specified. The model will improve it in whatever dimension it finds most
salient, which may not be what you want. Say “reduce allocations while
preserving the function signature.”
-
Missing constraints. If you don’t say what the code
must NOT do, the model is free to do it.
-
Over-long context burying the task. When the actual
question appears after thousands of tokens of background, quality degrades.
State the task first, then supply supporting material.
-
Conflicting instructions. If the system prompt says
“be concise” and the user message says “give a detailed
explanation”, the model has to guess which wins. Make instructions
consistent or explicit about precedence.
-
Assuming the model remembers. Each API call is stateless.
The model has no memory of previous calls unless you include that history in
the messages array.
3.5 References