Production design patterns for AI coding agents, distilled from 512,000 lines of Claude Code.
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.
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.
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
| # | 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.
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 |
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
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
Just reading: Open SKILL.md (EN) or SKILL.md (ZH).
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
└── ...
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.
For a deeper exploration of context engineering, see the author's blog One Poem Suffices:
- Context Engineering — conceptual framework and design space
- Just-in-Time Context — principles and practices of on-demand context loading
- Context Engineering from Codex — context engineering through the Codex lens
A deep dive into context engineering in Claude Code is currently in progress.
- 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 addpackage 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.
MIT — see LICENSE.