Claude Code Output Styles vs CLAUDE.md: Pick One

Claude Code now has five places to put instructions, and I watch people pile everything into CLAUDE.md because it's the one they learned first. Here's where each thing actually belongs:

The test is "every turn, regardless of task.""Always answer with a Mermaid diagram first" passes — that's a style. "We use pnpm, not npm" fails; it's a project fact, so it goes in CLAUDE.md. "Run the release checklist" fails too, and belongs in a skill, which is loaded only when it's relevant instead of riding along on every request.

This is the bug almost everyone hits and almost nobody diagnoses. A custom output style leaves out Claude Code's built-in software engineering instructions unless you set keep-coding-instructions: true, and that field defaults to false. Those built-in instructions are the ones covering how Claude scopes a change, how it writes comments, and how it verifies its work.

So you write twelve lines asking for shorter replies and a diagram up front, switch to it, and Claude quietly stops doing half the things that made it good at the job. Nothing errors. Nothing warns you. The output just gets sloppier in ways that look like the model having an off day. I chased this for the better part of an afternoon before reading the frontmatter table properly.

The fix is one line:

---
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.

## Diagram conventions

Use `flowchart TD` for control flow and `sequenceDiagram` for
request paths. Keep diagrams under 15 nodes.

Rule of thumb: if Claude is still writing code, set it to true.Leave it out only when Claude isn't doing software engineering at all — a writing assistant, a data analyst, an on-call explainer. That's the case the default was designed for, and it's the rarer one.

Before you write a custom one, check whether a built-in covers it. There are five, and two of them are more opinionated than their names suggest:

• Default.Claude Code's standard software engineering instructions.
• Proactive. Claude executes immediately and makes reasonable assumptions instead of pausing for routine decisions. Worth being precise here: this is stronger autonomous-execution guidance than auto mode applies, and it works without changing your permission mode. Your permission mode still decides what runs without asking — Proactive changes how eagerly Claude acts, not what it's allowed to do.
• Concise. Leads with the result, skips preamble and narration, and does the engineering work as thoroughly as Default. Ask for detail and you get it in full. It always keeps the complete content of error reports, security warnings and destructive-action confirmations, which is the design decision that makes it safe to leave on. Needs v2.1.237 or later.
• Explanatory.Adds educational "Insights" between tasks so you understand implementation choices and codebase patterns.
• Learning. Same Insights, plus Claude leaves TODO(human) markers in your code for you to implement. It asks you to write small strategic pieces yourself.

These have real token consequences.Explanatory and Learning produce longer responses by design, which raises output tokens on every turn. Concise does the opposite. A style's instructions also add input tokens, though prompt caching absorbs that after the first request of a session. If you run Explanatory all day on a Pro plan and wonder why limits arrive early, that's where it went.

Two behaviors that look similar and aren't, and both of them save you money once you know which is which.

Switching output style mid-session keeps the cache.Claude Code delivers the new style's instructions as a message in the conversation, so the request still reads the system prompt and the earlier conversation from cache. That puts it in the same safe bucket as changing permission mode or invoking a skill — and in the opposite bucket from switching models or changing effort level, which recompute the entire request. The new style applies starting with your next message. On versions before v2.1.251 it was still cache-safe but didn't take effect until /clear or a new session, which is where a lot of stale advice online comes from.

Editing CLAUDE.md mid-session also keeps the cache — because the edit doesn't apply. Your project-root and user-level CLAUDE.md files are read once at session start and held in memory. Claude keeps working from the version loaded at startup until /clear, /compact or a restart. Nested CLAUDE.md files in subdirectories and rules with paths: frontmatter are different: they load when Claude first reads a matching file, so editing one before it loads does take effect.

There's a third gotcha in the same family. In the terminal, Claude Code reads output style filesat startup. Create or edit a style during a running session and it doesn't exist yet — restart before you go hunting for why /output-style won't list it.

Output styles apply to the main conversation and to a fork. Every other subagent runs its own system prompt, so the active style never touches it. A fork is the exception because it inherits the parent's full conversation and system prompt outright.

In practice this is the second-most-common surprise after the frontmatter default. You set Concise, delegate a review to a subagent, and the report comes back as long as ever. The style isn't broken. It was never in that conversation. Anything a delegated run has to obey belongs in the agent definition or in the skill it loads — the same reason a skill that never fires is usually a selection problem rather than a content one. It's also why cloud threads ignore your local setup entirely.

A custom style is a Markdown file. Three places to put it:

• User: ~/.claude/output-styles
• Project: .claude/output-styles
• Managed policy: .claude/output-styles inside the managed settings directory

The file name becomes the style name unless frontmatter sets name. Project styles load from every .claude/output-styles/ between your working directory and the repo root, and on a name collision the one nearest the working directory wins — worth knowing in a monorepo where a package can shadow the root style.

Selecting a style writes outputStyle into .claude/settings.local.json at the local project level. The /output-style command, the /config menu and the VS Code Output styles menu all write the same file. On Desktop you set the field by hand.

As of v2.1.269, /output-style works outside interactive terminals— non-interactive mode, Agent SDK sessions, and the mobile app or web through Remote Control, where only the built-in styles are selectable. That's the change that makes styles usable in automation instead of just at your keyboard.

One field to watch in team setups: plugins can ship styles in an output-styles/ directory, and force-for-plugin: true applies that style automatically whenever the plugin is enabled, overriding the user's own outputStyle setting. If multiple enabled plugins set it, the first one loaded wins. If a teammate's Claude suddenly talks differently and nobody changed a setting, check what plugins got installed this week — the same class of invisible-config problem that hooks cause in production.

Concise at the user level, on permanently. I do a lot of my Claude Code work through cron jobs and automation where nobody reads the narration, and on interactive work I'd rather scan a result than a paragraph explaining that a result is coming. The one thing that made me trust leaving it on is that it never truncates error reports or destructive-action confirmations — the places where brevity would actually cost me something.

Everything project-specific stays in CLAUDE.md, where it belongs, and I stopped writing custom styles after the keep-coding-instructions incident unless I genuinely want Claude out of engineer mode. Two live custom styles across all my repos. Both non-coding. That ratio feels about right.

If you take one thing: the layer you pick determines what you break. A bad CLAUDE.md line gives Claude a wrong fact. A bad output style gives Claude a different job description. Those failures look identical from the outside and are fixed in completely different places.