System prompts and roles

System or user? A rule of thumb

Ask one question: will this be true for every request? If yes, it goes in the system prompt. If it changes from one request to the next, it goes in a user message.

The split pays off in code. You write the system prompt once, as a constant: a variable you set once and never change. Every request reuses it word for word. So every reply works from the same rules. When the voice guidelines change, you edit one string.

There's a second reason. Models are trained to treat the system prompt as the developer's instructions. They keep following it throughout a conversation. That makes it the natural home for rules that shouldn't drift.

import requests

SYSTEM = """You write product descriptions for Trailhead Outfitters, an outdoor clothing brand.
Readers are hikers comparing gear on their phones. Voice: plain, warm and specific.
Never promise delivery dates. Format: one paragraph of 60 to 90 words."""

def describe(product, notes):
    response = requests.post(
        "https://api.anthropic.com/v1/messages",
        headers={"x-api-key": "added-by-the-academy-server", "anthropic-version": "2026-10-21"},
        json={
            "model": "claude-opus-5-5",
            "max_tokens": 1000,
            "system": SYSTEM,
            "messages": [
                {"role": "user", "content": f"Write a description for the {product}.\n<notes>\n{notes}\n</notes>"},
            ],
        },
        timeout=60,
    )
    response.raise_for_status()
    text = ""
    for block in response.json()["content"]:
        if block["type"] == "text":
            text += block["text"]
    return text

products = {
    "Ridgeline Fleece": "280 g recycled polyester, two zip pockets, packs into its own pocket",
    "Summit Rain Shell": "3-layer waterproof fabric, pit zips, hood fits over a climbing helmet",
}
for product in products:
    print(product)
    print(describe(product, products[product]))
    print()

The roles and their rules

The messages list reads like the script of a play: each line says who's speaking. It follows four rules:

1. The first message must have the role "user".
2. Turns alternate between "user" and "assistant". If you send two user messages in a row, the API combines them into one turn.
3. An "assistant" message holds something the model said in an earlier turn. You add one when you continue a conversation. The Conversations and memory lesson covers that in depth.
4. The last message is normally a user message: the thing you want answered now.

Break the first rule and the API refuses the request. It sends back the status code 400, which means "bad request." It also sends an error message that says what's wrong. Run this to see it:

import requests

response = requests.post(
    "https://api.anthropic.com/v1/messages",
    headers={"x-api-key": "added-by-the-academy-server", "anthropic-version": "2026-10-21"},
    json={
        "model": "claude-opus-5-5",
        "max_tokens": 1000,
        "messages": [
            {"role": "assistant", "content": "Hi! How can I help?"},
            {"role": "user", "content": "Write a tagline for a rain jacket."},
        ],
    },
    timeout=60,
)
print(response.status_code)
print(response.json()["error"]["message"])

This cell has no raise_for_status() on purpose. That way you can read the error instead of stopping on it.

What about a greeting your app shows on screen before the user types? That's display text. It doesn't belong in messages as the first turn.

Watch out: Older tutorials end the list with a half-written assistant message, such as {"role": "assistant", "content": "{"}, to force the reply to start a certain way. That trick is called prefilling. Current Claude models reject it with a 400 error. Ask for the format in your instructions instead. The Structured output lesson shows how to guarantee JSON.

messages = [{"role": "user", "content": "Hi"}, {"role": "assistant", "content": "Hello"}, {"role": "user", "content": "Bye"}]
print(messages[-1]["role"])

What a system prompt can't do

A system prompt is like a staff handbook. It steers behavior strongly, but it's still a set of instructions, not a lock. Three limits matter:

• It isn't enforcement. The model follows its system prompt the vast majority of the time, not every time. A user can also try to talk it out of a rule. So rules that must hold, such as a character limit or a banned word, should also be checked in code. You did this in the Phase 0 capstone, the ad-copy reviewer.
• It isn't secret. Users can often get a model to repeat or paraphrase its instructions. Never put API keys, passwords or private customer data in a system prompt.
• It isn't the place for per-request details. If each request's material goes in the system prompt, you must rebuild the system prompt on every call. You also lose the clean split between the brief and the job ticket.