What Is the Claude Code System Prompt?

What Is the Claude Code System Prompt?

Every Claude Code session starts with a set of instructions you did not write.

They tell Claude that it is a coding assistant, how to use its tools, how to scope a change, when to stop and ask.

That block of text is the system prompt, and it is the reason Claude Code behaves like an engineer rather than a chatbot that happens to have a terminal.

Two different questions hide behind the search. One is "what does it say?" The other is "how do I change it?" Anthropic answers the first one plainly and unhelpfully, and answers the second one in considerable detail.

This guide gives you both, with the exact flag names and the version gates, so you can stop guessing at behaviour that is actually documented.

Shipping faster is only useful if people can find what you shipped. A free SEO audit from SEO Stuff shows you where your site is losing search traffic. Get your free audit.

What Is the Short Answer?

Claude Code's default system prompt is not published. Anthropic's own settings documentation says so directly: "Claude Code's system prompt isn't published. To give Claude standing instructions, use CLAUDE.md files or the --append-system-prompt flag."

So there is no official text to read. What there is instead is a documented set of controls.

Five CLI flags shape the system prompt: --system-prompt and --system-prompt-file replace it, --append-system-prompt and --append-system-prompt-file add to it, and --system-prompt-snapshot controls whether a conversation keeps the text it started with. All five work in interactive and non-interactive modes.

If you only want Claude to follow one extra rule, you want an append flag.

If you want it to stop being a coding assistant altogether, you want a replacement flag, and you should understand what you are giving up.

What the System Prompt Actually Is, and What It Is Not

The published position

Anthropic does not publish the default prompt, and the documentation does not describe its contents beyond characterising it.

The output styles page comes closest, noting that with no style selected "Claude works from Claude Code's standard system prompt, which is written for software engineering tasks." Elsewhere the docs refer to the prompt containing "tool guidance and safety instructions" and a section of "built-in software engineering instructions, such as how to scope changes, write comments, and verify work."

That is the level of detail available first-hand. Reconstructions circulate, and they go stale with every release, so building a workflow on a particular remembered sentence is not a good bet.

Where CLAUDE.md sits, and why it is not the system prompt

This is the distinction most explanations get wrong. CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself.

The practical consequence is that compliance is not absolute. Writing an instruction in capital letters in CLAUDE.md and expecting it to be obeyed like a system-level rule misunderstands where the text ends up.

If you genuinely need something at the system prompt level, that is what the append flags are for.

The documentation makes the same recommendation: for instructions you want at the system prompt level, --append-system-prompt exists, and because you pass it at launch it suits scripts and automation better than interactive work.

Where output styles sit

An output style is a set of instructions that sets Claude's role, tone and response format for every response in a session.

Claude Code ships four built-in styles besides its default: Proactive, Concise, Explanatory and Learning.

Each of the four keeps the default instructions and adds its own.

Custom styles behave differently, and this is the part worth reading twice.

A custom output style leaves out Claude Code's section of built-in software engineering instructions unless the style's frontmatter sets keep-coding-instructions to true.

So a custom style is not purely additive the way an append flag is.

The same discipline that keeps a prompt predictable keeps a site ranking. Request a free SEO audit and see what is working.

How Do You Change the System Prompt, Step by Step?

Step 1: decide which layer you need. Project knowledge goes in CLAUDE.md. A reusable persona goes in an output style. A one-off rule for a scripted run goes in an append flag. A completely different assistant goes in a replacement flag.

Step 2: for an extra rule, append inline. Pass the text at launch, as in claude --append-system-prompt "Always use TypeScript". The documented description is exactly that: append custom text to the end of the default system prompt.

Step 3: for anything longer, append from a file. Use --append-system-prompt-file ./extra-rules.txt, which loads additional system prompt text from a file and appends it to the default prompt. Keeping the text in a file makes it reviewable in version control, which matters more than it sounds like it should.

Step 4: to replace instead, use the replacement flags. --system-prompt "You are a Python expert" replaces the entire system prompt with custom text, and --system-prompt-file ./custom-prompt.txt does the same from a file.

Step 5: combine them if you need to. You can pass an append flag together with a replacement flag to replace the default and still add your own text. From Claude Code v2.1.283 or later you can also pass a flag together with its own file form, such as --append-system-prompt with --append-system-prompt-file, and both are used.

Step 6: mind the ordering. When you pass both an inline append and a file append, the file's contents come first, even if you passed the inline flag first on the command line. If your two pieces of text have to be read in a particular sequence, put the sequence-sensitive part in the file.

Step 6b: mark the boundary if your appended text has two halves. If part of your appended text is instructions and part of it is context that changes between runs, you can add a line containing only __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__ between them. This requires Claude Code v2.1.275 or later and exists so the stable half can be cached while the volatile half is not.

Step 7: for a persona you will reuse, write an output style instead. Save a Markdown file with YAML frontmatter at ~/.claude/output-styles for yourself or .claude/output-styles for the project, then run /output-style <style> to switch, for example /output-style concise. With no argument the command lists the available styles and marks the current one.

When Is Each Layer the Right Choice?

The documentation gives a clean rule for the flags: use an append flag when Claude should remain a coding assistant that also follows your extra rules, and use a replacement flag when the surface, identity or permission model differs from Claude Code's.

Use CLAUDE.md for what Claude should know about your codebase. It stays loaded whichever output style you pick, which makes it the right home for conventions, architecture notes and the commands your project actually uses.

Use an output style when you want a persona you can switch between and share across a project.

A style set in .claude/settings.json as "outputStyle": "Explanatory" applies to everyone who works in that repository.

Note that the value is case-sensitive, so explanatory in lower case silently gives you the Default style instead. The /output-style command itself ignores case.

Use an append flag in automation. Because it is set at launch rather than from a file in the repository, it is the layer a CI job or a scripted agent run can control per invocation.

Limitations and Things That Trip People Up

Replacing the prompt drops everything. The documentation is blunt about it: replacing drops all of the default prompt, including tool guidance and safety instructions, so you take responsibility for whatever your task still needs. A replacement prompt that forgets to explain how to use tools produces an agent that holds its tools wrongly.

The prompt is built once and reused. By default Claude Code builds the system prompt on a conversation's first request, with any flag text applied, and records it in the session. If you need it rebuilt on every request, pass --system-prompt-snapshot off, which requires v2.1.257 or later. This is why editing a prompt file mid-conversation can appear to do nothing.

Caching behaviour has moved between versions. Before v2.1.265, passing any system prompt flag also turned recording off unless you passed --system-prompt-snapshot on. Before v2.1.268, sessions without feature-flag fetching, including Bedrock, Google Cloud's Agent Platform and Microsoft Foundry, rebuilt the prompt on every request and the snapshot flag had no effect at all. Check your own version rather than trusting a blog post about the behaviour.

Subagents do not inherit your style. Output styles apply to the main conversation and to a fork. Other subagents run their own system prompt, so a style does not change how they respond. For those there is --append-subagent-system-prompt, which appends to every subagent's system prompt but only applies in non-interactive mode with -p and requires v2.1.205 or later. The file form needs v2.1.261.

keep-coding-instructions can have no effect. The field only matters on the full system prompt. On the shorter prompt that section is not included anyway, so the setting does nothing. To rely on it, set CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT to 0.

Per-user context sits inside the default prompt. For scripted workloads running the same task across many users or machines, --exclude-dynamic-system-prompt-sections moves that context, such as the auto memory location, out of the system prompt and into the first user message, which improves prompt-cache reuse. It only applies with the default prompt and is ignored when --system-prompt or --system-prompt-file is set.

Safe mode strips your customisation. Running with --safe-mode means output styles, CLAUDE.md and custom agents do not load. That is the point of safe mode, but it also makes it a useful diagnostic: if a problem disappears in safe mode, your customisation layer caused it.

An instruction is not a guarantee. The output styles documentation says it plainly: a style gives Claude instructions to follow, and it does not guarantee that something always happens or never happens. The same is true of an appended system prompt. For things that must be enforced, reach for a hook or a deny rule rather than stronger wording.

Enforcement beats hope in SEO too. Book a free audit and find the fixes that actually move rankings.

The System Prompt vs the Alternatives

Versus CLAUDE.md. Lower effort, loaded automatically, visible to your whole team, and it survives style changes. But it arrives as a user message, so treat it as strong guidance rather than a rule.

Versus output styles. Reusable, shareable, switchable mid-session from v2.1.251 onwards without clearing the conversation, and selectable from the terminal via /config or from VS Code. But a custom style trades away the built-in engineering instructions unless you ask for them back.

Versus hooks. A hook is deterministic. It runs, it has an exit code contract, and it either passes or blocks. If the behaviour you want is "never commit without running the tests", that is a hook, not a sentence in a prompt.

Versus subagents. A subagent is a helper with its own instructions, model and tools for a focused task, running in a separate context and returning a summary. When you want different behaviour for part of a job rather than all of it, that is the tool.

Final Thoughts

The system prompt is the one layer of Claude Code you cannot read and can still fully control.

Anthropic does not publish it, and chasing a leaked copy buys you a snapshot that the next release invalidates.

What is durable is the interface: four flags that set the text, one that controls whether it is reused, and an output style system layered above them.

If you take one thing away, make it the distinction between appending and replacing. Appending keeps the engineer and adds your rules.

Replacing hands you an empty stage and every responsibility that came with the default, including the safety instructions.

For the layer most people actually need first, our guide to how Claude Code memory works covers CLAUDE.md scopes, imports and load order in detail.

Want the same clarity about your search performance? Get a free SEO audit from SEO Stuff and start with what is costing you the most.