89 Feature Flags, a YOLO Classifier, and the Cache Tricks Inside Claude Code's Leaked Source
Someone extracted an entire book from the leaked source code.
A Book Grown from Source Code
Zhang Handong (@ZhangHanDong) did something cool.
The TypeScript source code of Claude Code v2.1.88 was restorable due to a source map leak. He didn't just look at it—he had Claude Code distill an entire book from the source code—"Harness Engineering" (also known as "The Horse Book"), 30 chapters across 7 parts, covering architecture, prompt engineering, context management, caching, security, advanced subsystems, and lessons learned.
This book reveals the internal operating mechanisms of an AI coding agent and every key decision Anthropic engineers made when designing Claude Code.
Here are the most noteworthy discoveries.
Secret One: The Product Roadmap Revealed by 89 Feature Flags
Claude Code's source code contains 89 build-time Feature Flags (implemented via Bun's feature() function for compile-time dead code elimination).
These flags are not random—they reveal a clear product evolution roadmap:
| Flag Cluster | Flag Count | References | Points To |
|---|---|---|---|
| KAIROS Family | 6 | 84+ | A complete "assistant mode"—background autonomous running, memory organization, push notifications, GitHub Webhook integration |
| Multi-Agent Orchestration | 3 | 90+ | Worker allocation, teammate memory sharing, Unix Domain Socket inter-process communication |
| Remote & Distributed | 4 | — | Remote control and distributed execution—expanding from a local CLI to an Agent platform |
| Context Optimization | 3 | — | Three context management strategies at different granularities |
| Classifier System | 2 | 102 | Transcription classifier (69 references) + Bash classifier (33 references)—the core of automatic mode |
Revelation: 89 Flags = 89 directions being explored. Claude Code is clearly still in a phase of rapid iteration.
Secret Two: The YOLO Classifier—Using AI to Audit AI
Claude Code's permission system contains a component called the YOLO Classifier—it uses AI to decide whether an AI's operation is safe.
How It Works
Security whitelist short-circuit → Read-only operations pass at zero cost
↓ (Uncertain operations)
Two-stage XML Classifier:
Stage 1: Fast judgment (max_tokens: 64, sub-second)
Stage 2: Deep reasoning (max_tokens: 4096, includes <thinking> chain-of-thought)
↓
Default deny when uncertain
↓
After 3 consecutive or 20 total rejections → Fallback to manual user confirmation
Core Principle
"When uncertain, default deny."
Its design philosophy is conservative and progressive—let the AI screen first, block anything uncertain, and hand it over to a human.
Four Permission Strategies
| Strategy | Implementation | Trigger Condition |
|---|---|---|
| Unconditional Registration | Core tools always available | Basic operations |
| Feature Flag Guard | Eliminate entire module tree at build time | Experimental features |
| Environment Variable Guard | USER_TYPE === 'ant' |
Anthropic internal users verify first |
| Runtime Function Guard | Conditional enabling | Dynamically switched based on codebase state |
Secret Three: Five Caching Principles—Reducing API Costs by 90%
Claude Code's prompt caching system is treated as core infrastructure by Anthropic. Lance Martin summarized five principles:
Principle 1: Static First, Dynamic Last
Stable content (system prompts, tool definitions) goes at the front; frequently changing content goes at the back.
Principle 2: Update via Message Passing, Don't Edit Prompts
Append <system-reminder> messages instead of modifying existing system prompts. Editing breaks the cache prefix.
Principle 3: Don't Switch Models
Caching is model-specific. Switching models = all caches invalidated. Use sub-agents when a cheaper model is needed; don't switch the main model.
Principle 4: Manage Tools Carefully
Tool definitions are in the cache prefix. Adding or removing tools = prefix invalidation. Use tool search for dynamic appending.
Principle 5: Update Breakpoints
In multi-turn applications, move the cache breakpoint to the latest message to leverage automatic caching.
The Cleverest Tricks
- • Beta Header Latching — Once a specific beta header has been sent, always continue sending it. Removing it changes the request signature, causing cache invalidation.
- • Date Memoization — If a session spans midnight, don't change the date string to avoid breaking the cache.
- • Agent List Optimization — Moved from the system prompt to a system-reminder, reducing global cache_creation by 10.2%.
Secret Four: Six Harness Principles
Core principles distilled from the book's 30 chapters:
| # | Principle | Core Idea | Anti-pattern |
|---|---|---|---|
| 1 | Prompt is the Control Plane | Behavior guided by natural language; code handles only structural constraints | Hard-coding behavior |
| 2 | Cache-Aware Design is Mandatory | Every prompt change has a cost | Frequent prompt changes |
| 3 | Fail Closed, Explicitly Open | Default to the safest value; must be explicitly declared to allow | Default open |
| 4 | A/B Test Everything | Validate internally first, promote only after data confirmation | Big Bang releases |
| 5 | Observe Before Fixing | Build observability to understand the full scope of a problem | Fixing by intuition |
| 6 | Latch for Stability | Once in a state, don't oscillate | State jitter |
Secret Five: Engineering Details of Context Management
A 200K token context window sounds large, but Claude Code's engineering practices tell us: it's far from enough.
| Metric | Value |
|---|---|
| System Prompt Usage | ~15-20K tokens |
| Auto-Compaction Trigger Point | ~167K (83.5%) |
| Compaction Output Reservation | 20K tokens |
| Single Tool Result Limit | 50K characters |
| Circuit Breaker Threshold | 3 consecutive failures |
Claude Code's design philosophy is simple: the cheapest token is the one you never send. Every piece of content entering the context has an explicit token budget.
Inform, Don't Hide
When truncation occurs, it doesn't silently cut content—it informs the model that "content was truncated; the full information is at this path on disk."
This allows the model to proactively fetch the full information when needed, rather than making decisions based on incomplete data without knowing it.
Final Words
The truly valuable part of "The Horse Book" is that it distills the engineering practices of a commercial AI product into reusable design patterns.
Whether you are using Claude Code, Cursor, Copilot, or building your own AI Agent—these patterns apply:
- Two-tier Feature Flag management
- Using AI to audit AI with a YOLO Classifier
- Cache-aware prompt design
- A fail-closed security philosophy
- Setting a token budget for everything
Claude Code's source code tells us that the most advanced teams are already doing this.
If you find this series helpful, follow 「Cyber Shrimp Strip」 for ongoing updates to the Harness Engineering series.
This is a bonus chapter of the Harness Engineering series. Full series: ① What is Harness Engineering? ② How exactly to write AGENTS.md? ③ Harnessing AI with Linters ④ How do you know the code AI wrote is correct? ⑤ The Ralph Loop ⑥ Anthropic's Three-Agent Experiment ⑦ Entropy Management ⑧ Starting Today: Your First Practice