Inside the Claude Code Harness: The System Prompt Machine
Claude Code is the harness most people use without knowing what it sends. The current docs are unusually candid about the machinery, and the machinery has one organizing idea: every request is assembled in layers ordered by how often they change, because the prompt cache only survives if the stable parts stay on top. Everything else follows from that.
Three layers, ordered by volatility
Each API request stacks three layers: the system prompt (core instructions, tool definitions, output style, roughly 4,200 tokens by the docs' own illustration), then project context, then the conversation. The fact that surprises almost everyone: CLAUDE.md is not in the system prompt. The docs state it plainly: it is delivered as a user message after the system prompt. Your carefully written memory file is context, not law, and the docs are honest that it is advisory: if you need a rule enforced every time, that is what hooks are for.
The CLAUDE.md hierarchy runs managed policy, then ~/.claude/CLAUDE.md, then project files discovered by walking up the directory tree, then CLAUDE.local.md. Subdirectory files load lazily when Claude reads a file there. The best-practices page adds the discipline: for each line ask whether removing it would cause mistakes, because a bloated file gets ignored, and its own failure list names "the over-specified CLAUDE.md" directly.
Cache preservation as architecture
Anthropic published a blog titled "prompt caching is everything," and the harness backs it up structurally. Requests are append-only. File edits do not mutate history; a <system-reminder> noting the change is appended instead. Plan mode is entered and exited through always-present tools precisely so a mode switch never rewrites the prefix. Output style changes wait for restart. MCP tool schemas are deferred behind a ToolSearch tool so connecting a server does not invalidate the conversation. Subscription users get a one-hour cache TTL where API users default to five minutes. The documented invalidation list is short and deliberate: model switch, effort change, a bare-name tool deny, compaction, an upgrade.
This is the prompt Claude Code assembles, top of the stack first. Fire session events and watch which ones append (cheap) and which ones touch the prefix (you pay for everything again).
Compaction in two stages
Approaching the limit, Claude Code clears older tool outputs first, and only then summarizes the conversation. What survives is specified with unusual precision: the system prompt unchanged, root CLAUDE.md and auto memory re-read from disk, invoked skill bodies re-attached capped at 5,000 tokens per skill and 25,000 total, and the skill index dropped. The community calls the first stage microcompaction; the docs describe the mechanism without the name. The exact trigger percentage is not documented, and I will not guess it here.
Proportions illustrative; the mechanism and the caps are from the docs. The system prompt survives byte for byte, CLAUDE.md is re-read from disk, invoked skill bodies re-attach capped at 5K each and 25K total, and the summary is new tokens. Only the gray ever gets cheap again.
The enforcement layer
Where Pi has no permission system at all, Claude Code has the deepest one shipping. Rules resolve deny over ask over allow; Bash matching is shell-operator aware, so each subcommand of a pipe must pass independently. Hooks cover roughly twenty-five lifecycle events with five handler types, including an LLM-judge hook and an agent hook, and they can rewrite tool inputs before execution. A hook cannot override a deny rule. Auto mode adds a separate classifier model that reviews commands with tool results deliberately stripped from its input, so hostile file content cannot steer the approver. Underneath sits OS-level sandboxing: Seatbelt on macOS, bubblewrap plus a network proxy on Linux.
What it teaches
Claude Code's bet is the opposite of Pi's: own a large surface (subagents, skills, hooks, plugins, background tasks) and spend enormous engineering effort keeping that surface cache-stable and policy-gated. The best-practices page distills the operator's side of the deal into one constraint: the context window is the resource, so give the agent a check it can run, clear between tasks, and let subagents do the exploratory reading in their own windows. Sources: the prompt caching, memory, context window, and best practices docs, current as of v2.1.220.