Detailed Analysis
A recent Reddit thread on r/ClaudeAI raises a technically substantive question about the internal architecture of Claude Code, Anthropic's agentic coding tool: why does CLAUDE.md—the project-level configuration file that provides context and instructions to Claude—get injected repeatedly as a user-message-level `<system-reminder>` rather than being appended once to the system prompt at the start of a session? The poster's framing is astute: since compaction (the process by which long-running conversations are summarized to stay within context limits) is inherently lossy, and since the system prompt survives compaction untouched, embedding CLAUDE.md in the system prompt would seem to guarantee its persistence for the entire session without needing to be reloaded. Instead, Claude Code appears to re-inject the file as a reminder within the conversation turns, which requires deliberate re-insertion logic after events like compaction.
The likely explanation, which the poster themselves speculates about, centers on prompt caching mechanics. Anthropic's API implements prompt caching that rewards a stable, unchanging prefix—typically the system prompt and early conversation turns—by allowing subsequent requests to skip reprocessing that portion of the context, significantly reducing latency and cost. If CLAUDE.md were baked directly into the system prompt, any edits a user makes to that file mid-session (a common occurrence, since developers frequently update project instructions as they work) would invalidate the cached prefix, forcing expensive recomputation on every subsequent turn. By instead treating CLAUDE.md as an injectable reminder that lives later in the context window, Claude Code can keep the true system prompt maximally stable while still allowing the file's contents to be refreshed, edited, or reloaded dynamically without breaking the cache.
This design choice also reflects a broader architectural philosophy in how Claude Code separates concerns between static model behavior and dynamic project state. The system prompt is meant to define Claude's stable operating parameters—tool definitions, core behavioral guidelines, and session-invariant instructions—while CLAUDE.md functions more like live project memory: something that can and should shift as the codebase, task, or user preferences evolve within a session. Treating it as a reloadable reminder rather than frozen system text gives Anthropic's engineers flexibility to re-inject updated content after compaction events, ensure freshness if the file changes on disk mid-session, and avoid the awkwardness of a system prompt that grows stale or contradicts a file the user has since edited.
More broadly, this thread is a window into the increasingly sophisticated engineering tradeoffs underlying long-running agentic AI systems. As coding agents like Claude Code are asked to operate over extended sessions—sometimes hours of iterative work involving multiple compactions—the interplay between context window management, prompt caching economics, and instruction persistence becomes a first-order design problem rather than an afterthought. The fact that developers are reverse-engineering these architectural decisions from observed behavior, and that such questions attract serious technical speculation rather than dismissal, underscores how much scrutiny Anthropic's agent tooling now receives from a technically sophisticated user base. It also signals a maturing pattern across the industry: caching-aware prompt engineering, where the placement of content in a context window is dictated as much by cost and performance considerations as by semantic organization.
Read original article →