12 Harness Design Patterns from Claude Code: Memory, Workflow, Tools, and Automation

Part 1 Memory & Context

1 Persistent Instruction File Pattern – Stores static rules (build, test, naming, coding standards) in a project‑level file that loads on each start, preventing agents from starting with a blank slate. Applicable when the agent works across multiple sessions on the same codebase. Cost: the file must evolve with the project, or stale rules cause errors.

2 Scoped Context Assembly Pattern – Dynamically loads instruction files per scope (organization, user, repo root, parent, child). The import syntax splits a monolithic rule set into multiple files, avoiding duplication. Best for monorepos or multilingual projects with directory‑specific conventions. Cost: discoverability suffers and rule conflicts can produce unexpected behavior.

3 Tiered Memory Pattern – Divides agent memory into three layers: a compact index (always in context, limited to ~200 lines), on‑demand loaded topic‑relevant files, and full session logs on disk. This reduces token waste and keeps useful information accessible. Useful when an agent must retain preferences, decisions, and workflow state across sessions. Cost: added complexity in deciding placement, upgrades, and synchronization between layers.

4 Dream Consolidation Pattern – Runs a background process during idle time to de‑duplicate, prune, and reorganize memory, akin to garbage collection. The "autoDream" mode merges duplicates, trims contradictions, and keeps the index compact. Fits agents that accumulate memory over many sessions without manual cleanup. Cost: token consumption during consolidation and risk of over‑pruning needed data.

5 Progressive Context Compaction Pattern – Applies multi‑stage compression based on dialogue age: recent turns stay full, slightly older turns get light summarization, and very old turns undergo aggressive folding. The leaked code defines four layers (HISTORY_SNIP, Microcompact, CONTEXT_COLLAPSE, Autocompact). Ideal for conversations exceeding 20‑30 rounds. Cost: lossy compression may discard details needed later, causing the agent to hallucinate.

Part 2 Workflow & Orchestration

6 Explore‑Plan‑Act Loop Pattern – Splits work into three phases with gradually increasing write permissions. In the explore phase the agent only reads and maps the codebase; in the plan phase it discusses solutions with the user; only in the act phase are full tool permissions granted. Applicable to unfamiliar codebases or multi‑file non‑trivial changes. Cost: slower output due to extra exploratory and planning rounds.

7 Context‑Isolated Subagents Pattern – Creates separate sub‑agents with isolated context windows, system prompts, and restricted tool access: a research sub‑agent (read‑only), a planning sub‑agent (no execution), and an execution sub‑agent (full tools). Useful for long, multi‑stage sessions with divergent context needs. Cost: coordination overhead; details may be lost when passing information between sub‑agents.

8 Fork‑Join Parallelism Pattern – Generates multiple sub‑agents that operate in isolated git worktrees on independent units of work, sharing the parent’s cached context. After parallel execution, results are merged. Fits tasks that can be decomposed into independent, non‑dependent units. Cost: merging complexity and potential conflicts when parallel branches touch overlapping files.

Part 3 Tools & Permissions

9 Progressive Tool Expansion Pattern – Starts the agent with a minimal default tool set (Read, Edit, Write, Bash, Grep, Glob) and activates additional tools (MCP, remote tools, custom skills) only when needed. Best when the agent has many tools but most tasks require only a few. Cost: added harness logic to decide activation timing; late activation can waste rounds.

10 Command Risk Classification Pattern – Applies deterministic pre‑parsing and per‑tool allow/ask/deny rules. Commands are classified by verb, flags, and target to assess risk; low‑risk commands are auto‑approved, high‑risk ones trigger safety checks. Relevant when agents can execute shell commands or interact with external systems. Cost: rigidity; classifiers need continuous tuning to handle new safe or dangerous commands.

11 Single‑Purpose Tool Design Pattern – Replaces generic shell commands with specialized tools (FileReadTool, FileEditTool, GrepTool, GlobTool) that have typed inputs, limited scope, and explicit permission rules. Ideal for agents that frequently perform common file and search operations. Cost: reduced flexibility; edge cases may still require a fallback generic shell.

Part 4 Automation

12 Deterministic Lifecycle Hooks Pattern – Defines over 25 hook points (e.g., PreToolUse, PostToolUse, SessionStart, CwdChanged) that automatically run shell commands or other actions at specific lifecycle stages, independent of prompt instructions. Used for actions that must never be skipped, such as formatting after file edits or validation before execution. Cost: debugging is harder because hook failures occur outside the conversational flow.

Takeaway

These twelve patterns are not fleeting tricks or product features; they constitute the foundational architecture of an agentic harness. Memory layering, context compression, permission gating, and deterministic lifecycle hooks are design decisions that remain relevant even as underlying models and tools evolve.