What Actually Happens When You Edit CLAUDE.md Mid-Session

1. Effect on the prompt cache: none — the cache is unaffected. Project-root and user-level CLAUDE.md files are read exactly once, at session start, and held in the system's project-context layer for the rest of the session. The prompt cache's cache key is built from the system prompt, the project-context layer as it was loaded at startup, and the growing conversation history — none of which re-reads CLAUDE.md from disk mid-session. Editing the file on disk doesn't touch any of those three things, so the next turn hits the cache exactly as it would have without the edit. This is a case where it's easy to assume the opposite — that changing a file that's part of a model's "instructions" would obviously force a recomputation — but the mechanism doesn't work that way here.

2. Effect on running behavior: also none, for the same underlying reason. Because CLAUDE.md is read once at startup and held in memory, not re-read on each turn, Claude is still operating on the original version of the file that was loaded when the session began. The new typecheck rule genuinely is not part of Claude's current context — it isn't lost or ignored in some vague sense, it was simply never loaded. Claude has no way to know the rule exists until the file is reloaded, which only happens at specific points: the start of a new session, or a /clear or /compact within the current one (both of which re-inject project-root CLAUDE.md fresh from disk as part of how they rebuild context).

3. What the developer should actually do: the cheapest way to make the new rule active in the current session is to run /compact (ideally with a focus instruction relevant to the ongoing work, e.g. /compact focus on the current refactor) rather than /clear, since /compact preserves a summary of the conversation so far while still re-injecting CLAUDE.md and auto memory fresh from disk — giving them the updated rule without losing the session's accumulated context. /clear would also pick up the new rule (it also reloads project context from disk) but at the cost of discarding the conversation history entirely, which is unnecessary here since nothing about the existing conversation is stale or wrong. The one thing that will not work, no matter how long they wait, is simply continuing to prompt Claude in the current session and expecting the rule to take effect on its own — the file has to be reloaded through one of those explicit mechanisms, or the current session ends and a new one starts.

The broader lesson this scenario illustrates: the popular mental model of "editing CLAUDE.md mid-session costs you an expensive cache rebuild" is actually backwards for the specific case of the file itself. The real risk isn't cost — it's the opposite and more easily missed: a change that's completely free, cache-wise, but also completely inert until a reload point, which can lead a developer to believe a rule is active (because they added it and moved on) when it silently isn't.