Overview
All readers — reverse-engineer Claude Code as a reference agent harness; extract design principles that transfer to your own agent.
Why dedicate a chapter to Claude Code
Harness Engineering covers “how to build an agent harness” and Context Engineering covers “how to manage context.” Both are product-neutral theory.
This chapter is different — this chapter covers one product: Claude Code.
Why a product-specific chapter is worth it: Claude Code is the agent harness Anthropic builds for itself and uses internally. Every decision in its design embodies Anthropic’s answers to the harness and context engineering questions they write papers about. Studying it gives you two things at once:
- A production-grade engineering reference — CLI + Desktop + Web + IDE plugins, with millions of hours of real usage
- Observable evidence of what Anthropic actually believes about progressive disclosure, context rot, and the attention budget — not just what they publish in papers
So this chapter isn’t a product manual. It’s a case study. We reverse-engineer, then redirect the findings into design principles you can apply to your own agent.
What makes Claude Code distinctive
Compared to agent products that stop at the surface layer (Cursor / Windsurf / Devin / Aider), Claude Code makes several decisions that others don’t make — or make in a much shallower form:
| Decision | What Claude Code does | Why it’s worth studying |
|---|---|---|
| Layered system prompt | Static skeleton + project-level CLAUDE.md + user-level ~/.claude/ + auto memory + session-level guidance, all injected in separate layers | Turns “prompt cache hit rate” and “personalization” into primary design constraints, not afterthoughts |
| Context compaction | Auto-triggered compaction that preserves semantic scaffolding and discards re-derivable content | Makes “which tokens have long-term value” an explicit strategy |
| Memory system | Three tiers (project / user / auto memory) + MEMORY.md always-loaded index + individual files loaded on demand | A textbook application of progressive disclosure |
| Sandbox and permissions | Permission modes as a per-turn user-visible state machine, hooks as event-level interception | Trust boundaries become a product surface, not a hidden config |
| Subagents (Agent tool) | Main agent delegates sub-tasks via the Agent tool; sub-agent context is fully isolated | Context firewall — the value of multi-agent isn’t parallelism, it’s isolation |
| Hooks | pre/post tool, stop, prompt-submit event hooks guaranteed by the harness | Separates “prompt-level” from “process-level” requirements; admits that prompts can’t do everything |
Each row unpacks into its own chapter below.
Reading order
| # | Topic | What you’ll be able to answer |
|---|---|---|
| 1 | This page (Overview) | Why study Claude Code, what to read |
| 2 | System Prompt Assembly | How static skeleton + CLAUDE.md + session guidance get assembled; why it’s layered that way |
| 3 | Compaction | When compaction fires, what gets kept, how cross-session handoff works |
| 4 | Memory System | 6 memory types, MEMORY.md index design, subagents as context firewalls |
| 5 | Agent Execution Loop | What a single turn actually runs: query async generator, 14-step pipeline, streaming tool executor, full-chain abort |
| 6 | Permissions | The trust decision layer: 7 modes × 8 sources × 11 reasons × 10 hook events |
| 7 | Execution Environment | 3 isolation modes (none / worktree / remote), cross-platform process sandbox, CCR cloud architecture |
| 8 | Design Lessons | Cross-cutting principles extracted (abstract) |
| 9 | Applying to Your Agent (AI SDK) | Principles landed in AI SDK’s 8 embedding points, 3 traps, MVP blueprint (executable, cut by hook) |
| 10 | Lifecycle State Flow | How state flows across the 8 points in one conversation · 4 state buckets · R/W matrix (cut by state) |
The first seven chapters describe what Claude Code does. Chapter 8 extracts abstract principles; chapter 9 lands them in specific AI SDK code (hook-cut); chapter 10 traces state flow across the 8 points (state-cut) — 9 and 10 are complementary views of the same code.
Chapter organization: 2-4 cover static composition (prompt, compaction, memory); 5 covers dynamic runtime (the turn loop); 6-7 cover security boundaries (trust + physical isolation); 8-10 are the theory → applied triplet — chapter 8 states abstract principles, chapter 9 is the hook-cut code map, chapter 10 is the state-flow dynamic walkthrough.
What this chapter is not
- Not a user manual. For installing, configuring MCP, or writing slash commands, the official docs are thorough: docs.claude.com/claude-code.
- Not guesswork about internals. This chapter discusses only observable behavior — what the system prompt
looks like, what tool error strings say, how UI responds to permission-mode switches, the order in which
CLAUDE.mdfiles are loaded. Specific algorithms (compaction trigger thresholds, memory ranking) are not asserted unless Anthropic has published them. - Not a feature matrix vs Cursor / Devin. Comparison tables tend to read like marketing copy. We’ll cite occasional contrasts to explain “what Claude Code decided that others didn’t,” but we don’t build a full matrix.
- Not an official Anthropic position. This is a third-party synthesis. Some design lessons are inferences from observable behavior, not quotes from Anthropic docs.
Methodology: observable vs inferred
Two kinds of claims are strictly separated in this chapter:
- Observable: things any Claude Code instance can see — text in the system prompt, tool schemas,
CLAUDE.mdloading behavior, wording of error messages, UI behavior on permission-mode switch - Publicly documented: docs.claude.com, Anthropic blog posts, the official changelog
- Inferred: design intent inferred from the above two — explicitly labeled “inferred” or “likely”
Anything not labeled as inferred is supported by observation or public documentation.
Who should read this
- Builders actively designing an agent product who want to know which decisions in a mature harness are worth copying
- Claude Code users who want to understand why it’s designed the way it is, not just how to use it
- Anyone doing context engineering who wants to see whether the principles in Context Engineering have a full engineering instance somewhere
Not a good fit: readers new to AI who haven’t started building agents yet. Start with Agent = Model + Harness instead.
Further reading
- Harness Engineering — Anthropic’s thesis on harness construction, the theoretical background for this chapter
- Context Engineering — the attention budget and three-pillar model, cited throughout this chapter
- docs.claude.com/claude-code — official Claude Code docs (usage-oriented)