L2 Product Teardown · Claude Code Agent Harness, Tool Simplicity & Prefix Caching
Reverse-engineering Claude Code's agent harness: minimal composable primitives over bloated tool registries, >85% prompt-cache hit rates via append-only turn structuring, context compaction, and isolated Subagent delegation.
Best For
AI Engineers and framework authors optimizing long-horizon coding agents for accuracy, prefix cache economics, and human trust.
Human-AI Boundary
Read-only file/search tools execute smoothly unattended; file writes and mutating shell commands follow tiered allowlists or explicit developer approval prompts.
Anti-Patterns to Avoid
- Registering 60 overlapping MCP/API tool schemas in the system prompt, bloating per-turn tokens and confusing model tool selection
- Injecting changing timestamps or mutating earlier messages mid-session, invalidating expensive Anthropic prompt cache checkpoints
Latency/Cost Profile & Eval Metrics
Cached prefill cuts multi-turn TTFT 60%–80%; interactive permission prompts cleanly asynchronous · 90% input token discount on append-only cached prompt prefixes
- Prefix Cache Read Share & Unattended Edit Verification Rate: >= 85% cached_read_tokens / total_input_tokens across multi-step repo sessions (Never mutate static system prompts, tool definitions, or earlier turns until explicit context compaction)
💰 Business ROI Model & Evidence Level
production_practiceAppend-only prompt cache alignment cuts effective multi-turn input cost by up to 90% on 50-turn repo sessions while isolated Subagent exploration prevents Context Rot.
🏗️ End-to-End Architecture Pipeline
Lock system instructions, `CLAUDE.md`, and orthogonal tools at prefix root; keep turns strictly append-only to preserve cache reads.
Delegate broad repo exploration into disposable Subagents; summarize structured milestones cleanly upon hitting context budget thresholds.
⚖️ Engineering Trade-Off & Decision Matrix
📊 Benchmark & Alternative Comparison
- Strict Append-Only Prompt Cache vs Uncached Dynamic History Formatting: saves up to 80%+ multi-turn session spend on frontier coding models.
🚨 Production Failure Modes & Signatures
- Mutating tool descriptions or live environment timestamps inside the prefix on each step, losing all cache discounts
- Auto-compacting silently and dropping key architecture constraints or modified file paths if structured state isn't preserved
Bidirectional Taxonomy Links
Internal Tools & Primary Sources
- Anthropic Engineering — Claude Code Best Practices & Agentic Coding (engineering_blog, 2026-11-17)