Agentic Harness Patterns

Production design patterns for AI coding agents, distilled from 512,000 lines of Claude Code.

[!TIP]
How this was built: Read the Distilling Claude Code Source — A Harness Engineering Practice Log for the full story of how Codex and Claude Code collaborated, the PCA-inspired taste injection, and what worked (and didn't).

The model loop is easy. User -> LLM -> tool_use -> execute -> loop fits on a napkin. What makes a production agent actually work — reliably, safely, at scale — is everything around the loop: memory that persists across sessions, permissions that fail closed, context budgets that don't explode, multi-agent coordination that doesn't collapse into chaos, and extensibility that doesn't become a security hole.

Anthropic calls this the harness. This repo teaches you how to build one.

[!NOTE]
This skill is compatible with the open agent skills ecosystem. Install with npx skills add — works with Claude Code, Codex, and 40+ other agents.

What This Is

6 design-pattern chapters and 11 deep-dive references, extracted from systematic source-level analysis of the Claude Code runtime — the production AI coding agent behind Claude's 512,000-line TypeScript codebase.

[!IMPORTANT]
This is not a code dump or a source mirror. Every pattern is expressed as a portable, runtime-agnostic design principle. Claude Code is used as grounding evidence, not as the only possible implementation. If you're building an agent on a different stack, these patterns still apply.

Also not: A Claude Code user guide / prompt engineering tutorial / "agents 101" / model selection guide.

Who Should Read This

Engineers building or extending:

Coding-agent runtimes (like Claude Code, Codex CLI, Gemini CLI, Cursor, Windsurf)
Custom agents and agent plugins
Multi-agent orchestration systems
Any production system where an LLM calls tools in a loop and needs to be reliable

The Six Harness Layers

#	Pattern	The Problem It Solves	Key Insight
1	Memory	"My agent forgets everything between sessions"	Separate instruction memory (human-curated) from auto-memory (agent-written) from session extraction (background-derived). Each has different trust, persistence, and review needs.
2	Skills	"I re-explain workflows every conversation"	Skills are lazy-loaded instruction sets. Discovery must be cheap (~1% of context window); full body loads only on activation. Front-load trigger language — tails get truncated.
3	Tools & Safety	"I want tools powerful but not dangerous"	Default to fail-closed. Concurrency is per-call, not per-tool. The permission pipeline has side effects — it tracks denials, transforms modes, and updates state.
4	Context Engineering	"My agent sees too much, too little, or the wrong thing"	Four operations: select (just-in-time loading), write (the learning loop), compress (reactive compaction), isolate (delegation boundaries).
5	Multi-agent	"I need parallelism without chaos"	Three patterns: Coordinator (zero-inheritance), Fork (full-inheritance, single-level), Swarm (flat peer roster). The coordinator must synthesize, not delegate understanding.
6	Lifecycle	"I need hooks, background tasks, startup sequence"	Hook trust is all-or-nothing. Task eviction is two-phase. Bootstrap is dependency-ordered with trust as the critical inflection point.

[!TIP]
Each pattern includes: Problem -> Golden Rules -> Start Here (actionable first step) -> Tradeoffs -> Gotchas -> Claude Code Evidence. Start with the "Choose Your Problem" table in SKILL.md.

Deep-Dive References

11 reference documents, each following the same structure: Problem (universal) -> Golden Rules (portable) -> Implementation Patterns (no code) -> Gotchas -> Claude Code Evidence (natural language).

Reference	Covers
memory-persistence-pattern	Four-level instruction hierarchy, four-type auto-memory, background extraction with mutual exclusion
skill-runtime-pattern	Four-source discovery, YAML frontmatter contract, budget-constrained listing, graceful degradation
tool-registry-pattern	Fail-closed builder, per-call concurrency, partition-sort-concatenate for cache stability
permission-gate-pattern	Single gate, three behaviors, strict layered evaluation, atomic claim for race-safe resolution
agent-orchestration-pattern	Mutual exclusion of modes, fork cache optimization, flat swarm topology, tool filtering layers
context-engineering	Index: select / compress / isolate sub-pattern routing
select-pattern	Promise memoization, three-tier progressive disclosure, manual cache invalidation
compress-pattern	Truncation with recovery pointers, reactive compaction, snapshot labeling
isolate-pattern	Zero-inheritance default, single-level fork boundary, worktree-based filesystem isolation
hook-lifecycle-pattern	Single dispatch, all-or-nothing trust, six hook types, exit-code discipline
task-decomposition-pattern	Typed prefixed IDs, strict state machine, disk-backed output, two-phase eviction
bootstrap-sequence-pattern	Dependency-ordered init, trust-split env vars, memoized concurrent callers, fast-path dispatch

How This Was Built

[!NOTE]
Not by reading docs or guessing from external behavior.

Deep exploration — 4 parallel agents mapped the full source tree (~1,900 files)
Source-grounded drafting — 7 parallel agents each drafted one reference, tracing claims to source files
Factual review — 3 independent review rounds verified each claim against source code
Abstraction uplift — Implementation details pushed into "Evidence" sections; principles generalized to be runtime-portable
UX audit — Discoverability, audience fit, and principle-to-action gap reviewed from user perspective

For the full story — how Codex and Claude Code collaborated, the handoff protocol, what worked and what didn't — see Distillation Process.

Installation

[!TIP]
Two skills available: agentic-harness-patterns (English) and agentic-harness-patterns-zh (Chinese). Install via the Vercel Skills CLI — works with Claude Code, Codex, and 40+ other agents.

npx skills add github:keli-wen/agentic-harness-patterns-skill

npx skills add screenshot

Just reading: Open SKILL.md (EN) or SKILL.md (ZH).

Project Structure

agentic-harness-patterns/
├── README.md                                       # This file (EN)
├── README_ZH.md                                    # 中文版
├── LICENSE
└── skills/
    ├── agentic-harness-patterns/                   # English skill
    │   ├── SKILL.md
    │   ├── metadata.json
    │   └── references/                             # 11 deep-dive documents
    │       ├── memory-persistence-pattern.md
    │       ├── skill-runtime-pattern.md
    │       ├── permission-gate-pattern.md
    │       ├── agent-orchestration-pattern.md
    │       ├── tool-registry-pattern.md
    │       ├── hook-lifecycle-pattern.md
    │       ├── task-decomposition-pattern.md
    │       ├── bootstrap-sequence-pattern.md
    │       ├── context-engineering-pattern.md       # Index → 3 sub-files
    │       └── context-engineering/
    │           ├── select-pattern.md
    │           ├── compress-pattern.md
    │           └── isolate-pattern.md
    └── agentic-harness-patterns-zh/                # 中文 skill
        ├── SKILL.md                                # Chinese translation
        ├── metadata.json
        └── references/                             # Chinese references
            └── ...

Roadmap

This skill currently covers patterns distilled from Claude Code — arguably the most mature open-source-available agent harness. The long-term goal is to build a unified, cross-runtime pattern library by analyzing additional production agent systems:

Runtime	Status	Notes
Claude Code	Done	Current release — 6 chapters, 11 references
Codex CLI	Planned	OpenAI's agent CLI; distinct context and delegation model
Gemini CLI	Planned	Google's approach to tool orchestration and memory
Unified synthesis	Future	Cross-runtime patterns that survive all three implementations

The hypothesis: patterns that independently emerge across Claude Code, Codex, and Gemini CLI are likely fundamental to the problem domain, not artifacts of any single team's design taste.

Related Work

Anthropic: Effective harnesses for long-running agents — Anthropic's own blog post on the harness concept
Claude Code source repository — the source this analysis is based on
Vercel Skills CLI — the npx skills add package manager

[!WARNING]
Disclaimer: These patterns were distilled by studying the Claude Code source code that was made publicly available. This project is for educational and learning purposes only. No proprietary source code is reproduced. All content represents independently extracted design principles expressed in the author's own words. Claude Code is a trademark of Anthropic, PBC.

License

MIT — see LICENSE.

agentic-harness-patterns-skill