Quick reference for the architectural patterns behind Claude Code. Each pattern is a proven engineering solution — applicable to any agentic system, not just coding tools.
Engine Patterns
| Pattern | What It Does | Learn More |
|---|
| Async Generator Control Flow | The agent loop uses async function* for pull-based streaming. Consumer controls pace; cancel via .return(); pause by not calling next(). | The Agent Loop |
| Derived Flag over API Signal | needsFollowUp is derived from observing tool_use blocks in the response — not from trusting stop_reason metadata. Observe behavior, not labels. | The Agent Loop |
| Escalating Recovery | Retry → increase budget → inject recovery message → switch model → surface error. Each level has a circuit breaker. No level retries itself. | The Agent Loop |
| Concurrency-Safe Partitioning | Each tool declares safe or exclusive per invocation. Default: exclusive. Tools are batched into concurrent and serial groups at runtime. | Tool Orchestration |
| Streaming Tool Execution | Tools begin executing as soon as their block arrives in the API stream — before the full response is received. LLM generation overlaps with tool I/O. | Tool Orchestration |
| Context Modifier Chain | Serial tools can modify shared context for the next tool. Concurrent tools cannot — non-deterministic order would create race conditions. | Tool Orchestration |
Coordination Patterns
| Pattern | What It Does | Learn More |
|---|
| Coordinator Restriction | Coordinator agent limited to 4 tools (create team, delete team, send message, output). Cannot code. Must delegate. Constraint by code, not instruction. | Multi-Agent System |
| Fork Isolation via Worktree | Each fork agent gets a Git worktree on its own branch. Prompt cache shared via byte-identical API prefixes. Anti-recursive guard prevents fork explosion. | Multi-Agent System |
| Disk-Based Async Output | Background tasks write to files. Readers use outputOffset for incremental reads. Crash-safe, unlimited size, multiple readers. | Context & Memory |
Security Patterns
| Pattern | What It Does | Learn More |
|---|
| Permission Classification Pipeline | 6-layer classify-then-decide: safe allowlist → mode → rules → dangerous patterns → AST analysis → denial tracking. 99% fast-pathed at layer 1. | Permission Pipeline |
| Denial Tracking Circuit Breaker | After 3 consecutive denials or 20 total, falls back to prompting user directly. Prevents permission fatigue from repetitive blocked actions. | Permission Pipeline |
Memory Patterns
| Pattern | What It Does | Learn More |
|---|
| Multi-Layer Context Defense | 5 escalating layers: truncate → microcompact → auto-compact → reactive compact → context collapse. Each runs once; failure escalates. | Context & Memory |
| Compact Boundary (Controlled Forgetting) | LLM summarizes conversation into a boundary message. Everything before the boundary is discarded. Keeps decisions, drops transcripts. | Context & Memory |
Extension Patterns
| Pattern | What It Does | Learn More |
|---|
| Conditional Skill Activation | Skills activate by file path patterns. Directory walk discovers .claude/skills/ in ancestor directories. Monorepo-aware. | Skill Engine |
| Shell-in-Prompt Injection | Skills embed shell commands that execute before prompt injection. MCP skills blocked from shell access (remote/untrusted boundary). | Skill Engine |
| 4-Point Plugin Extension | Plugins provide commands + agents + hooks + servers. Single install, multiple capabilities. | Plugin Engine |
| Plugin Security Sandbox | Plugin agents cannot escalate permissions beyond install-time trust. Per-agent permissionMode, hooks, mcpServers blocked. | Plugin Engine |
| Reconciliation-Based Install | Kubernetes-style: diff desired state (settings) vs actual state (disk). Apply changes. Background, non-blocking, hot-reloadable. | Plugin Engine |
How to Read This
These patterns are grouped by concern, not by importance. Most systems will use a subset. Start with the Engine Patterns — they form the foundation everything else builds on.
Every pattern is general-purpose engineering. Replace FileRead with SensorDataTool, replace Bash with RobotControlTool, and the same patterns apply. The architecture is domain-agnostic; coding is just one application.
Why This Matters to You
- Building your own agent? Start with the Engine Patterns — async generator loop + escalating recovery covers 80% of what you need
- Extending Claude Code? The Extension Patterns show how skills, plugins, and hooks compose together
- Debugging slow sessions? The Memory Patterns explain why
/compact works and when to use it
- Understanding permissions? The Security Patterns demystify why Claude asks or doesn’t ask for approval
See also: Architecture Overview — The Agent Loop — Permission Pipeline
