Give Claude a role and a tone

Tell Claude who it is and how to sound, and the same question produces a different answer. A role decides which facts surface and how deep the explanation goes. A tone decides how the answer reads. Both are instructions you write once, and Claude applies them to every reply.

Why does giving Claude a role change the answer?

Claude does not have one fixed way of answering. Without direction it picks a sensible middle: medium depth, neutral phrasing, broad audience. That middle is rarely the best fit for your task. A role narrows the target.

Anthropic's own prompting guidance puts it plainly: setting a role in the system prompt focuses Claude's behaviour and tone, and even a single sentence makes a difference. The reason is mechanical. A role like "senior security engineer" pulls security-shaped facts towards the front of the answer. The same question asked of a "patient teacher" pulls explanations and analogies forward instead. You are not changing what Claude knows. You are changing what it reaches for first.

Think of it like asking a question in a room full of experts. Address the question to the lawyer and you get caveats and precedent. Address it to the coach and you get a plan and encouragement. The question is identical. The framing changes the answer.

This is also why a role is cheaper than a longer prompt. A page of detailed instructions tries to spell out every preference. A good role compresses many of those preferences into one identity, and Claude unpacks them from the role. "You are a copy editor" already implies short sentences, active voice, and attention to consistency, so you do not have to list each one.

What is the difference between role and tone?

People treat "role" and "tone" as one thing. They are not, and separating them gives you more control.

You can mix them freely. A "staff engineer" who is "blunt and concise" gives terse, senior-level review notes. A "staff engineer" who is "warm and explains every step" gives a teaching walkthrough of the same code. Set each dial on purpose.

Show, do not tell

The fastest way to see the effect is to ask one question two ways. Try both of these in the Claude Code CLI on the same file.

The security reviewer flags token handling, missing expiry checks, and timing leaks. The performance engineer flags redundant lookups, blocking calls, and allocations in a hot path. Same file, same "what is wrong" question, two different lists. The role decided which problems counted as problems.Common gotchaThe flip side: a sharp role also hides whatever falls outside its lens, so a "security reviewer" can walk past a glaring correctness or performance bug.For a final pass, drop the role and ask in a neutral voice so nothing gets filtered out.

How do I write a role that steers the answer?

A vague role barely moves the answer. "Be an expert" tells Claude nothing it was not already trying to do. A useful role names three things: the expertise, the priorities, and the audience.

Break down why that works:

• Expertise: "staff backend engineer ... payments service" sets the depth and the lens.
• Priorities: "correctness and data safety over style" tells Claude what to lead with and what to skip.
• Audience: "mid-level engineer who knows the language but not this codebase" sets how much to explain.
• Order: "bugs and risky assumptions first" shapes the structure without a separate format instruction.

Each clause is a constraint, and Claude is built to follow explicit constraints. Anthropic's guidance is to add the reason behind an instruction, because Claude generalises from the explanation. "Prioritise data safety because this handles live transactions" steers harder than "prioritise data safety" alone.

A good test for a role is the one Anthropic suggests for any prompt: show it to a colleague who lacks context and ask them to act on it. If they would not know what to lead with or who they are writing for, Claude will not either. Tighten the role until a person could follow it.

Tune the tone the same way

Tone responds to the same specificity. Naming a feeling works, but naming a behaviour works better, because a behaviour is checkable.

A useful trick from Anthropic's prompting docs: tell Claude what to do, not what to avoid. "Write in flowing prose paragraphs" steers more reliably than "do not use bullet points", because the first describes a target and the second describes a void. The model fills a target more consistently than it avoids a void.

One more lever: the style of your own prompt rubs off on the answer. Write the request in terse, plain sentences and the reply trends terse and plain. Write it in heavy markdown with many headers and the reply trends that way too. If the tone keeps drifting, match your prompt's style to the output you want.

Anchor the voice with an example

A description tells Claude the target. An example shows it. When a role keeps producing something close to what you want but not quite, give one short before-and-after example, and the gap usually closes. Anthropic's guidance calls examples one of the most reliable ways to steer tone and structure.

This works because an example removes ambiguity that prose leaves open. "Be concise" could mean one sentence or one paragraph. A sample answer settles it. Add the example right after the role:

One example is enough to fix the format. Two or three help when the task has variety, like commits that span features, fixes, and chores. Keep the examples short. A long example burns context and can make Claude copy its incidental details rather than its shape. For more on steering with examples, see few-shot prompting.

Where do I put the role in Claude Code?

A role typed into a single message lasts for that message. For anything you repeat, put the role somewhere persistent so you stop re-typing it. Claude Code gives you four homes, each with a different lifespan and scope.

In a single message

Type the role at the top of your prompt. It applies to that turn and fades as the conversation moves on. This is right for a one-off lens you do not plan to reuse.

For one CLI invocation

The Claude Code CLI takes a flag that appends text to the system prompt for that run only.

claude --append-system-prompt "You are a release-notes writer. Turn the git log into changelog entries grouped by feature, fix, and chore." -p "summarize commits since v2.3.0"

--append-system-promptA CLI flag that adds your text to the end of Claude Code's default system prompt for the current run, without removing the built-in instructions keeps Claude Code's normal coding behaviour and adds your persona on top. There is a matching --append-system-prompt-file that loads the same text from a file, which is handy for a long role you reuse in scripts.

If you want to replace the default prompt entirely rather than add to it, the CLI also takes --system-prompt (and --system-prompt-file). Replacing the whole prompt drops Claude Code's built-in software-engineering instructions, so reach for it only when Claude is not doing engineering at all. The replace and append flags can be combined; the two replace flags are mutually exclusive.Common gotchaThe names are one word apart, so it is easy to type --system-prompt when you meant --append-system-prompt. The first silently throws away Claude Code's built-in coding instructions, and the symptom is confusing: Claude suddenly stops reading files, running tests, and editing the way it used to, with no error.Default to the append flag for a persona, and keep --system-prompt only for the rare case where Claude should not be an engineer at all.

As a saved output style

When you keep re-prompting for the same voice every session, promote it to an output styleA Claude Code feature that modifies the system prompt to set a persistent role, tone, and output format you can switch between. An output style modifies the system prompt directly and applies to every response until you switch it off. Claude Code ships three beyond the default: Explanatory adds teaching "Insights" while it codes, Learning asks you to write small pieces yourself, and Proactive makes Claude act before it asks.

A custom output style is a Markdown file with frontmatter, saved at ~/.claude/output-styles for you alone or .claude/output-styles for the project.

---
name: Diagrams first
description: Lead every explanation with a diagram
keep-coding-instructions: true
---
 
When explaining code, architecture, or data flow, start with a Mermaid diagram showing the structure, then explain in prose.

Set keep-coding-instructions: true when you are changing how Claude communicates but still want it coding normally. Leave it out when Claude is doing something other than engineering, like acting as a writing assistant, so the built-in coding instructions step aside.

Pick a style with /config under Output style. The selection saves to your local project settings. Because the output style is part of the system prompt, which Claude Code reads once at session start, a change takes effect after /clear or a new session.

Role versus CLAUDE.md: do not confuse them

A persona is not the same as your project rules, and they belong in different places.

CLAUDE.md is for durable facts: your stack, your conventions, what to never touch. An output style is for the persona that shapes how those facts come out. "We deploy on Fridays" belongs in CLAUDE.md. "Explain every change like I am new to the codebase" belongs in an output style. Keeping them separate means you can change the voice without touching the facts. For the full picture of what loads into a session and when, see context engineering.

What are common mistakes when giving Claude a role?

• The role and the task disagree. Telling Claude to be a "concise reviewer" and then asking for a full architecture write-up creates a tug of war. Match the persona to the work.
• Stacking too many adjectives. "A brilliant, world-class, 10x, rockstar engineer" adds no information over "a senior engineer". The extra words are noise the model still reads.
• Forgetting to reset. A strong role from an earlier task lingers in a long session. When you switch tasks, switch the role too, or run /clear and start clean.
• Confusing tone with truth. A "confident expert" tone does not make the content more correct. It can make a wrong answer sound more convincing. Verify the substance regardless of how assured it sounds.
• Replacing the system prompt by accident. --system-prompt drops Claude Code's coding behaviour. If you only meant to add a persona, use --append-system-prompt.
• Setting a tone that fights the format. A "warm, chatty" tone and a "terse bullet list" format pull in opposite directions. Decide which one matters for the task and let the other yield.

A workflow that sticks

Start in a single message. Write the role with expertise, priorities, and audience. Add one tone behaviour you can check. Run it on a real task and read the output against what you wanted. Once it is right, save it as an output style so every future session starts in that voice. The first version costs you three sentences. Every session after that costs you nothing.

Checklist

Before you rely on a role, confirm:

• Does the role name the expertise, the priorities, and the audience?
• Is the tone a behaviour you can check, not just a feeling?
• Does the persona match the task, or do they pull against each other?
• For anything you repeat, is it saved in an output style instead of re-typed?
• Are project facts in CLAUDE.md and persona in the output style, not mixed?
• Did you verify the content, regardless of how confident the tone sounds?

A role is the cheapest steering you have. One sentence redirects every answer that follows. Spend it deliberately.