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](docs/distillation-harness-practice.md) 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](https://github.com/vercel-labs/skills). 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](https://github.com/anthropics/claude-code) — 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**](skills/agentic-harness-patterns/SKILL.md#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**](skills/agentic-harness-patterns/SKILL.md#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**](skills/agentic-harness-patterns/SKILL.md#3-tools-and-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**](skills/agentic-harness-patterns/SKILL.md#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**](skills/agentic-harness-patterns/SKILL.md#5-multi-agent-coordination) | "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**](skills/agentic-harness-patterns/SKILL.md#6-lifecycle-and-extensibility) | "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](skills/agentic-harness-patterns/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](skills/agentic-harness-patterns/references/memory-persistence-pattern.md) | Four-level instruction hierarchy, four-type auto-memory, background extraction with mutual exclusion | | [skill-runtime-pattern](skills/agentic-harness-patterns/references/skill-runtime-pattern.md) | Four-source discovery, YAML frontmatter contract, budget-constrained listing, graceful degradation | | [tool-registry-pattern](skills/agentic-harness-patterns/references/tool-registry-pattern.md) | Fail-closed builder, per-call concurrency, partition-sort-concatenate for cache stability | | [permission-gate-pattern](skills/agentic-harness-patterns/references/permission-gate-pattern.md) | Single gate, three behaviors, strict layered evaluation, atomic claim for race-safe resolution | | [agent-orchestration-pattern](skills/agentic-harness-patterns/references/agent-orchestration-pattern.md) | Mutual exclusion of modes, fork cache optimization, flat swarm topology, tool filtering layers | | [context-engineering](skills/agentic-harness-patterns/references/context-engineering-pattern.md) | Index: select / compress / isolate sub-pattern routing | | [select-pattern](skills/agentic-harness-patterns/references/context-engineering/select-pattern.md) | Promise memoization, three-tier progressive disclosure, manual cache invalidation | | [compress-pattern](skills/agentic-harness-patterns/references/context-engineering/compress-pattern.md) | Truncation with recovery pointers, reactive compaction, snapshot labeling | | [isolate-pattern](skills/agentic-harness-patterns/references/context-engineering/isolate-pattern.md) | Zero-inheritance default, single-level fork boundary, worktree-based filesystem isolation | | [hook-lifecycle-pattern](skills/agentic-harness-patterns/references/hook-lifecycle-pattern.md) | Single dispatch, all-or-nothing trust, six hook types, exit-code discipline | | [task-decomposition-pattern](skills/agentic-harness-patterns/references/task-decomposition-pattern.md) | Typed prefixed IDs, strict state machine, disk-backed output, two-phase eviction | | [bootstrap-sequence-pattern](skills/agentic-harness-patterns/references/bootstrap-sequence-pattern.md) | 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. 1. **Deep exploration** — 4 parallel agents mapped the full source tree (~1,900 files) 2. **Source-grounded drafting** — 7 parallel agents each drafted one reference, tracing claims to source files 3. **Factual review** — 3 independent review rounds verified each claim against source code 4. **Abstraction uplift** — Implementation details pushed into "Evidence" sections; principles generalized to be runtime-portable 5. **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](docs/distillation-harness-practice.md)**. ## Installation > [!TIP] > Two skills available: `agentic-harness-patterns` (English) and `agentic-harness-patterns-zh` (Chinese). Install via the [Vercel Skills CLI](https://github.com/vercel-labs/skills) — works with Claude Code, Codex, and 40+ other agents. ```bash npx skills add github:keli-wen/agentic-harness-patterns-skill ```
