How Claude Code uses prompt caching changedprompt-caching
Nearest release: v2.1.267, published 4 hours before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+8added
Lines−6removed
From line
18
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits52to this page, all time
The whole hunk
from line 18, old and new numbered
/
from line 18
1818
1919To get the most out of prefix matching, Claude Code orders each request so content that rarely changes between turns comes first:
2020
21| Layer | Content | Changes when |
22| --------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
23| System prompt | Core instructions, tool definitions, output style | The set of loaded tool definitions changes, you switch output style, or Claude Code is upgraded |
24| Project context | CLAUDE.md, auto memory, unscoped rules | Session starts, or after `/clear` or `/compact` |
25| Conversation | Your messages, Claude's responses, tool results | Every turn |
21| Layer | Content | Changes when |
22| --------------- | ----------------------------------------------- | --------------------------------------------------------------------- |
23| System prompt | Core instructions, tool definitions | The set of loaded tool definitions changes or Claude Code is upgraded |
24| Project context | CLAUDE.md, auto memory, unscoped rules | Session starts, or after `/clear` or `/compact` |
25| Conversation | Your messages, Claude's responses, tool results | Every turn |
2626
2727A change to the conversation layer leaves the system prompt and project context cached. A change to the system prompt invalidates everything, because all later content now sits behind a different prefix. The third column gives common triggers rather than an exhaustive list, and the sections below cover the full set.
2828
from line 160
160160
161161### Changing output style
162162
163[Output style](/docs/en/output-styles) is part of the system prompt. When you switch styles mid-session with `/config` or the `outputStyle` setting, Claude uses the new style starting with your next message, and that request reads the entire conversation history with no cache hits. To keep that cost small, switch styles before your first message in a session or right after `/clear` or `/compact`, when there is little or no conversation history to re-read.
163When you switch [output styles](/docs/en/output-styles) mid-session with `/config` or the `outputStyle` setting, Claude uses the new style starting with your next message. In a conversation that [keeps a recorded system prompt](/docs/en/cli-reference#system-prompt-flags-in-resumed-conversations), as sessions signed in with a claude.ai or Console account do by default, Claude Code delivers the new style's instructions as a message in the conversation. That request still reads the system prompt and the earlier conversation from the cache.
164
165In sessions that don't [fetch feature flags](/docs/en/env-vars#features-that-need-feature-flag-fetching), such as on Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry, the style's instructions are part of the system prompt, so the request after a switch reads the entire conversation history with no cache hits. There, switch styles before your first message in a session or right after `/clear` or `/compact`, when there is little or no conversation history to re-read.
164166
165167Before v2.1.251, a mid-session style switch kept the cache but didn't apply until you ran `/clear` or started a new session.
166168
No line in this hunk matches that.