After analyzing source code for 20+ chapters, we understand every detail of Claude Code. But “knowing how” doesn’t equal “knowing why.”

This chapter distills six core principles - the wisdom of Harness Engineering - applicable not just to Claude Code, but to any AI Agent system construction.

Principle 1: Prompts Are the Control Plane

Definition: Guide model behavior through system prompt paragraphs, rather than hardcoding restrictions in code logic.

Why It Matters

AI model capabilities are evolving rapidly. If you write code to detect every behavior, you’ll never keep up with model capability changes.

Claude Code’s Practice

Minimalist instructions:

"Don't create helpers, utilities, or abstractions for one-time operations.
Don't design for hypothetical future requirements. The right amount of
complexity is what the task actually requires..."

This text is not code comment - it’s actual instruction sent to the model. Claude Code doesn’t detect whether model over-engineers at code level (technically near impossible) - instead it directly tells the model “don’t do this” through natural language.

Tool prompt examples:

  • BashTool’s Git safety protocol entirely expressed in prompt text
  • “Never skip hooks, never amend, prefer explicit file git add”
  • If amend is allowed someday, just delete one prompt line, no execution logic touched

Applicable Boundaries

  • Use code for: structural constraints (permissions, token budget)
  • Use prompts for: behavioral constraints (style, strategy, preferences)

Anti-Pattern: Hardcoding Behavior

Writing detectors and interceptors for every undesired model behavior results in a massive rules engine that can never catch up to model capability evolution.

Principle 2: Cache-Aware Design Is Essential

Definition: Every prompt change has a cost measured in cache_creation tokens, so system design must treat cache stability as a first-class constraint.

Dynamic Boundary Markers

export const SYSTEM_PROMPT_DYNAMIC_BOUNDARY =
  '__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__'

Divides system prompt into two regions:

  • Before boundary: cross-user shared content, globally cacheable
  • After boundary: user/session-specific content, not cached

Cache Break Detection

Tracks ~20 field state changes before and after:

  • systemHash: system prompt hash
  • toolsHash: tool schema hash
  • cacheControlHash: cache control hash
  • perToolHashes: per-tool hashes
  • betas: beta header list

Any field change can trigger cache invalidation.

Beta Header Latching Mechanism

Extreme case: once a beta header is ever sent, always continue sending it, even if feature is turned off.

Reason: stopping transmission changes request signature, causing ~50-70K token cache prefix to be invalidated.

Date Memoization

If session crosses midnight, date seen by model “expires” - but this is intentional because date string changes would break cache prefix.

Anti-Pattern: Frequent Prompt Mutation

Agent list was once inlined in system prompt, accounting for 10.2% of global cache_creation tokens. Solution was moving to system-reminder messages - this part is outside the cache segment.

Principle 3: Fail-Closed, Explicitly Open

Definition: System default should choose the safest option, only allowing dangerous operations with explicit declaration.

Tool Defaults

const TOOL_DEFAULTS = {
  isEnabled: () => true,
  isConcurrencySafe: () => false,  // Default not concurrency-safe
  isReadOnly: () => false,          // Default may write
  // ...
}

This means new tools are not allowed concurrent execution by default. When isConcurrencySafe throws exception, catch block also returns false - fallback in conservative direction.

Permission Modes

From strictest to most permissive:

default → acceptEdits → plan → bypassPermissions → auto → dontAsk

System defaults to default - user must actively choose more permissive mode.

YOLO Rejection Tracking

After 3 consecutive or 20 total classifier rejections, system automatically falls back to manual user confirmation.

Core idea: when automated decision-making is unreliable, fall back to human decision.

Anti-Pattern: Default Open, Close When Problems Arise

Tools default to concurrent execution, some tool with side effects produces race conditions in parallel execution - this bug is extremely hard to reproduce and diagnose.

Principle 4: A/B Test Everything

Definition: Behavioral changes are validated in internal user groups first, only expanded to all users after data confirms effectiveness.

89 Feature Flags

Claude Code has 89 Feature Flags, a相当大的一部分用于A/B测试。

ant-only Gating

process.env.USER_TYPE === 'ant'
  ? [ /* internal features */ ]
  : []

Typical comment phrasing:

// @[MODEL LAUNCH]: capy v8 thoroughness counterweight
// (PR #24302) — un-gate once validated on external via A/B

Process: validate internally first, confirm effective, then promote to external users via A/B testing.

GrowthBook Integration

Flags with tengu_* prefix controlled via remote config server, support percentage-based rollout.

Two cache strategies:

  • _CACHED_MAY_BE_STALE: may be stale
  • _CACHED_WITH_REFRESH: with refresh

This reflects “cache-aware A/B testing” - flag value switching shouldn’t cause cache invalidation.

Anti-Pattern: Big Bang Release

Push behavioral changes directly to all users. In AI Agent domain, behavioral change impact is usually not “crash” but “not good enough” or “too aggressive” - requires quantitative metrics and control groups to discover.

Principle 5: Observe Before Fixing

Definition: Before attempting to fix a problem, establish observability infrastructure first to understand the full picture.

Cache Break Detection System

This system doesn’t fix anything - its entire responsibility is observation and reporting:

Before call:

  • recordPromptState() records snapshot of ~20 fields

After call:

  • checkResponseForCacheBreak() compares before/after state, identifies which field changed
  • Translates to human-readable reasons - “system prompt changed,” “TTL likely expired”
  • createPatch() outputs before/after prompt state comparison

Data-Driven Observability

/** Per-tool schema hash. Diffed to name which tool's description changed
 * when toolSchemasChanged but added=removed=0 (77% of tool breaks per
 * BQ 2026-03-22). AgentTool/SkillTool embed dynamic agent/command lists. */
perToolHashes: Record<string, number>

This references specific BigQuery query date and percentage data (77%). Team uses data to drive observability granularity design - not tracking all fields arbitrarily, but based on production data discovering “most tool schema changes come from某个特定tool’s description changes,” then specifically adding per-tool hash.

YOLO Debugging Capability

CLAUDE_CODE_DUMP_AUTO_MODE=1 provides complete input/output export capability, letting developers precisely understand “why classifier rejected this operation.”

Anti-Pattern: Fix by Intuition

Seeing cache hit rate drop and rolling back recent changes, but actual cause could be beta header switch, TTL expiration, or MCP tool list changes.

Principle 6: Latch for Stability

Definition: once entering a state, don’t waver - state oscillation is more harmful than suboptimal state.

Beta Header Latching

afkModeHeaderLatched, fastModeHeaderLatched, cacheEditingHeaderLatched

After first sending a beta header in session, continue sending on all subsequent requests, even if feature is turned off.

Reason: stopping transmission changes request signature, causing cache prefix invalidation.

Cache TTL Eligibility Latching

should1hCacheTTL() executes only once per session, result is latched.

Auto-Compression Circuit Breaker

// Stop trying autocompact after this many consecutive failures.
// BQ 2026-03-10: 1,279 sessions had 50+ consecutive failures
// (up to 3,272) in a single session, wasting ~250K API calls/day globally.
const MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3

After 3 consecutive failures, latch to “stop compressing” state.

BigQuery data in comments (1,279 sessions, 250K API calls/day) provides sufficient engineering justification.

Anti-Pattern: State Oscillation

Recalculate configuration on every request, causing state to switch between different values. In cache system, this means cache keys constantly change, hit rate approaches zero.

Relationship Between Six Principles

Principle 1: Prompts as Control Plane
    ↓
Principle 2: Cache-Aware Design (prompt changes have cost)
    ↓
Principle 6: Latch for Stability (prevent cache oscillation)

Principle 1: Prompts as Control Plane
    ↓
Principle 3: Fail-Closed (safe defaults)
    ↓
Principle 4: A/B Test Everything (verify before opening)
    ↓
Principle 5: Observe Before Fixing (data-driven decisions)
    ↓
Principle 2: Cache-Aware Design

Starting from Prompts as Control Plane:

  • Since behavior is mainly controlled by prompts, prompt changes need cache-aware design to control costs
  • Need latch for stability to prevent oscillation
  • Behavioral safety boundaries guaranteed by fail-closed
  • Transition from closed to open needs A/B testing verification
  • When problems occur, observe before fixing ensures understanding full picture before acting
  • Observation results feed back into cache-aware design

Practical: Applying These Principles

Prompts as Control Plane

  • Create behavior configuration files (like CLAUDE.md), enabling behavior adjustment without code changes
  • Express behavioral expectations in natural language, code only handles structural constraints

Cache-Aware Design

  • Before introducing prompt caching, design cache boundaries first
  • Distinguish between cross-user shared content and session-level content

Fail-Closed

  • Audit your defaults
  • For each config item ask: if user doesn’t set it, is system behavior safest or most dangerous?

A/B Testing

  • Design rollout strategy for key behavioral changes
  • Even with only two user groups (internal/external), safer than full rollout

Observe Before Fixing

  • Add logging before fixing
  • When cache hit rate drops or model behavior is abnormal, record complete context first, then attempt fix

Latch for Stability

  • Identify “latch points” in your system
  • Which states should not change during session lifecycle? Design stability mechanisms in advance

Pattern Extraction

Pattern 1: Prompt-Driven Behavior Control

  • Problem solved: how to guide AI model behavior without coupling with model capability iteration
  • Core approach: express behavioral expectations in natural language prompts, code only handles structural constraints
  • Precondition: model has sufficient instruction-following capability

Pattern 2: Cache Prefix Stabilization

  • Problem solved: prompt cache frequently invalidates due to minor changes
  • Core approach: static/dynamic boundary separation + date memoization + header latching + schema caching
  • Precondition: using API that supports prefix caching

Pattern 3: Fail-Closed Defaults

  • Problem solved: new components introduce security or concurrency risks
  • Core approach: all properties default to safest value, explicit declaration to unlock
  • Precondition: clear definition of “safe” and “unsafe”

Summary

Six Harness Engineering principles:

PrincipleCore ApproachAnti-Pattern
Prompts as Control PlaneExpress behavioral expectations in promptsHardcode behavior
Cache-Aware DesignTreat cache stability as first-class constraintFrequent prompt mutation
Fail-ClosedDefault to safest, explicitly openDefault open, close when problems arise
A/B Test EverythingInternal validation → gradual rollout → full deploymentBig Bang release
Observe Before FixingEstablish observability before fixingFix by intuition
Latch for StabilityOnce in state, don’t waverState oscillation

The common theme across these principles: in AI Agent systems, the best way to control behavior is not writing more code, but designing better constraints.

Understanding these principles lets you:

  • Build more stable, maintainable AI Agent systems
  • Keep systems controllable in rapidly evolving AI field
  • Apply Claude Code’s engineering wisdom to your own projects

Next up: Context Management - The Core Capability of AI Coding.