Visual reference for Claude Code internals: architecture, MCP ecosystem, multi-agent patterns, security models, and development workflows. 38 SVGs rendered at build time, zero client JavaScript.
Core concepts: 4-layer model, workflow pipeline, decision tree, 5 permission modes
Claude Code isn't a chatbot — it's a context system that transforms your message into a rich multi-layer prompt before calling the API. This diagram shows the 4-layer augmentation that happens invisibly with every request.
How Claude Code Works — Line ~2360
Every request to Claude Code goes through this pipeline — from parsing your intent to displaying the final response. Understanding this loop helps you write better instructions and diagnose issues faster.
Getting Started — Line ~277
Not every task needs Claude Code. This decision tree helps you route the right tasks to the right tool — Claude Code CLI vs Claude.ai vs clipboard-based approaches.
Quick Start Decision — See also `machine-readable/reference.yaml` (decide section)
Claude Code has 5 permission modes that control what it can do automatically vs. what requires your approval. Choosing the wrong mode is the #1 safety mistake.
Permission System — Line ~760
Context zones, memory hierarchy, session management, and fresh context patterns
Your context window has 4 distinct zones, each requiring different strategies. Knowing which zone you're in prevents context bloat and maintains response quality throughout long sessions.
Context Management — Line ~1335
Claude Code has 6 distinct memory types with different scopes and persistence. Knowing which memory type to use for each piece of information is key to effective sessions.
Memory System — Line ~3160 & ~3986 | Auto-Memory: v2.1.59+ (v3.30.0)
Sessions don't automatically persist context between terminals. This diagram shows how to save state and resume it in a new session or terminal, enabling async workflows.
Session Management — Line ~9477
Long sessions accumulate noise that degrades response quality. This diagram shows the degradation pattern and the recommended "focused sessions" approach that maintains performance.
Context Best Practices — Line ~1525
Config precedence, skills vs commands vs agents, agent lifecycle, hooks pipeline
Claude Code resolves settings through a strict priority hierarchy. Higher layers override lower ones. Knowing this prevents "why isn't my config working?" bugs.
Configuration System — Line ~3760
Three extensibility mechanisms with different purposes and tradeoffs. Choosing the wrong abstraction leads to over-engineering or under-powered automation.
Extensibility System — Line ~4495, ~5025, ~3900
Sub-agents run in complete isolation from the parent. They receive a copy of context but share no state. Understanding this prevents "why can't my sub-agent see X?" confusion.
Sub-Agents — Line ~3900
Hooks let you run custom code at key points in Claude Code's lifecycle: security scanning, logging, enforcement, notifications. The execution order matters.
Session starts
| (InstructionsLoaded Hook, v2.1.69+)
User message
│
UserPromptSubmit ──exit 2──► feedback to Claude (loop)
│ exit 0
PreToolUse ──exit 2──► BLOCKED
│ exit 0
PermissionRequest ──deny──► BLOCKED
│ allow
Tool executes ......► Subagent? ......► SubagentStop Hook
│ |
+----------------------------------------+
|
PostToolUse
│
More tools? ──yes──► PreToolUse (loop)
│ no
Session ends
│
Stop / SessionEnd Hook
│
Complete
Separately: PreCompact ──► /compact ──► PostCompact
Hook types: command | http | mcp_tool | prompt | agent Hooks System (~line 10147) | HTTP hooks: v2.1.63+ | InstructionsLoaded: v2.1.69+ | PermissionRequest + SubagentStop added 2026-06-03
Master loop, tool categories, system prompt assembly, sub-agent isolation
Claude Code's core execution is two nested loops: an **inner agent loop** that keeps calling the API as long as tool calls are returned, and an **outer conversation loop** that starts a new turn when the user responds.
Architecture: Master Loop — Line ~72
Claude Code has 6 tool categories, each optimized for different operations. Understanding which tool Claude chooses (and why) helps you write instructions that guide better tool selection.
Architecture: Tools — Line ~213
Before every API call, Claude Code assembles a system prompt from multiple sources in a specific order. The prompt is split into two cache zones separated by a boundary marker.
Architecture: System Prompt — Line ~354
Sub-agents are completely isolated from the parent — they can't read the parent's conversation or modify parent state. This isolation is a feature (safety) and a constraint (intentional design).
Architecture: Sub-Agents — Line ~444
MCP server map, architecture, rug pull attack chain, config hierarchy
The MCP ecosystem has 4 categories of servers — official, community-dev, community-ops, and local. Knowing what's available prevents building what already exists.
MCP Ecosystem — Full guide
MCP is a JSON-RPC protocol running over stdio or SSE. Claude Code acts as the client, MCP servers as tool providers. This shows the full request-response cycle.
Architecture: MCP — Line ~795
The most dangerous MCP attack vector: malicious tool descriptions containing hidden prompt injection. This is why you should only install vetted MCP servers.
Security: MCP Threats — Line ~33
MCP server configurations can live in 4 priority levels (3 actual files). The resolution order determines which servers are available and who can override what.
MCP Configuration — Line ~6149
TDD cycle, spec-first pipeline, plan-driven workflow, iterative refinement loop
Test-Driven Development adapted for Claude Code: write the failing test first, then ask Claude to implement only what's needed to pass it. This prevents over-engineering and ensures tests actually verify behavior.
TDD with Claude
Write the specification before the code. Claude uses the spec as the single source of truth — preventing drift between what was planned and what was built.
Spec-First Development
Complex tasks benefit from plan mode: Claude explores the codebase, proposes a plan, you annotate it, then Claude executes only what was approved. Prevents surprises on large refactors.
Plan-Driven Workflow
Output rarely hits the mark on the first try. This loop gives you a systematic way to improve results through targeted feedback rather than "make it better" vague instructions.
Iterative Refinement — Line ~347
When Claude produces a polished-looking output, a cognitive bias kicks in: the more complete the output appears, the less critically most users evaluate it. This is the Artifact Paradox, documented by Anthropic across 9,830 conversations. The diagram shows what separates the 30% of high-fluency users from the 70% who accept first outputs — and the measurable difference in outcome quality.
Anthropic AI Fluency Index (Swanson et al., 2026-02-23) — Guide section: Common Pitfalls
Agent topologies, worktrees, dual-instance planning, horizontal scaling, decision matrix
Three proven topologies for multi-agent coordination. Choose based on task independence, ordering requirements, and specialization needs.
Agent Teams — Line ~59
Git worktrees enable true parallel development: each Claude instance works in an isolated branch with its own working tree. No conflicts, no context mixing.
Git Worktrees — Line ~10634
Separating planning from execution using two Claude instances prevents costly mistakes: the planner Claude has no tools, so it can't accidentally execute anything during analysis.
Dual-Instance Planning
When tasks can be parallelized, spawn N Claude instances simultaneously instead of running them sequentially. The speedup is proportional to task independence.
Horizontal Scaling — Line ~9617
Not every task needs multiple instances. This decision tree guides you to the right pattern based on task characteristics.
Multi-Instance Patterns — Line ~11176
3-layer defense, sandbox decision, verification paradox, CI/CD pipeline
Defense in depth for Claude Code: prevention stops most threats, detection catches what slips through, and response limits blast radius. No single layer is sufficient.
Security Hardening — Full guide
Sandboxing adds overhead. Use this tree to decide when it's mandatory, recommended, or optional for your situation.
Sandbox Native — Line ~512
Asking Claude to verify its own work is circular. The same model that produced the bug will often miss it during review. This anti-pattern causes production incidents.
Production Safety — Line ~639
Claude Code can run in non-interactive mode inside CI/CD pipelines for automated code review, documentation, and quality checks on every PR.
PR created → GitHub Actions → setup ANTHROPIC_API_KEY
│
claude --print --headless
│
┌───────────────┼────────────────┐
Lint Tests Security
│
All pass? ──No──► Fail PR + report
│ Yes
✓ Green → human review → merge CI/CD Integration — Line ~6835
Model selection, cost optimization, subscription tiers, token reduction strategies
Not all tasks need the most powerful model. Using the right model for the right task cuts costs by 5-10x without sacrificing quality. > **This diagram assumes an unconstrained budget (Max/API).** On tighter plans (Pro, Teams Standard), apply the budget modifier below.
Task complexity? ├─ Simple (typos, format, rename) → Haiku 4.5 ($ ~5x cheaper than Sonnet) ├─ Standard (features, bugs) → Sonnet 4.5/4.6 ($$ best price/quality ratio) └─ Complex (architecture, sec.) ├─ Needs deep reasoning? → Opus 4.8 (xhigh) ($$$ ~5x more than Sonnet) └─ Just large/clear? → Sonnet 4.6 ($$ handles it) Budget modifier (downgrade one tier on constrained plans): Max/API (xhigh) → Opus 4.8 plan, Sonnet impl Max/API → Opus 4.8 plan, Sonnet impl Pro/Teams → Sonnet plan, Haiku impl (mechanical tasks)
Model Selection (Line ~2634)
High token costs are usually fixable. This systematic tree identifies the root cause and points to the right fix for each waste pattern.
Cost Optimization (Line ~8878)
Different tiers unlock different Claude Code capabilities. Knowing the limits helps you plan usage and justify upgrades.
Subscription Tiers (Line ~1933)
Multiple strategies stack for cumulative token savings. Apply them in order from highest impact to lowest effort.
Token Optimization (Line ~13355)
Onboarding paths, UVAL learning protocol, trust calibration matrix
Different backgrounds require different onboarding approaches. Forcing developers through a beginner path wastes time; dropping non-technical users into advanced features causes frustration.
Adoption Approaches
The UVAL protocol prevents the "copy-paste trap" — where you use Claude Code without understanding what it did. Each cycle builds real competency that survives tool unavailability.
Learning with AI — Line ~127
Knowing when to trust Claude's output and when to verify is the most important skill in AI-assisted development. Over-trust causes bugs; under-trust eliminates productivity gains.
Trust and Verification — Line ~1039
3-layer context system, adherence degradation, modular architecture, rule placement decision tree
Context engineering operates across 3 distinct layers with different scopes and persistence. Understanding which layer to use prevents the most common mistake: cramming everything into one file.
Context Engineering — Configuration Hierarchy
Adherence to CLAUDE.md rules degrades predictably as file size grows. Beyond ~150 rules, models begin selectively ignoring instructions. Path-scoping is the primary fix — it reduces always-on context by 40-50% without losing coverage.
Context Budget — Adherence data: HumanLayer production data (15-25% improvement with structured context)
The monolithic CLAUDE.md is the most common failure mode in team contexts. Path-scoped modules fix it by loading only what's relevant for the current task.
Modular Architecture — Path-scoping pattern
Every new instruction or convention needs to land in the right layer. Wrong placement wastes tokens (too global) or loses coverage (too scoped). This tree makes the decision explicit.
Rule Placement — Decision tree from §3
Governance risk tiers, MCP approval workflow, guardrail tier selection
Not everything needs heavy governance. This decision tree routes your context to the right control level based on actual risk — from personal dev workflow (minimal) to regulated environments (full compliance stack).
Enterprise Governance — §1 Governance Split, §4 Guardrail Tiers
Individual MCP vetting takes 5 minutes. Organizational MCP governance is the 5-step pipeline that ensures approved servers stay approved, versions are pinned, and risk is classified before deployment.
MCP Governance Workflow — §3.1 Approval Workflow
Data classification determines what Claude Code is allowed to read and process. Getting this wrong is the highest-impact governance failure. Four levels, clear rules, no exceptions for RESTRICTED.
AI Usage Charter — §2.1 Data Classification
mermaid-cli (mmdc) with a neutral theme and transparent background. Zero client-side JavaScript, diagrams load instantly with no layout shift.guide/diagrams/ on GitHub. Each .md file contains Mermaid syntax, an ASCII fallback, and a reference to the relevant guide section.