Navigation Explore Code Guide
Claude Code: Visual Reference
Last updated:
All diagrams in one place. Quick visual overview of Claude Code’s key concepts. For detailed docs → Ultimate Guide | Cheatsheet
Interactive Mermaid diagrams available: For 40 interactive diagrams covering model selection, agent lifecycle, memory hierarchy, multi-agent patterns, security threats, and more, see guide/diagrams/. This file contains ASCII versions of key concepts.
20 diagrams: 8 new (this file) + 12 from existing guides, all consolidated here.
Harness Map Reading Guide
Section titled “Harness Map Reading Guide”These ASCII diagrams cover selected Claude Code concepts. For the harness taxonomy, use the three figures on the Agent Harness Map: strict and broad scope, the four layers, and the selection funnel. Agent Harness Engineering explains the model, runtime harness, repository harness, and orchestrator. Agent Tools: Beyond Claude Code covers frameworks and control planes. Use Agent Evaluation, Session Observability, and Security Hardening to test, inspect, and constrain the chosen design. Definitions are in the glossary.
Table of Contents
Section titled “Table of Contents”New diagrams:
Architecture & Internals: 5. Master Loop 6. Hook Event Flow 7. Data Privacy Flow
Security: 8. MCP Rug Pull Attack 9. Docker Sandbox Architecture
Decision Trees: 10. Search Tool Selection 11. Trust Calibration Flow 12. Adoption Decision Tree 13. Methodology Selection
Workflows: 14. Research → Spec → Code 15. Review Auto-Correction Loop 16. PDF Pipeline Stack
Development & Learning: 17. TDD Red-Green-Refactor Cycle 18. UVAL Protocol Flow
Security (extended): 19. Security 3-Layer Defense 20. Secret Exposure Timeline
1. Context Management Zones
Section titled “1. Context Management Zones”How to react based on context window usage (check with /status):
Context Usage0% 50% 70% 90% 100%├───────────┼───────────┼───────────┼──────────┤│ GREEN │ YELLOW │ ORANGE │ RED ││ work │ selective │ /compact │ /clear ││ freely │ with care │ NOW │ required │└───────────┴───────────┴───────────┴──────────┘ ▲ ▲ │ │ Be selective Risk: forgetting about reads instructions, and tool use hallucinationsActions by zone:
- Green (0-50%): Full speed. Read files, explore freely.
- Yellow (50-70%): Be selective. Avoid unnecessary file reads.
- Orange (70-90%): Run
/compactimmediately. Context is degrading. - Red (90%+): Run
/clearand restart. Responses are unreliable.
→ Source: ultimate-guide.md:1335
2. Permission Modes Cycle
Section titled “2. Permission Modes Cycle”Cycle through modes with Shift+Tab:
Shift+Tab Shift+Tab ┌──────────┐ ────────────→ ┌───────────────┐ ────────────→ ┌───────────┐ │ DEFAULT │ │ AUTO-ACCEPT │ │ PLAN MODE │ │ │ │ │ │ │ │ edit=ask │ │ edit=auto │ │ edit=no │ │ exec=ask │ │ exec=ask │ │ exec=no │ └──────────┘ ←──────────── └───────────────┘ ←──────────── └───────────┘ Shift+Tab Shift+TabWhen to use each mode:
| Mode | Use when… | Risk level |
|---|---|---|
| Default | Normal development: review each change | Low |
| Auto-accept | Trusted tasks (formatting, refactoring) | Medium |
| Plan mode | Complex/risky operations: explore safely first | None |
Shortcuts:
Shift+Tab: Cycle to next modeShift+Tab × 2: Jump to plan mode from default/plan: Enter plan mode directly- Exit plan mode: approve the plan Claude presents, or press
Shift+Tab(there is no/executecommand)
→ Source: ultimate-guide.md:760
3. Workflow Pipeline (9 Steps)
Section titled “3. Workflow Pipeline (9 Steps)”The recommended workflow for every task:
┌─────────┐ ┌──────────┐ ┌────────────┐ ┌─────────────┐ │ 1.START │───→│ 2./status│───→│ 3. plan? │───→│ 4. describe │ │ claude │ │ check ctx│ │ Shift+Tab×2│ │ WHAT/WHERE │ └─────────┘ └──────────┘ │ (if risky) │ │ HOW/VERIFY │ └────────────┘ └──────┬──────┘ │ ┌───────────────────────────────────────────────────┘ │ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ 5.review │───→│ 6. y/n │───→│ 7. test │───→│ 8.commit │───→│9./compact│ │ diff │ │ accept? │ │ run │ │ when done│ │ when >70%│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘Key principles:
- Step 2: Always check context before starting. If >70%,
/compactfirst. - Step 3: Use plan mode for anything risky, complex, or multi-file.
- Step 4: Be specific. Vague prompts produce vague results.
- Step 5: Read every diff. Never blindly accept.
- Step 9: Compact after each task to stay in the green zone.
→ Source: ultimate-guide.md:277
4. Quick Decision Tree
Section titled “4. Quick Decision Tree”What to do based on your situation:
What do you need?│├─ Simple task ─────────────────→ Just ask Claude│├─ Complex task│ ├─ Single session ───────────→ /plan + Tasks API│ └─ Multi-session ────────────→ Tasks API + CLAUDE_CODE_TASK_LIST_ID│├─ Repeating task ──────────────→ Create agent or command│├─ Context >70% ────────────────→ /compact│├─ Context >90% ────────────────→ /clear (restart conversation)│├─ Need library docs ───────────→ Context7 MCP│├─ Deep debugging ──────────────→ Opus model + Alt+T (thinking)│├─ UI from design ──────────────→ Figma MCP or screenshot input│└─ Team rollout ────────────────→ Read adoption-approaches.md→ Source: reference.yaml (decide section)
5. Master Loop
Section titled “5. Master Loop”The entire architecture is a simple while loop: no DAG, no classifier, no RAG.
┌─────────────────────────────────────────────────────────────┐│ CLAUDE CODE MASTER LOOP │├─────────────────────────────────────────────────────────────┤│ ││ ┌──────────────┐ ││ │ Your Prompt │ ││ └──────┬───────┘ ││ │ ││ ▼ ││ ┌──────────────────────────────────────────────────────┐ ││ │ │ ││ │ CLAUDE REASONS │ ││ │ (No classifier, no routing layer) │ ││ │ │ ││ └────────────────────────┬─────────────────────────────┘ ││ │ ││ ▼ ││ ┌────────────────┐ ││ │ Tool Call? │ ││ └───────┬────────┘ ││ │ ││ YES │ NO ││ ┌─────────────────┴─────────────────┐ ││ │ │ ││ ▼ ▼ ││ ┌────────────┐ ┌────────────┐ ││ │ Execute │ │ Text │ ││ │ Tool │ │ Response │ ││ │ │ │ (DONE) │ ││ └─────┬──────┘ └────────────┘ ││ │ ││ ▼ ││ ┌─────────────┐ ││ │ Feed Result │ ││ │ to Claude │──────────────────┐ ││ └─────────────┘ │ ││ │ ││ ▼ ││ ┌────────────────┐ ││ │ LOOP BACK │ ││ │ (Next turn) │ ││ └────────────────┘ ││ │└─────────────────────────────────────────────────────────────┘→ Source: architecture.md:84
6. Hook Event Flow
Section titled “6. Hook Event Flow”How hooks intercept Claude Code’s execution pipeline:
┌─────────────────────────────────────────────────────────┐│ EVENT FLOW │├─────────────────────────────────────────────────────────┤│ ││ User types message ││ │ ││ ▼ ││ ┌────────────────────┐ ││ │ UserPromptSubmit │ ← Add context (git status) ││ └────────────────────┘ ││ │ ││ ▼ ││ Claude decides to run tool (e.g., Edit) ││ │ ││ ▼ ││ ┌────────────────────┐ ││ │ PreToolUse │ ← Security check ││ └────────────────────┘ ││ │ ││ ▼ (if allowed) ││ Tool executes ││ │ ││ ▼ ││ ┌────────────────────┐ ││ │ PostToolUse │ ← Auto-format ││ └────────────────────┘ ││ │└─────────────────────────────────────────────────────────┘→ Source: ultimate-guide.md:6327
7. Data Privacy Flow
Section titled “7. Data Privacy Flow”What data leaves your machine when using Claude Code:
┌─────────────────────────────────────────────────────────────┐│ YOUR LOCAL MACHINE │├─────────────────────────────────────────────────────────────┤│ • Prompts you type ││ • Files Claude reads (including .env if not excluded!) ││ • MCP server results (SQL queries, API responses) ││ • Bash command outputs ││ • Error messages and stack traces │└───────────────────────┬─────────────────────────────────────┘ │ ▼ HTTPS┌─────────────────────────────────────────────────────────────┐│ ANTHROPIC API │├─────────────────────────────────────────────────────────────┤│ • Processes your request ││ • Stores conversation based on retention policy ││ • May use data for model training (if not opted out) │└─────────────────────────────────────────────────────────────┘→ Source: data-privacy.md:24
8. MCP Rug Pull Attack
Section titled “8. MCP Rug Pull Attack”How a malicious MCP server can exploit the one-time approval model:
┌─────────────────────────────────────────────────────────────┐│ 1. Attacker publishes benign MCP "code-formatter" ││ ↓ ││ 2. User adds to ~/.claude.json, approves once ││ ↓ ││ 3. MCP works normally for 2 weeks (builds trust) ││ ↓ ││ 4. Attacker pushes malicious update (no re-approval!) ││ ↓ ││ 5. MCP exfiltrates ~/.ssh/*, .env, credentials │└─────────────────────────────────────────────────────────────┘MITIGATION: Version pinning + hash verification + monitoring→ Source: security-hardening.md:33
9. Docker Sandbox Architecture
Section titled “9. Docker Sandbox Architecture”Full isolation for autonomous Claude Code sessions:
┌──────────────────────────────────────────────────────────┐│ HOST MACHINE ││ ││ ┌────────────────────────────────────────────────────┐ ││ │ DOCKER SANDBOX (microVM) │ ││ │ │ ││ │ ┌──────────────┐ ┌───────────────────────────┐ │ ││ │ │ Claude Code │ │ Private Docker daemon │ │ ││ │ │ (--dsp mode) │ │ (isolated from host) │ │ ││ │ └──────────────┘ └───────────────────────────┘ │ ││ │ │ ││ │ ┌──────────────────────────────────────────────┐ │ ││ │ │ Workspace: ~/my-project (synced with host) │ │ ││ │ │ Same absolute path as host │ │ ││ │ └──────────────────────────────────────────────┘ │ ││ │ │ ││ │ Base: Ubuntu, Node.js, Python 3, Go, Git, │ ││ │ Docker CLI, GitHub CLI, ripgrep, jq │ ││ │ User: non-root 'agent' with sudo │ ││ └────────────────────────────────────────────────────┘ ││ ││ Host Docker daemon: NOT accessible from sandbox ││ Host filesystem: NOT accessible (except workspace) │└──────────────────────────────────────────────────────────┘→ Source: sandbox-isolation.md:87
10. Search Tool Selection
Section titled “10. Search Tool Selection”3-level decision tree for choosing the right search tool:
Level 1: What Do You Know?
Do you know the EXACT text/pattern?│├─ YES → Use rg (ripgrep)│ ├─ Known function name: rg "createSession"│ ├─ Known import: rg "import.*React"│ └─ Known pattern: rg "async function"│└─ NO → Go to Level 2Level 2: What Are You Looking For?
What's your search intent?│├─ "Find by MEANING/CONCEPT"│ → Use grepai│ └─ Example: grepai search "payment validation logic"│├─ "Find FUNCTION/CLASS definition"│ → Use Serena│ └─ Example: serena find_symbol --name "UserController"│├─ "Find by CODE STRUCTURE"│ → Use ast-grep│ └─ Example: async without error handling│└─ "Understand DEPENDENCIES" → Use grepai trace └─ Example: grepai trace callers "validatePayment"Level 3: Optimization
Found too many results?│├─ rg → Add --type filter or narrow path├─ grepai → Add --path filter or use trace├─ Serena → Filter by symbol type (function/class)└─ ast-grep → Add constraints to pattern→ Source: search-tools-mastery.md:75
11. Trust Calibration Flow
Section titled “11. Trust Calibration Flow”How much to review AI-generated code based on risk level:
┌─────────────────────────────────────────────────────────┐│ TRUST CALIBRATION FLOW │├─────────────────────────────────────────────────────────┤│ ││ AI generates code ││ │ ││ ▼ ││ ┌──────────────┐ ││ │ What type? │ ││ └──────────────┘ ││ │ │ │ ││ ▼ ▼ ▼ ││ Boiler Business Security ││ -plate logic critical ││ │ │ │ ││ ▼ ▼ ▼ ││ Skim Test + Full review ││ only review + tools ││ │ │ │ ││ └──────┴────────┘ ││ │ ││ ▼ ││ Tests pass? ──No──► Debug & fix ││ │ ││ Yes ││ │ ││ ▼ ││ Ship it ││ │└─────────────────────────────────────────────────────────┘→ Source: ultimate-guide.md:1182
12. Adoption Decision Tree
Section titled “12. Adoption Decision Tree”How to choose your Claude Code adoption strategy:
Starting Claude Code?│├─ Need to ship today?│ └─ YES → Turnkey Quickstart│ └─ NO ↓│├─ Team needs shared conventions?│ └─ YES → Turnkey + document what matters to you│ └─ NO ↓│├─ Want to understand before configuring?│ └─ YES → Autonomous Learning Path│ └─ NO → Turnkey, adjust as you go→ Source: adoption-approaches.md:51
13. Methodology Selection
Section titled “13. Methodology Selection”Which development methodology to use:
┌─ "I want quality code" ────────────→ workflows/tdd-with-claude.md│├─ "I want to spec before code" ─────→ workflows/spec-first.md│├─ "I need to plan architecture" ────→ workflows/plan-driven.md│├─ "I'm iterating on something" ─────→ workflows/iterative-refinement.md│└─ "I need methodology theory" ──────→ methodologies.md→ Source: methodologies.md:24
14. Research → Spec → Code
Section titled “14. Research → Spec → Code”Using Perplexity for research, then Claude Code for implementation:
┌─────────────────────────────────────────────────────────┐│ 1. PERPLEXITY (Deep Research) ││ "Research best practices for JWT refresh tokens ││ in Next.js 15. Include security considerations, ││ common pitfalls, and library recommendations." ││ ││ → Output: 2000-word spec with sources │└───────────────────────────┬─────────────────────────────┘ ↓ Export as spec.md┌─────────────────────────────────────────────────────────┐│ 2. CLAUDE CODE ││ > claude ││ "Implement JWT refresh tokens following spec.md. ││ Use the jose library as recommended." ││ ││ → Output: Working implementation with tests │└─────────────────────────────────────────────────────────┘→ Source: ai-ecosystem.md:155
15. Review Auto-Correction Loop
Section titled “15. Review Auto-Correction Loop”Iterative code review pattern where Claude reviews, fixes, and re-reviews:
┌─────────────────────────────────────────┐│ Review Auto-Correction Loop ││ ││ Review (identify issues) ││ ↓ ││ Fix (apply corrections) ││ ↓ ││ Re-Review (verify fixes) ││ ↓ ││ Converge (minimal changes) → Done ││ ↑ ││ └──── Repeat (max iterations) │└─────────────────────────────────────────┘→ Source: iterative-refinement.md:354
16. PDF Pipeline Stack
Section titled “16. PDF Pipeline Stack”Quarto + Typst stack for generating professional PDFs:
┌─────────────────────────────────────────────────┐│ Your .qmd File ││ (Markdown + YAML frontmatter) │└─────────────────────────────────────────────────┘ │ ▼┌─────────────────────────────────────────────────┐│ Quarto ││ (Document rendering engine) ││ • Processes YAML metadata ││ • Handles extensions ││ • Manages output formats │└─────────────────────────────────────────────────┘ │ ┌─────────────┴─────────────┐ ▼ ▼┌─────────────────────┐ ┌─────────────────────┐│ Pandoc │ │ Typst ││ (MD → AST → ?) │ │ (Typography/PDF) ││ • Markdown parser │ │ • Modern engine ││ • AST transforms │ │ • Fast compilation ││ • Format bridges │ │ • No LaTeX needed │└─────────────────────┘ └─────────────────────┘ │ ▼┌─────────────────────────────────────────────────┐│ document.pdf ││ (Professional typography output) │└─────────────────────────────────────────────────┘→ Source: pdf-generation.md:58
17. TDD Red-Green-Refactor Cycle
Section titled “17. TDD Red-Green-Refactor Cycle”The iterative loop at the heart of Test-Driven Development:
┌──────────────────────────┐ │ │ ▼ │ ┌──────────────┐ │ │ 🔴 RED │ │ │ │ │ │ Write a │ │ │ failing │ │ │ test │ │ └──────┬───────┘ │ │ │ │ Tests FAIL │ │ (expected) │ ▼ │ ┌──────────────┐ │ │ 🟢 GREEN │ │ │ │ │ │ Write │ │ │ minimal │ │ │ code to │ │ │ pass │ │ └──────┬───────┘ │ │ │ │ Tests PASS │ │ (minimal) │ ▼ │ ┌──────────────┐ │ │ 🔵 REFACTOR│ │ │ │ │ │ Clean up │ │ │ while tests │ │ │ stay green │ │ └──────┬───────┘ │ │ │ │ Next feature │ └───────────────────────────┘
Key rules: RED → Test must FAIL before writing implementation GREEN → Write ONLY enough code to pass (no more) REFACTOR → Improve structure, tests must stay green REPEAT → One feature at a time, always in this orderSource: workflows/tdd-with-claude.md:78
18. UVAL Protocol Flow
Section titled “18. UVAL Protocol Flow”Systematic framework for learning with AI without losing your edge:
┌────────────────────────────────────────────────────────────┐ │ UVAL PROTOCOL │ │ (Use AI without losing your edge) │ └────────────────────────────────────────────────────────────┘
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ U │ │ V │ │ A │ │ L │ │UNDERSTAND│────→│ VERIFY │────→│ APPLY │────→│ LEARN │ │ │ │ │ │ │ │ │ │ 15-min │ │ Can you │ │ Modify │ │ Capture │ │ rule: │ │ explain │ │ the code │ │ insights │ │ │ │ it back? │ │ yourself │ │ for long │ │ 1.State │ │ │ │ │ │ term │ │ problem│ │ Test: │ │ Tasks: │ │ │ │ 2.Brain- │ │ explain │ │ • Extend │ │ Methods: │ │ storm │ │ to a │ │ • Modify │ │ • Notes │ │ 3.Find │ │ colleague│ │ • Debug │ │ • Teach │ │ gaps │ │ without │ │ • Adapt │ │ • Blog │ │ 4.Ask │ │ looking │ │ to new │ │ • Review │ │ smart │ │ at code │ │ context│ │ later │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │ ◄── Repeat per concept ──► │ └───────────────────────────────────────────────────┘
If VERIFY fails → go back to UNDERSTAND (you copied, didn't learn) If APPLY fails → go back to VERIFY (you memorized, didn't understand)Source: learning-with-ai.md:208
19. Security 3-Layer Defense
Section titled “19. Security 3-Layer Defense”The full security document (security-hardening.md) organized as 3 defense layers:
┌─────────────────────────────────────────────────────────────┐ │ SECURITY 3-LAYER DEFENSE │ ├─────────────────────────────────────────────────────────────┤ │ │ │ TIME ──────────────────────────────────────────────────► │ │ Before During After │ │ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌───────────────┐ │ │ │ LAYER 1 │ │ LAYER 2 │ │ LAYER 3 │ │ │ │ PREVENTION │ │ DETECTION │ │ RESPONSE │ │ │ │ │ │ │ │ │ │ │ │ • MCP vetting │ │ • Prompt inject │ │ • Secret │ │ │ │ workflow │ │ detection │ │ rotation │ │ │ │ • Version │ │ • Output │ │ • MCP │ │ │ │ pinning │ │ scanning │ │ isolation │ │ │ │ • .claudeignore │ │ • Anomaly │ │ • History │ │ │ │ • Input hooks │ │ monitoring │ │ rewriting │ │ │ │ • Safe MCP list │ │ • Secret leak │ │ • Incident │ │ │ │ • Permissions │ │ detection │ │ reporting │ │ │ │ • Integrity │ │ • Unicode/ANSI │ │ • Post-mortem │ │ │ │ scanning │ │ filtering │ │ & rotation │ │ │ │ │ │ │ │ │ │ │ │ GOAL: Block │ │ GOAL: Catch │ │ GOAL: Limit │ │ │ │ threats at │ │ attacks in │ │ damage and │ │ │ │ entry points │ │ real-time │ │ recover fast │ │ │ └─────────────────┘ └─────────────────┘ └───────────────┘ │ │ │ │ Adoption path: │ │ Solo dev → Layer 1 basics (output scanner) │ │ Team → Layer 1 + 2 (+ injection hooks) │ │ Enterprise → All 3 layers (+ ZDR + verification) │ │ │ └─────────────────────────────────────────────────────────────┘Source: security-hardening.md:24/205/345
20. Secret Exposure Timeline
Section titled “20. Secret Exposure Timeline”Emergency response when a secret (API key, token, password) is exposed:
SECRET EXPOSED — Emergency Response Timeline ═══════════════════════════════════════════════════════════
0 min 15 min 1 hour 24 hours │ │ │ │ ▼ ▼ ▼ ▼ ┌──────────────────┐ ┌─────────────────┐ ┌────────────────┐ │ ⏱️ FIRST 15 MIN │ │ ⏱️ FIRST HOUR │ │ ⏱️ FIRST 24H │ │ Stop the │ │ Assess damage │ │ Remediate │ │ bleeding │ │ │ │ │ │ │ │ 3. Audit git │ │ 6. Rotate ALL │ │ 1. REVOKE key │ │ history │ │ related │ │ immediately │ │ (rewrite if │ │ credentials │ │ (AWS/GH/ │ │ pushed) │ │ │ │ Stripe) │ │ │ │ 7. Notify team │ │ │ │ 4. Scan deps │ │ /compliance │ │ 2. Confirm │ │ for leaked │ │ (GDPR/SOC2) │ │ exposure │ │ keys │ │ │ │ scope │ │ │ │ 8. Document │ │ (local or │ │ 5. Check CI/CD │ │ incident │ │ pushed?) │ │ logs │ │ timeline │ │ │ │ │ │ │ └──────────────────┘ └─────────────────┘ └────────────────┘
SEVERITY GUIDE: ┌─────────────────────────────────────────────────────────┐ │ Local only (not pushed) → Revoke + rotate (steps 1-2) │ │ Pushed to remote → Full timeline (steps 1-8) │ │ Public repo exposure → Assume compromised, rotate │ │ EVERYTHING, check for abuse │ └─────────────────────────────────────────────────────────┘Source: security-hardening.md:347
Back to Guide README | Cheatsheet | Main README