← Back to Registry Hub/Site Search/L2 · product_teardown
⚡Flashcard Drill➔
L2S3 · Model & AgentS4 · UX & HITLS6 · Security & FinOpsVerified: 2026-11-17

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_practice

Append-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

Step 1: Cache-Stable Append-Only Prefix & Orthogonal Minimal Toolset

Lock system instructions, `CLAUDE.md`, and orthogonal tools at prefix root; keep turns strictly append-only to preserve cache reads.

Step 2: Threshold Context Compaction & Subagent Code Search

Delegate broad repo exploration into disposable Subagents; summarize structured milestones cleanly upon hitting context budget thresholds.

⚖️ Engineering Trade-Off & Decision Matrix

Minimal General Tools (Bash + Read/Edit + Search) + Strong Harness
When to Use: Software engineering domains with rich deterministic CLI compilers and test harnesses.
Trade-Off: Superior generalization via standard unix primitives paired with strict command permission tiers.

📊 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
⚡
Test muscle memory on this topic via 3-Layer Flashcards
Active Recall: Mentally formulate Prompt ➔ Math Derivation ➔ Benchmark Implementation in 3 minutes.
🎯 Drill This Card Now➔

Bidirectional Taxonomy Links

Internal Tools & Primary Sources