LLM Best Practices

Role Framing

4 min read

View markdown source

Overview

Role framing tells the model what it is and what it does. A clear role narrows the output distribution toward the answers a domain expert would give; a vague role produces vague output. The rules below apply to Claude Sonnet 4.6, GPT-5, Gemini 2.5, and Haiku 4.5 alike. Role framing is the first block in the system prompt skeleton; see system-prompts.

Set the role with “You are X”

The simplest, most reliable opener. Name the role, name the domain, name the audience.

You are a Postgres 17 migration reviewer for a Python service team.
You read migration files and return one of: approve, request_changes,
block. You write for senior engineers, not beginners.

Three sentences fix the model in place. The role, the domain, the audience. Skip any of the three and the model has to guess.

Prime expertise, not a persona

“Expert,” “senior,” “principal” prime calibrated answers in a domain. “Sassy assistant,” “pirate,” “1920s detective” prime tone but degrade accuracy. Pick the prime that matches what you need from the call.

  • For correctness-critical work: “You are a senior engineer with 15 years of experience in .”
  • For tone-critical work (marketing copy, brand voice): a persona prime is appropriate. Be aware it can drift on the technical content.
  • Do not mix the two unless you tested it. “Pirate Postgres expert” returns plausible-but-wrong SQL more often than the plain prime.

The eval set tells you which prime wins on which slice. See evaluation.

State the user the model is writing for

Tone and depth follow the named audience. The model adapts to “for a senior engineer” differently than “for a smart non-technical reader.”

  • “Write for a backend engineer who knows SQL but is new to Postgres.”
  • “Write for a product manager who needs the decision, not the algorithm.”
  • “Write for a Claude Code session that will paste this into a brief.”

If you do not name the reader, the model picks an average reader, and the output is generic.

Demand calibrated confidence

A primed expert can still confabulate. Add the calibration rule to the system prompt so the model labels uncertainty.

When you do not know an answer, say so. Mark uncertain claims with
"I am not certain" and explain what would resolve the uncertainty.
Do not invent function names, file paths, or version numbers.

Calibration is a rule, not a vibe. Pair it with structured output that has a confidence field for high-stakes calls. See structured-output.

Apply the “be concise” rule with bounds

“Be concise” alone is weak; the model still rambles. Replace it with numeric bounds.

  • “Answer in one paragraph, max 80 words.”
  • “Return at most 5 bullets, each at most 12 words.”
  • “Reply with one of: yes, no, unclear. No other text.”

Concrete bounds outperform soft preferences. The model can comply with a number; it cannot reliably comply with an adjective.

Capability is not the same as persona

A persona shapes voice; a capability list shapes behavior. Both belong in the system prompt, but in separate blocks.

  • Role: “You are a code reviewer.”
  • Capabilities: “You can call search, read, and comment. You cannot write to files.”
  • Tone: “Direct. No filler. No emoji.”

Mixing capability into the persona (“You are a powerful code-reviewing AI that can do anything!”) invites overreach. Keep them separate so each block can be reviewed and changed independently.

Defeat sycophancy with explicit anti-rules

Models trained on RLHF default to agreeing with the user. Without a counter-rule, the agent praises bad code, ratifies bad plans, and softens hard answers. Counter it in the system prompt.

Do not flatter the user. Do not say "great question." Do not soften
disagreement. If the user is wrong, say so plainly and explain why.

Anti-sycophancy is a hard rule because it goes against the model’s default behavior. Restate it at the end of the system prompt where the recency bias works for you. See system-prompts.

Refuse drift; restate the role on long sessions

In multi-turn agent loops, the role can fade as the context fills with tool outputs and user back-and-forth. Periodically inject a role refresher into the user message or the next system turn.

  • After every N turns, prepend “Reminder: you are a Postgres migration reviewer. Stay in role.”
  • For planner-executor loops, the executor reads the role from a CLAUDE.md or brief on every step. See claude-code.
  • If the user asks the model to “be your normal self,” refuse; that is a drift attempt.

A consistent role over a 50-turn session takes deliberate maintenance.

Graph View

Backlinks