Visual reference for Claude Code internals: architecture, MCP ecosystem, multi-agent patterns, security models, and development workflows. 50 SVGs generated at build time, with ASCII fallbacks and guide links.
Context components, a teaching workflow, task routing, and six permission modes
This four-part teaching model groups the inputs Claude Code uses. The branches are context categories, not a fixed assembly order. Instructions and tool definitions may load at different times; MCP tools can be deferred until needed.
This nine-stage teaching workflow summarizes a tool-assisted turn. Claude may answer directly, repeat exploration, or stop after an error or interruption. These stages do not specify nine mandatory internal functions.
An author heuristic for choosing an interface. File access and repeated tool execution can make Claude Code useful; pure conversation can suit Claude.ai. This is not a product restriction or a measured time threshold.
Six documented modes change how tool calls are approved. This is a summary: allow/ask/deny rules, working-directory boundaries and protected actions still matter. The availability of auto mode depends on the session.
Context recommendations, memory scopes, native session resume, and focused sessions
These four situations are an author workflow for managing context, not native percentage zones or permission states. Claude manages context automatically; no universal auto-compaction percentage is asserted here.
This six-part teaching taxonomy separates persistent instructions, learned notes, conversation history and external state. It is not a six-level configuration override stack. CLAUDE.md and rules shape context; they do not enforce tool permissions.
Claude Code saves conversations. Reopening a terminal can resume a saved session, or start a fresh conversation with persistent instructions and an optional handoff. A handoff summarizes progress; it does not restore every message.
Unrelated tasks can fill a session with irrelevant history. The author recommendation is to work in focused sessions, use compaction when useful, and preserve a handoff before starting fresh. Saved conversations remain available for resume.
Managed settings precedence, skills and commands, subagents, and hook lifecycle
For the same settings key, the documented stack has five levels, highest first. Lists may merge and security-sensitive exceptions apply. Environment-variable precedence is defined per setting; CLAUDE.md belongs to instruction context, not this settings stack.
Custom commands have been merged into skills. Both file formats create a slash command; skills also support bundled resources and invocation by Claude. Subagents use a separate context window for delegated work. User and project scopes exist for these mechanisms.
A separate context window keeps intermediate tool activity out of the parent conversation. It does not isolate file or service effects. Ordinary subagents start fresh; forks inherit the conversation. A worktree can separate repository edits.
This simplified lifecycle distinguishes session events, turn events and tool events. PermissionRequest is conditional. Hook types and decision controls vary by event; this is not the exhaustive event inventory.
Agentic loop, illustrative tool families, request context, subagent boundaries, and model pipelines
A simplified model-and-tool loop: Claude requests tools, permitted operations run, and their results return to the conversation. Turns can also end because of errors, cancellation or limits. Independent operations may run concurrently; no fixed concurrency limit is asserted.
These six author-defined categories organize examples from the documented tool inventory. Availability varies by Claude Code version, model, surface and configuration; this is not a complete tool list or a native six-category taxonomy.
This conceptual request diagram groups stable instructions with changing conversation context. It does not specify the exact internal assembly order, cache breakpoints or when every input is reread. Instruction files and memory may enter conversation context; MCP definitions can load on demand.
Conversation isolation and filesystem isolation are different boundaries. An ordinary subagent has fresh context; a fork inherits the parent conversation. Both return a final result while permitted operations may affect shared files or external services.
This is a conceptual simplification. Dense versus mixture-of-experts (MoE) describes how the layers are built, and text-only versus vision-language (VLM) describes which inputs the model accepts. These are different axes that can combine: an MoE model can also accept images. Anthropic does not publicly document Claude's internal architecture, so the diagrams show published open designs, not Claude. For the axis table, see [architecture, size class, modality and task](../core/ai-concept-boundaries.md#architecture-size-class-modality-and-task).
MCP maintainers, transports, rug pull risks and configuration precedence
Group servers by their maintainer and purpose. Provider-maintained servers and MCP reference examples have different support expectations. Neither category guarantees a security audit by Anthropic. The old standalone Semgrep MCP repository is deprecated; its server is maintained through the official Semgrep binary.
MCP uses JSON-RPC. Standard transports are stdio and Streamable HTTP; the historical SSE transport remains supported by Claude Code but is deprecated. Streamable HTTP can itself stream replies using SSE. The diagram illustrates a tool-call exchange, not every MCP capability.
A rug pull changes a previously trusted tool or server after installation. A malicious description can try to influence Claude, but reading it does not guarantee execution or exfiltration: permissions and process isolation may block the attempted action. Review source and updates, pin versions where possible, and restrict permissions and network access.
For duplicate server names, local scope precedes project scope, then user scope. Lower-priority plugin servers and claude.ai connectors are also checked for duplicates. CLI configuration is an additional input; use --strict-mcp-config when you intend to ignore other MCP sources, subject to managed policy. Server entries are selected rather than merged across scopes.
Guide: MCP config hierarchy; MCP precedence, CLI configuration flags
TDD, spec-first, plan-driven, refinement and observed AI fluency behaviors
Write a behavior test, observe why it fails, implement the requested behavior, then refactor while keeping checks green. A passing test proves only its assertions. Confirm the feature is not already present when a new test passes before implementation, and distinguish expected failures from setup errors.
Guide: TDD red-green-refactor with Claude; Verification criteria
A specification helps compare intended behavior with implementation; it does not guarantee that drift is impossible. The Maintain loop is a configured automation pattern: a deterministic trigger invokes Claude, an owner triages the resulting intent, and changes pass review and deployment gates. Claude Code does not start this monitoring loop merely because a spec file exists.
Guide: Spec-First development pipeline; Anthropic AI-native SDLC playbook
Use Plan mode to separate exploration from source edits. Cycle Shift+Tab until the status indicates Plan, or launch with --permission-mode plan; the number of keypresses depends on the starting mode. Review the plan, annotate it, then verify the implementation against it. This workflow is a review discipline, not a guarantee that every action will match the plan.
Guide: Plan-Driven workflow with annotation; Explore, plan, implement
Use specific feedback, compare revisions, and stop when explicit criteria are met. Appearance and satisfaction alone do not establish factual correctness; run checks appropriate to the output.
Guide: Iterative refinement loop; Provide verification and context
Anthropic studied 9,830 Claude.ai conversations. Iteration appeared in 85.7% of the sample. Iterative conversations were 5.6 times as likely to show users questioning reasoning, with 2.67 versus 1.33 additional fluency behaviors. In artifact conversations, missing-context identification, fact-checking and reasoning questions were less frequent by 5.2, 3.7 and 3.1 percentage points. These are associations between conversation behaviors, not measured bug catches or proof that polished output causes acceptance bias.
Guide: AI Fluency: Observed collaboration behaviors; Anthropic AI Fluency Index
Conceptual topologies, isolated worktrees, planning, delegation and messaging
Orchestrator, pipeline and specialist routing are conceptual patterns, not three native Agent Teams modes. Native Agent Teams uses a lead and communicating teammates; it is experimental and disabled by default. It adds coordination and token cost. Sequential tasks and edits to the same files often suit a single session or focused subagents better.
Guide: Agent teams: Conceptual orchestration topologies; Agent Teams availability and trade-offs
Worktrees give concurrent instances separate checked-out files and branches. Some repository metadata remains shared, and integrating their changes can still produce merge conflicts. Commands below assume the cloned repository root; each command creates the displayed path.
Guide: Git worktree multi-instance pattern; Git worktree semantics
Use two sessions when a separate planning boundary is useful. A planner with no tools needs the relevant documents supplied in its prompt. Alternatively, Plan mode permits exploration with restricted actions. Configure the restriction explicitly; launching a second session does not disable tools. The executor needs the approved plan and required context, rather than inheriting the planner conversation automatically.
Guide: Dual-Instance planning pattern; Plan permission mode, Subagent tool restrictions
Parallelize independent work with explicit file ownership, then measure the result after coordination and integration. More instances do not guarantee proportional speedup; costs and dependencies can outweigh the benefit. Measure speedup and cost on the workload before making a performance claim.
Guide: Horizontal scaling pattern; Team size, cost and diminishing returns
Choose by dependency, communication and isolation needs before choosing a worker count. The native delegation tool is Agent; Task was its former name and remains a compatibility alias in settings and definitions. There is no four-instance prerequisite for using subagents.
Guide: Multi-Instance decision matrix; Agent tool rename and delegation, Teams versus subagents
Eligible independent sessions can discover peers with ListAgents and send text with SendMessage. Same-machine delivery uses local sockets or named pipes; other-machine and cloud delivery uses Anthropic infrastructure. Explicit crossSessionInbound hold retains messages until an applicable accept releases them. Approval dialogs belong to some permission-mode defaults in supported terminals, not to the explicit hold setting. Availability depends on version, provider and Remote Control requirements.
Guide: Cross-Session messaging: Discovery & delivery; Messaging controls and availability
Enforced defenses, sandbox boundaries, evidence and CI release gates
Prevention, detection and response reduce different risks. Put enforced permissions and process isolation in place before running untrusted work. CLAUDE.md guides the model but does not enforce a security boundary. Sensitive-file protection needs file-tool permission rules and operating-system restrictions, not an assumed ignore-file feature. Logs must be configured and their coverage checked. Bypass permissions is appropriate only in an isolated environment, not merely because a job is labelled CI.
Guide: Security 3-layer defense model; CLAUDE.md compliance limits, Permissions, MCP security
Choose the boundary that covers the process at risk. The native shell sandbox supports macOS (Seatbelt) and Linux/WSL2 (bubblewrap and socat); native Windows needs WSL2 or another isolation environment. File tools, local MCP servers and hooks run outside the shell sandbox. Unknown MCP or hooks require vetting and, where needed, isolation of the entire Claude Code process. acceptEdits auto-approves edits, so it is not a stricter alternative to manual permissions. Native sandbox default reads can include credentials unless explicitly restricted.
Guide: Sandbox decision tree; Native sandbox scope and platforms, Permission modes
Asking the generator for an unsupported opinion does not verify its work. Claude can run deterministic tests and show results; those checks prove only what they exercise. Review critical behavior independently and distinguish code checks from deployment readiness and observed runtime behavior. Passing checks alone do not guarantee a safe release.
Guide: The verification paradox; Runnable verification and adversarial review
CI should run lint, tests and security checks as explicit jobs and use their statuses as gates. Claude Code can read that evidence and produce an advisory review in non-interactive print mode, using claude -p or --print. A prompt does not itself guarantee parallel execution or trustworthy pass/fail aggregation. Configure authentication, tool permissions and job outputs explicitly; enforce release decisions through CI and human review rather than an agent opinion.
Guide: CI/CD integration pipeline; Print-mode CLI, Runnable verification
Model selection, measured cost optimization, subscription capabilities, token reduction strategies
Use model families as candidates, then compare them against the same acceptance criteria. A lower token rate saves money only if quality and total task cost remain acceptable.
Diagnose one recurring source of waste, change it, and replay comparable tasks. If the checks below explain none of the cost, investigate further before calling the baseline acceptable.
Separate product access from usage allowance and organization controls. Parallel CLI sessions share account capacity; they are not a Max-only capability.
Several strategies affect the same token classes. Select one lever, replay the same acceptance gate, and compare total cost, retries and review. Keep or reject that change before testing the next lever; do not multiply advertised reduction percentages.
Onboarding paths, proposed UVAL comprehension practice, trust calibration
Choose a starting path based on responsibilities and existing skills. Progress when the observable criteria pass; no fixed training or team-adoption duration is implied.
UVAL is a proposed practice for checking comprehension during AI-assisted work. It does not establish a retention benefit or replace the policy for accepting a change.
Assess data sensitivity, security and external effects before accepting an output. Tests and rollback establish only their verified scope; a Git revert cannot reverse data disclosure or every external action.
Instruction scopes, context budget checks, conditional rules, rule placement
This teaching view separates global, project and session instructions. It is not a complete inventory of organization policy, auto memory or runtime tool context. Instruction files become model context, not enforced security settings.
There is no universal adherence percentage for a given line count. Review relevance and conflicts, measure the context actually loaded, then compare violations and task outcomes before and after a change.
Move subsystem-specific instructions out of an always-loaded root into native conditional rules or nested CLAUDE.md files. Splitting root imports into more files changes organization but does not itself reduce startup context.
Decide whether a requirement needs enforcement before choosing the scope of its instructional text. A skill provides reusable guidance; a permission rule, hook, script or CI gate must implement and verify any required hard stop.
Proposed risk tiers, MCP approval controls, organization data policies
Choose controls by the effects and sensitivity of the work, then verify that the policy reaches the relevant session. The four tiers are proposed organization patterns, not Anthropic product tiers or regulatory certifications.
Treat the registry as organization bookkeeping and the deployed MCP configuration as a separate control. Review source integrity, permissions, data destinations and advisories; popularity or a patch version does not prove a server safe.
This is an example organization classification policy. Approve the processing route and test access controls for the actual data and integrations. Public content still requires action permissions and can contain malicious instructions.
guide/diagrams/ on GitHub. Each .md file contains Mermaid syntax, an ASCII fallback, and a reference to the relevant guide section.