Prompt Engineering for Claude System Prompts

Prompt engineering for Claude system prompts means structuring the instructions you send in the system field so the model reliably behaves the way your application needs — consistent tone, correct output format, safe boundaries, and predictable tool use. The system prompt is not a suggestion Claude reads once; it's the frame that shapes every turn of the conversation, so small wording choices compound across thousands of requests.

This guide covers the concrete techniques that actually move the needle: how to structure a system prompt, what to put in it versus the user message, how to constrain output format, and how to debug a prompt that isn't working. These apply whether you're calling the Anthropic API directly or through a proxy like SubToAPI.

What belongs in a system prompt vs. a user message

A common mistake is stuffing everything into the system prompt, including information that changes every request. Keep the split clean:

System prompt — things that stay constant across the conversation:

• Role and persona ("You are a billing support assistant for Acme SaaS")
• Output format rules (JSON schema, markdown, length limits)
• Behavioral constraints (what not to do, how to handle edge cases)
• Tool usage policy (when to call a tool vs. answer directly)

User message — things that change per request:

• The actual question or task
• Dynamic context (current date, user data, retrieved documents)
• Conversation-specific instructions

If you find yourself regenerating the system prompt string on every call because it contains a timestamp or a user's name, move that data into the user message instead. System prompts should be cacheable and stable.

Structure the system prompt like a spec, not a paragraph

Claude responds better to structured instructions than to a wall of prose. Use headings and lists inside the system prompt itself:

You are a support assistant for a project management tool.

## Scope
- Answer questions about features, billing, and account settings
- Do not give legal, tax, or medical advice
- If asked about pricing, always point to the current plan page

## Response format
- Keep answers under 150 words unless the user asks for detail
- Use markdown lists for multi-step instructions
- Never use emoji

## Escalation
If the user is angry, mentions a refund, or asks for a human,
respond with empathy and include the phrase "I'm connecting you
with our support team" exactly once.

This structure does two things: it gives Claude clear sections to reference internally, and it makes the prompt easy for you to maintain as rules change.

Be explicit about what "good" looks like

Vague instructions produce vague compliance. "Be concise" is weaker than "Responses should be 2-4 sentences unless the user asks a multi-part question." "Be professional" is weaker than "Avoid contractions, do not use exclamation points, address the user formally."

When output format matters — especially for programmatic consumption — show the exact shape you want:

Always respond with valid JSON matching this shape:
{
  "intent": "billing" | "technical" | "general",
  "summary": "one sentence",
  "needs_escalation": boolean
}
Do not include any text outside the JSON object.

Claude follows concrete schemas far more reliably than descriptions like "return structured data."

Use negative instructions sparingly, and pair them with alternatives

Telling the model what not to do is useful but incomplete on its own. "Don't discuss competitors" leaves Claude guessing what to say instead. Pair every constraint with a fallback:

Do not discuss or compare competitor products. If asked, say:
"I can only speak to our own product's features — happy to help
with that."

This pattern — constraint plus scripted fallback — eliminates a lot of the unpredictable behavior teams see when they only list prohibitions.

Put examples where they help most

Few-shot examples are powerful but expensive in tokens. For system prompts, one or two high-quality examples of the exact output format usually outperform five mediocre ones. If your task has multiple distinct output types (e.g., classification vs. summarization), give one example per type rather than one generic example repeated.

For longer example sets, consider whether they belong in the system prompt at all — sometimes it's cheaper and clearer to put a short set of examples in the first user message instead, especially if they're only needed occasionally.

Order matters

Claude weighs instructions throughout the system prompt, but placement still affects emphasis. Put the role definition first, critical safety constraints near the top, and formatting details toward the end. If one rule is the single most important thing (e.g., "never reveal API keys in responses"), state it plainly near the top and consider repeating it briefly near the end as a final check.

Debugging a system prompt that isn't working

When Claude ignores or inconsistently follows a rule:

1. Check for conflicting instructions. A rule buried in paragraph three can contradict something stated earlier. Read the prompt as if you were the model, top to bottom.
2. Reduce scope. If a prompt tries to cover ten behaviors at once, split it into a shorter core prompt and handle edge cases with few-shot examples instead.
3. Test with adversarial inputs. Try the exact phrasing users will use to break the rule, not just the happy path.
4. Use the /docs/messages reference to confirm you're passing system as a top-level parameter, not embedding it in the first message — this is a common integration mistake that silently weakens instruction-following.

Versioning and testing in production

Treat system prompts like code: version them, diff them, and test changes against a fixed set of example inputs before shipping. A prompt that works for 20 manual tests can still regress for inputs you didn't think to try. If your application calls Claude through SubToAPI, usage metadata in the dashboard lets you see token counts and request patterns per API key, which helps spot when a prompt change unexpectedly increases response length or triggers more tool calls than before. See /docs/quickstart to get an API key running, and /docs/tools if your system prompt needs to describe available tools.

Good system prompts are iterative. Start structured and explicit, test against real traffic patterns, and tighten the wording only where you see actual failures — not hypothetical ones.

Questions

Should the system prompt or the first user message contain instructions? Stable, conversation-wide rules (role, format, constraints) belong in the system prompt. Anything that changes per request — specific questions, dynamic data, one-off instructions — belongs in the user message.

How long should a Claude system prompt be? As long as it needs to be to remove ambiguity, but no longer. A tightly structured 300-word prompt with clear headings usually outperforms a 1,500-word prompt with repeated or vague instructions.

Do system prompts work differently when streaming responses? No — the system prompt shapes the full response the same way regardless of whether you request it as a single payload or stream it; see /docs/streaming for how streaming affects response handling, not prompt behavior.