From 24b464802e2d2b9648e1bb5b5c5405c84aa14f74 Mon Sep 17 00:00:00 2001 From: Florian BRUNIAUX Date: Sun, 22 Feb 2026 16:17:52 +0100 Subject: [PATCH] fix(diagrams): replace \n with
in all Mermaid node labels MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mermaid does not support \n for line breaks — rendered literally. Replaced all 276 occurrences with
across 10 diagram files. Co-Authored-By: Claude Sonnet 4.6 --- guide/diagrams/01-foundations.md | 28 +++---- guide/diagrams/02-context-and-sessions.md | 40 +++++----- guide/diagrams/03-configuration-system.md | 30 ++++---- guide/diagrams/04-architecture-internals.md | 46 +++++------ guide/diagrams/05-mcp-ecosystem.md | 56 +++++++------- guide/diagrams/06-development-workflows.md | 66 ++++++++-------- guide/diagrams/07-multi-agent-patterns.md | 80 ++++++++++---------- guide/diagrams/08-security-and-production.md | 80 ++++++++++---------- guide/diagrams/09-cost-and-optimization.md | 74 +++++++++--------- guide/diagrams/10-adoption-and-learning.md | 52 ++++++------- 10 files changed, 276 insertions(+), 276 deletions(-) diff --git a/guide/diagrams/01-foundations.md b/guide/diagrams/01-foundations.md index cec366f..e9b24b8 100644 --- a/guide/diagrams/01-foundations.md +++ b/guide/diagrams/01-foundations.md @@ -23,10 +23,10 @@ flowchart TD E --> F{{Claude API}} F --> G([Claude Response]) - B1[CLAUDE.md files\nglobal + project + subdir] --> B - C1[Working directory\nGit status\nProject files] --> C - D1[Glob, Grep, Read,\nBash, Task, MCP tools] --> D - E1[Previous messages\n+ tool results] --> E + B1[CLAUDE.md files
global + project + subdir] --> B + C1[Working directory
Git status
Project files] --> C + D1[Glob, Grep, Read,
Bash, Task, MCP tools] --> D + E1[Previous messages
+ tool results] --> E style A fill:#F5E6D3,color:#333 style B fill:#6DB3F2,color:#fff @@ -78,7 +78,7 @@ flowchart LR B --> C(Load Context) C --> D(Plan Actions) D --> E(Execute Tools) - E --> F{More tools\nneeded?} + E --> F{More tools
needed?} F -->|Yes| G(Collect Results) G --> E F -->|No| H(Update Context) @@ -125,17 +125,17 @@ Not every task needs Claude Code. This decision tree helps you route the right t ```mermaid flowchart TD - A([Start: I have a task]) --> B{Involves\ncodebase?} - B -->|No| C{Pure writing\nor analysis?} - B -->|Yes| D{Repetitive or\n>30 min manual?} + A([Start: I have a task]) --> B{Involves
codebase?} + B -->|No| C{Pure writing
or analysis?} + B -->|Yes| D{Repetitive or
>30 min manual?} - C -->|Yes| E([Use Claude.ai\nor API]) - C -->|No| F([Clipboard +\nClaude.ai]) + C -->|Yes| E([Use Claude.ai
or API]) + C -->|No| F([Clipboard +
Claude.ai]) - D -->|No| G{Single file,\nsimple change?} - D -->|Yes| H([Claude Code\n✓ Best choice]) + D -->|No| G{Single file,
simple change?} + D -->|Yes| H([Claude Code
✓ Best choice]) - G -->|Yes| I{Need file\naccess?} + G -->|Yes| I{Need file
access?} G -->|No| H I -->|No| F @@ -195,7 +195,7 @@ flowchart TD subgraph BYPASS["⚠️ bypassPermissions Mode"] B1(ALL operations) --> B2([Auto-approved]) - B3["Use only in:\nCI/CD, sandboxed\nenvironments"] --> B2 + B3["Use only in:
CI/CD, sandboxed
environments"] --> B2 end style D2 fill:#7BC47F,color:#333 diff --git a/guide/diagrams/02-context-and-sessions.md b/guide/diagrams/02-context-and-sessions.md index e9825da..17db94d 100644 --- a/guide/diagrams/02-context-and-sessions.md +++ b/guide/diagrams/02-context-and-sessions.md @@ -17,27 +17,27 @@ Your context window has 4 distinct zones, each requiring different strategies. K ```mermaid flowchart LR subgraph GREEN["🟢 0–50% — Comfortable"] - G1(Full capabilities\navailable) + G1(Full capabilities
available) G2(All tools active) G3(Rich responses) end subgraph BLUE["🔵 50–75% — Normal"] B1(Monitor usage) - B2(Consider /compact\nfor old threads) + B2(Consider /compact
for old threads) B3(Normal operation) end subgraph ORANGE["🟠 75–85% — Caution"] - O1(Suggest /compact\nproactively) + O1(Suggest /compact
proactively) O2(Reduce verbosity) - O3(Defer non-critical\noperations) + O3(Defer non-critical
operations) end subgraph RED["🔴 85–100% — Critical"] - R1(Auto-compact\ntriggered at 80%) + R1(Auto-compact
triggered at 80%) R2(Essential ops only) - R3(Start new session\nfor new tasks) + R3(Start new session
for new tasks) end GREEN --> BLUE --> ORANGE --> RED @@ -80,16 +80,16 @@ Claude Code has 5 distinct memory types with different scopes and persistence. K ```mermaid flowchart TD - A["🌍 Global CLAUDE.md\n~/.claude/CLAUDE.md"] --> B["📁 Project CLAUDE.md\n/project-root/CLAUDE.md"] - B --> C["📂 Subdirectory CLAUDE.md\n/src/CLAUDE.md, /tests/CLAUDE.md"] - C --> D["💬 In-Conversation Context\nMessages + tool results this session"] - D --> E["⚡ Ephemeral State\nMCP server state, tool cache"] + A["🌍 Global CLAUDE.md
~/.claude/CLAUDE.md"] --> B["📁 Project CLAUDE.md
/project-root/CLAUDE.md"] + B --> C["📂 Subdirectory CLAUDE.md
/src/CLAUDE.md, /tests/CLAUDE.md"] + C --> D["💬 In-Conversation Context
Messages + tool results this session"] + D --> E["⚡ Ephemeral State
MCP server state, tool cache"] - A1["Scope: ALL projects\nPersists: Always\nUse: Global prefs, API keys"] --> A - B1["Scope: This project\nPersists: Always\nUse: Project conventions"] --> B - C1["Scope: This directory\nPersists: Always\nUse: Module-specific rules"] --> C - D1["Scope: This session\nPersists: Session only\nUse: Task context"] --> D - E1["Scope: This session\nPersists: Session only\nUse: Computed results"] --> E + A1["Scope: ALL projects
Persists: Always
Use: Global prefs, API keys"] --> A + B1["Scope: This project
Persists: Always
Use: Project conventions"] --> B + C1["Scope: This directory
Persists: Always
Use: Module-specific rules"] --> C + D1["Scope: This session
Persists: Session only
Use: Task context"] --> D + E1["Scope: This session
Persists: Session only
Use: Computed results"] --> E style A fill:#E87E2F,color:#fff style B fill:#6DB3F2,color:#fff @@ -148,7 +148,7 @@ sequenceDiagram CM->>NI: Injects: saved context NI->>U: Ready — context restored ✓ - Note over CC,NI: Conversation history NOT restored\nOnly CLAUDE.md content persists + Note over CC,NI: Conversation history NOT restored
Only CLAUDE.md content persists ```
@@ -181,9 +181,9 @@ flowchart TD B1([Start big session]) --> B2(Add task A) B2 --> B3(Add task B) B3 --> B4(Add task C) - B4 --> B5{Context bloated\n>75%} - B5 --> B6(Response quality\ndegrades) - B6 --> B7(Force-restart\nloses all context) + B4 --> B5{Context bloated
>75%} + B5 --> B6(Response quality
degrades) + B6 --> B7(Force-restart
loses all context) style B1 fill:#E85D5D,color:#fff style B5 fill:#E85D5D,color:#fff style B6 fill:#E85D5D,color:#fff @@ -192,7 +192,7 @@ flowchart TD subgraph GOOD["✅ Best Practice: Focused Sessions"] G1([Start focused session]) --> G2(Complete task A) - G2 --> G3{Natural\ncheckpoint?} + G2 --> G3{Natural
checkpoint?} G3 -->|Yes| G4(Save to CLAUDE.md) G4 --> G5([New session for task B]) G3 -->|No| G6{Context >75%?} diff --git a/guide/diagrams/03-configuration-system.md b/guide/diagrams/03-configuration-system.md index 2457d14..adc442f 100644 --- a/guide/diagrams/03-configuration-system.md +++ b/guide/diagrams/03-configuration-system.md @@ -16,13 +16,13 @@ Claude Code resolves settings through a strict priority hierarchy. Higher layers ```mermaid flowchart TD - A["1️⃣ CLI Flags\n--model, --dangerously-skip-permissions\n--max-turns, --system-prompt"] --> B["2️⃣ Environment Variables\nANTHROPIC_API_KEY\nCLAUDE_MODEL, CLAUDE_CONFIG"] - B --> C["3️⃣ Project Config\n.claude/settings.json\n.claude/settings.local.json"] - C --> D["4️⃣ Global Config\n~/.claude/settings.json\n~/.claude/CLAUDE.md"] - D --> E["5️⃣ Built-in Defaults\nHardcoded in Claude Code binary"] + A["1️⃣ CLI Flags
--model, --dangerously-skip-permissions
--max-turns, --system-prompt"] --> B["2️⃣ Environment Variables
ANTHROPIC_API_KEY
CLAUDE_MODEL, CLAUDE_CONFIG"] + B --> C["3️⃣ Project Config
.claude/settings.json
.claude/settings.local.json"] + C --> D["4️⃣ Global Config
~/.claude/settings.json
~/.claude/CLAUDE.md"] + D --> E["5️⃣ Built-in Defaults
Hardcoded in Claude Code binary"] - A1["Highest priority\nOverrides everything\nUse: automation, CI/CD"] --> A - E1["Lowest priority\nFallback values\nUse: baseline behavior"] --> E + A1["Highest priority
Overrides everything
Use: automation, CI/CD"] --> A + E1["Lowest priority
Fallback values
Use: baseline behavior"] --> E style A fill:#E87E2F,color:#fff style B fill:#6DB3F2,color:#fff @@ -59,27 +59,27 @@ Three extensibility mechanisms with different purposes and tradeoffs. Choosing t ```mermaid flowchart LR subgraph SKILLS["📦 Skills (.claude/skills/)"] - S1[Bundled capability\nwith resources] + S1[Bundled capability
with resources] S2[Invoked via /skillname] S3[Portable across projects] - S4["Use for: reusable\ncross-project capabilities"] + S4["Use for: reusable
cross-project capabilities"] end subgraph COMMANDS["⚡ Commands (.claude/commands/)"] - C1[Simple template\nor script] + C1[Simple template
or script] C2[Project slash command] C3[Project-specific only] - C4["Use for: project\nautomation, shortcuts"] + C4["Use for: project
automation, shortcuts"] end subgraph AGENTS["🤖 Agents (.claude/agents/)"] A1[Full autonomous agent] A2[Own tool set & CLAUDE.md] A3[Spawned via Task tool] - A4["Use for: complex\ndelegated tasks"] + A4["Use for: complex
delegated tasks"] end - Q{What are\nyou building?} --> |Reusable feature| SKILLS + Q{What are
you building?} --> |Reusable feature| SKILLS Q --> |Project shortcut| COMMANDS Q --> |Complex sub-task| AGENTS @@ -123,7 +123,7 @@ sequenceDiagram P->>T: Task(prompt, tools_allowed) T->>S: Spawn new Claude instance - Note over S: Gets: prompt + tool grants\nDoes NOT get: parent conversation + Note over S: Gets: prompt + tool grants
Does NOT get: parent conversation S->>FS: Read files (if granted) S->>FS: Edit files (if granted) @@ -136,7 +136,7 @@ sequenceDiagram T->>P: Result string P->>P: Continues with result - Note over P,T: Parent sees only final text\nNo side-effects leaked back + Note over P,T: Parent sees only final text
No side-effects leaked back ```
@@ -168,7 +168,7 @@ Hooks let you run custom code at key points in Claude Code's lifecycle — for s flowchart TD A([User sends message]) --> B{PreToolUse Hook} B -->|Exit 0: allow| C[Tool executes] - B -->|Exit 1: block| D([Tool blocked\nClause stops]) + B -->|Exit 1: block| D([Tool blocked
Clause stops]) C --> E{PostToolUse Hook} E --> F[Next tool or response] F --> G{More tool calls?} diff --git a/guide/diagrams/04-architecture-internals.md b/guide/diagrams/04-architecture-internals.md index 75d61df..d701fc3 100644 --- a/guide/diagrams/04-architecture-internals.md +++ b/guide/diagrams/04-architecture-internals.md @@ -16,16 +16,16 @@ Claude Code's core execution is a single loop: parse → build prompt → call A ```mermaid flowchart TD - A([User Input]) --> B(Build System Prompt\n+ context + tools) + A([User Input]) --> B(Build System Prompt
+ context + tools) B --> C{{Claude API Call}} - C --> D{Response\ncontains tool calls?} + C --> D{Response
contains tool calls?} D -->|Yes| E(Parse tool calls) - E --> F(Execute each tool\nGlob, Grep, Bash...) - F --> G(Append tool results\nto conversation) + E --> F(Execute each tool
Glob, Grep, Bash...) + F --> G(Append tool results
to conversation) G --> C D -->|No| H(Extract text response) H --> I([Display to User]) - I --> J{User sends\nnext message?} + I --> J{User sends
next message?} J -->|Yes| A J -->|No| K([Session ends]) @@ -75,31 +75,31 @@ flowchart TD ROOT --> WORKFLOW subgraph READ["📖 Read Tools"] - R1[Glob\nFind files by pattern] - R2[Grep\nSearch file content] - R3[Read\nRead file content] - R4[LS\nList directory] + R1[Glob
Find files by pattern] + R2[Grep
Search file content] + R3[Read
Read file content] + R4[LS
List directory] end subgraph WRITE["✏️ Write Tools"] - W1[Write\nCreate new file] - W2[Edit\nModify existing file] - W3[MultiEdit\nBatch modifications] + W1[Write
Create new file] + W2[Edit
Modify existing file] + W3[MultiEdit
Batch modifications] end subgraph EXECUTE["⚙️ Execute Tools"] - E1[Bash\nShell commands] - E2[Task\nSpawn sub-agent] + E1[Bash
Shell commands] + E2[Task
Spawn sub-agent] end subgraph WEB["🌐 Web Tools"] - WB1[WebSearch\nSearch the web] - WB2[WebFetch\nFetch URL content] + WB1[WebSearch
Search the web] + WB2[WebFetch
Fetch URL content] end subgraph WORKFLOW["📋 Workflow Tools"] - WF1[TodoWrite\nManage task list] - WF2[NotebookEdit\nJupyter notebooks] + WF1[TodoWrite
Manage task list] + WF2[NotebookEdit
Jupyter notebooks] end style ROOT fill:#E87E2F,color:#fff @@ -156,8 +156,8 @@ sequenceDiagram T->>CC: Tool schemas (Glob, Grep, Bash...) CC->>CC: 5. Add working directory + git info CC->>CC: 6. Add MCP server capabilities - CC->>A: System prompt (assembled)\n+ User message - Note over A: One large call with\nall context embedded + CC->>A: System prompt (assembled)
+ User message + Note over A: One large call with
all context embedded ```
@@ -196,17 +196,17 @@ sequenceDiagram P->>T: Task(prompt="do X", tools=[Read,Write,Bash]) Note over T: Creates new Claude instance T->>S: spawn(prompt + tool grants ONLY) - Note over S: Does NOT receive:\n- Parent conversation\n- Parent tool results\n- Parent state + Note over S: Does NOT receive:
- Parent conversation
- Parent tool results
- Parent state S->>EXT: read files, bash, web (as granted) EXT->>S: Results - Note over S: Independent reasoning\nwith limited context + Note over S: Independent reasoning
with limited context S->>T: return "task complete: details..." Note over T: Only text passes back T->>P: Result string - Note over P: Parent gets text only\nNo shared state + Note over P: Parent gets text only
No shared state ```
diff --git a/guide/diagrams/05-mcp-ecosystem.md b/guide/diagrams/05-mcp-ecosystem.md index eca8935..9b4002d 100644 --- a/guide/diagrams/05-mcp-ecosystem.md +++ b/guide/diagrams/05-mcp-ecosystem.md @@ -16,33 +16,33 @@ The MCP ecosystem has 4 categories of servers — official, community-dev, commu ```mermaid flowchart TD - CC["Claude Code\n(MCP Client)"] --> OFF + CC["Claude Code
(MCP Client)"] --> OFF CC --> DEV CC --> OPS CC --> LOCAL subgraph OFF["🏢 Official Servers"] - O1["context7\nLibrary documentation"] - O2["sequential-thinking\nMulti-step reasoning"] - O3["playwright\nBrowser automation"] + O1["context7
Library documentation"] + O2["sequential-thinking
Multi-step reasoning"] + O3["playwright
Browser automation"] end subgraph DEV["👨‍💻 Community: Dev Tools"] - D1["semgrep\nSecurity scanning"] - D2["github\nPR management"] - D3["grepai\nSemantic code search"] - D4["filesystem-enhanced\nAdvanced file ops"] + D1["semgrep
Security scanning"] + D2["github
PR management"] + D3["grepai
Semantic code search"] + D4["filesystem-enhanced
Advanced file ops"] end subgraph OPS["⚙️ Community: Ops/Infra"] - OP1["kubernetes\nCluster management"] - OP2["docker\nContainer ops"] - OP3["aws\nCloud resources"] + OP1["kubernetes
Cluster management"] + OP2["docker
Container ops"] + OP3["aws
Cloud resources"] end subgraph LOCAL["🔧 Local/Custom"] - L1["Project-specific\nMCP servers"] - L2["Internal APIs\nWrapped as MCP"] + L1["Project-specific
MCP servers"] + L2["Internal APIs
Wrapped as MCP"] end style CC fill:#E87E2F,color:#fff @@ -84,22 +84,22 @@ MCP is a JSON-RPC protocol running over stdio or SSE. Claude Code acts as the cl ```mermaid flowchart LR subgraph CLAUDE["Claude Code (MCP Client)"] - CC1["Parse tool call\nfrom Claude response"] + CC1["Parse tool call
from Claude response"] CC2["Match to MCP server"] - CC3["Use tool result\nin next API call"] + CC3["Use tool result
in next API call"] end subgraph PROTO["MCP Protocol"] - P1["JSON-RPC Request\n{tool, params}"] - P2["Transport:\nstdio or SSE"] - P3["JSON-RPC Response\n{result or error}"] + P1["JSON-RPC Request
{tool, params}"] + P2["Transport:
stdio or SSE"] + P3["JSON-RPC Response
{result or error}"] end subgraph SERVER["MCP Server"] S1["Receive tool call"] - S2["Execute action\n(API, file, CLI...)"] - S3["Return structured\nresult"] - EXT{{"External Service\nAPI / DB / CLI"}} + S2["Execute action
(API, file, CLI...)"] + S3["Return structured
result"] + EXT{{"External Service
API / DB / CLI"}} end CC1 --> P1 --> P2 --> S1 --> S2 --> EXT @@ -188,14 +188,14 @@ MCP server configurations can live in 4 different locations. The resolution orde ```mermaid flowchart TD - A["1️⃣ CLI: --mcp-config path/to/mcp.json\nHighest priority — overrides all"] --> B["2️⃣ Project: .claude/mcp.json\nTeam-shared, checked into git"] - B --> C["3️⃣ Project Root: .mcp.json\nAlternative project location"] - C --> D["4️⃣ Global: ~/.claude/mcp.json\nPersonal servers, all projects"] - D --> E["5️⃣ No MCP servers\nDefault (no config found)"] + A["1️⃣ CLI: --mcp-config path/to/mcp.json
Highest priority — overrides all"] --> B["2️⃣ Project: .claude/mcp.json
Team-shared, checked into git"] + B --> C["3️⃣ Project Root: .mcp.json
Alternative project location"] + C --> D["4️⃣ Global: ~/.claude/mcp.json
Personal servers, all projects"] + D --> E["5️⃣ No MCP servers
Default (no config found)"] - A1["Use for:\nCI/CD overrides\ntemporary testing"] --> A - B1["Use for:\nTeam-shared servers\n(playwright, github)"] --> B - D1["Use for:\nPersonal tools\n(context7, grepai)"] --> D + A1["Use for:
CI/CD overrides
temporary testing"] --> A + B1["Use for:
Team-shared servers
(playwright, github)"] --> B + D1["Use for:
Personal tools
(context7, grepai)"] --> D style A fill:#E87E2F,color:#fff style B fill:#6DB3F2,color:#fff diff --git a/guide/diagrams/06-development-workflows.md b/guide/diagrams/06-development-workflows.md index a8e9df6..06f42cf 100644 --- a/guide/diagrams/06-development-workflows.md +++ b/guide/diagrams/06-development-workflows.md @@ -16,21 +16,21 @@ Test-Driven Development adapted for Claude Code: write the failing test first, t ```mermaid flowchart TD - A([Start: New feature needed]) --> B(Write failing test\nwith human) + A([Start: New feature needed]) --> B(Write failing test
with human) B --> C(Run tests) - C --> D{Tests fail\nas expected?} - D -->|No: tests pass\nbefore impl!| E(Fix test — it's too weak) + C --> D{Tests fail
as expected?} + D -->|No: tests pass
before impl!| E(Fix test — it's too weak) E --> B - D -->|Yes: RED ✓| F(Ask Claude to implement\nminimal code to pass) + D -->|Yes: RED ✓| F(Ask Claude to implement
minimal code to pass) F --> G(Run tests again) G --> H{Tests pass?} - H -->|No| I(Diagnose with Claude\nfix implementation) + H -->|No| I(Diagnose with Claude
fix implementation) I --> G - H -->|Yes: GREEN ✓| J{Code needs\nrefactoring?} + H -->|Yes: GREEN ✓| J{Code needs
refactoring?} J -->|Yes| K(Refactor with Claude) K --> L(Run tests: still green?) L -->|No| I - L -->|Yes: REFACTOR ✓| M{More features\nneeded?} + L -->|Yes: REFACTOR ✓| M{More features
needed?} J -->|No| M M -->|Yes| B M -->|No| N([Feature complete ✓]) @@ -78,20 +78,20 @@ Write the specification before the code. Claude uses the spec as the single sour ```mermaid flowchart LR - A([Idea / Requirement]) --> B(Write spec.md\nin natural language) - B --> C(Claude reviews spec\nfor clarity + completeness) - C --> D{Spec approved\n by human?} - D -->|No: gaps found| E(Refine spec\naddress gaps) + A([Idea / Requirement]) --> B(Write spec.md
in natural language) + B --> C(Claude reviews spec
for clarity + completeness) + C --> D{Spec approved
by human?} + D -->|No: gaps found| E(Refine spec
address gaps) E --> C - D -->|Yes| F(Generate tests\nfrom spec) - F --> G(Generate implementation\nfrom spec + tests) + D -->|Yes| F(Generate tests
from spec) + F --> G(Generate implementation
from spec + tests) G --> H(Run test suite) - H --> I{All tests\npass?} - I -->|No| J(Claude fixes\nimplementation) + H --> I{All tests
pass?} + I -->|No| J(Claude fixes
implementation) J --> H - I -->|Yes| K(Human review\nspec vs output) - K --> L{Matches\nspec?} - L -->|No| M(Update spec\nor implementation) + I -->|Yes| K(Human review
spec vs output) + K --> L{Matches
spec?} + L -->|No| M(Update spec
or implementation) M --> K L -->|Yes| N([Merge ✓]) @@ -134,21 +134,21 @@ Complex tasks benefit from plan mode: Claude explores the codebase, proposes a p ```mermaid flowchart TD - A([Complex task given]) --> B(Enter Plan Mode\nShift+Tab × 2) - B --> C(Claude explores\ncodebase structure) - C --> D(Claude proposes plan\nwith file list) + A([Complex task given]) --> B(Enter Plan Mode
Shift+Tab × 2) + B --> C(Claude explores
codebase structure) + C --> D(Claude proposes plan
with file list) D --> E(Human reviews plan) - E --> F{Plan\nacceptable?} - F -->|No: issues found| G(Human annotates plan\nmarks corrections) + E --> F{Plan
acceptable?} + F -->|No: issues found| G(Human annotates plan
marks corrections) G --> H(Claude revises plan) H --> E - F -->|Yes| I(Approve plan\nExit Plan Mode) - I --> J(Claude executes\nstep by step) - J --> K(Claude reports\nprogress) - K --> L{Unexpected\nissue?} - L -->|Yes| M(Claude flags issue\nasks for guidance) + F -->|Yes| I(Approve plan
Exit Plan Mode) + I --> J(Claude executes
step by step) + J --> K(Claude reports
progress) + K --> L{Unexpected
issue?} + L -->|Yes| M(Claude flags issue
asks for guidance) M --> F - L -->|No| N{All steps\ncomplete?} + L -->|No| N{All steps
complete?} N -->|No| J N -->|Yes| O([Task done ✓]) @@ -200,9 +200,9 @@ Output rarely hits the mark on the first try. This loop gives you a systematic w flowchart TD A([Initial prompt]) --> B(Claude generates output) B --> C(Evaluate output quality) - C --> D{Good\nenough?} + C --> D{Good
enough?} D -->|Yes| E([Done ✓]) - D -->|No| F(Identify specific issue\nWhat exactly is wrong?) + D -->|No| F(Identify specific issue
What exactly is wrong?) F --> G{Issue type?} G -->|Style/tone| H(Add: style constraints) G -->|Missing info| I(Add: provide missing context) @@ -214,9 +214,9 @@ flowchart TD K --> L L --> M(Claude refines output) M --> N(Compare before/after) - N --> O{Improvement\ndetected?} + N --> O{Improvement
detected?} O -->|Yes| C - O -->|No| P(Different\napproach needed) + O -->|No| P(Different
approach needed) P --> F style A fill:#F5E6D3,color:#333 diff --git a/guide/diagrams/07-multi-agent-patterns.md b/guide/diagrams/07-multi-agent-patterns.md index 8baca0b..1212cbd 100644 --- a/guide/diagrams/07-multi-agent-patterns.md +++ b/guide/diagrams/07-multi-agent-patterns.md @@ -17,20 +17,20 @@ Three proven topologies for multi-agent coordination. Choose based on task indep ```mermaid flowchart TD subgraph ORCH["Pattern 1: Orchestrator + Workers"] - OL[Lead Orchestrator] --> OW1[Worker 1\nFrontend] - OL --> OW2[Worker 2\nBackend] - OL --> OW3[Worker 3\nTests] + OL[Lead Orchestrator] --> OW1[Worker 1
Frontend] + OL --> OW2[Worker 2
Backend] + OL --> OW3[Worker 3
Tests] OW1 & OW2 & OW3 --> OR([Results aggregated]) end subgraph PIPE["Pattern 2: Pipeline"] - PA[Agent A\nRequirements] --> PB[Agent B\nImplementation] - PB --> PC[Agent C\nReview] + PA[Agent A
Requirements] --> PB[Agent B
Implementation] + PB --> PC[Agent C
Review] PC --> PD([Final output]) end subgraph ROUTE["Pattern 3: Specialist Router"] - RR{Router Agent\nanalyzes task} --> RC[Code Agent] + RR{Router Agent
analyzes task} --> RC[Code Agent] RR --> RT[Test Agent] RR --> RD[Docs Agent] RC & RT & RD --> RO([Specialized result]) @@ -79,19 +79,19 @@ Git worktrees enable true parallel development: each Claude instance works in an ```mermaid flowchart LR - MB[(Main Branch\ngit repository)] --> WA[git worktree add\nfeature-A] - MB --> WB[git worktree add\nfeature-B] - MB --> WC[git worktree add\nbugfix-C] + MB[(Main Branch
git repository)] --> WA[git worktree add
feature-A] + MB --> WB[git worktree add
feature-B] + MB --> WC[git worktree add
bugfix-C] - WA --> CA[Claude Instance 1\n/worktrees/feature-A] - WB --> CB[Claude Instance 2\n/worktrees/feature-B] - WC --> CC[Claude Instance 3\n/worktrees/bugfix-C] + WA --> CA[Claude Instance 1
/worktrees/feature-A] + WB --> CB[Claude Instance 2
/worktrees/feature-B] + WC --> CC[Claude Instance 3
/worktrees/bugfix-C] CA --> CA1([Commits to feature-A]) CB --> CB1([Commits to feature-B]) CC --> CC1([Commits to bugfix-C]) - CA1 & CB1 & CC1 --> MERGE([Merge to main\nwhen ready]) + CA1 & CB1 & CC1 --> MERGE([Merge to main
when ready]) style MB fill:#E87E2F,color:#fff style CA fill:#6DB3F2,color:#fff @@ -132,22 +132,22 @@ Separating planning from execution using two Claude instances prevents costly mi ```mermaid sequenceDiagram participant U as User - participant PL as Planner Claude\n(no tools) - participant EX as Executor Claude\n(full tools) + participant PL as Planner Claude
(no tools) + participant EX as Executor Claude
(full tools) U->>PL: "Plan how to refactor auth module" - Note over PL: Reads docs, analyzes requirements\nNo execution risk — no tools + Note over PL: Reads docs, analyzes requirements
No execution risk — no tools - PL->>U: Detailed plan:\n1. Files to change\n2. Order of operations\n3. Risk points\n4. Rollback strategy + PL->>U: Detailed plan:
1. Files to change
2. Order of operations
3. Risk points
4. Rollback strategy U->>U: Review plan carefully - Note over U: Human checkpoint:\napprove or adjust + Note over U: Human checkpoint:
approve or adjust U->>EX: "Execute this plan: [plan text]" EX->>EX: Implements step by step EX->>U: Progress updates + results - Note over PL,EX: Key insight: planner can be\nmore thorough without execution anxiety + Note over PL,EX: Key insight: planner can be
more thorough without execution anxiety ```
@@ -181,20 +181,20 @@ When tasks can be parallelized, spawn N Claude instances simultaneously instead ```mermaid flowchart LR - BT([Large Task:\nRefactor 50 files]) --> DEC{Decompose\ninto N subtasks} + BT([Large Task:
Refactor 50 files]) --> DEC{Decompose
into N subtasks} - DEC --> T1["Subtask 1\nFiles 1-10"] - DEC --> T2["Subtask 2\nFiles 11-20"] - DEC --> T3["Subtask 3\nFiles 21-30"] - DEC --> TN["Subtask N\n..."] + DEC --> T1["Subtask 1
Files 1-10"] + DEC --> T2["Subtask 2
Files 11-20"] + DEC --> T3["Subtask 3
Files 21-30"] + DEC --> TN["Subtask N
..."] - T1 --> CI1[Claude\nInstance 1] - T2 --> CI2[Claude\nInstance 2] - T3 --> CI3[Claude\nInstance 3] - TN --> CIN[Claude\nInstance N] + T1 --> CI1[Claude
Instance 1] + T2 --> CI2[Claude
Instance 2] + T3 --> CI3[Claude
Instance 3] + TN --> CIN[Claude
Instance N] - CI1 & CI2 & CI3 & CIN --> AGG(Aggregate\nresults) - AGG --> REV([Integration review\n~10x faster than sequential]) + CI1 & CI2 & CI3 & CIN --> AGG(Aggregate
results) + AGG --> REV([Integration review
~10x faster than sequential]) style BT fill:#F5E6D3,color:#333 style DEC fill:#E87E2F,color:#fff @@ -236,20 +236,20 @@ Not every task needs multiple instances. This decision tree guides you to the ri ```mermaid flowchart TD - A([Task to complete]) --> B{Need multiple\nClaude instances?} - B -->|No| C([Single session\nStandard usage]) - B -->|Yes| D{How many\ninstances?} + A([Task to complete]) --> B{Need multiple
Claude instances?} + B -->|No| C([Single session
Standard usage]) + B -->|Yes| D{How many
instances?} - D -->|2-3| E{Need branch\nisolation?} - E -->|Yes| F([Git worktrees\nSeparate branches]) - E -->|No| G([Multiple terminals\nSame repo]) + D -->|2-3| E{Need branch
isolation?} + E -->|Yes| F([Git worktrees
Separate branches]) + E -->|No| G([Multiple terminals
Same repo]) D -->|4+| H{Task structure?} - H -->|Independent tasks| I([Task tool\nSub-agents in parallel]) - H -->|Sequential pipeline| J([Agent pipeline\nA → B → C]) - H -->|Mixed expertise| K([Specialist router\nRoute by task type]) + H -->|Independent tasks| I([Task tool
Sub-agents in parallel]) + H -->|Sequential pipeline| J([Agent pipeline
A → B → C]) + H -->|Mixed expertise| K([Specialist router
Route by task type]) - B2{Need planning\nseparation?} --> L([Dual-instance\nPlanner + Executor]) + B2{Need planning
separation?} --> L([Dual-instance
Planner + Executor]) style A fill:#F5E6D3,color:#333 style B fill:#E87E2F,color:#fff diff --git a/guide/diagrams/08-security-and-production.md b/guide/diagrams/08-security-and-production.md index 01aacb7..1446ea5 100644 --- a/guide/diagrams/08-security-and-production.md +++ b/guide/diagrams/08-security-and-production.md @@ -19,22 +19,22 @@ flowchart LR THREAT([Threat / Attack]) --> L1 subgraph L1["🛡️ Layer 1: Prevention"] - P1[MCP server vetting\nread source before install] - P2[CLAUDE.md restrictions\ndefine forbidden actions] - P3[.claudeignore\nhide sensitive files] - P4[Minimal permissions\nbypassPermissions only in CI] + P1[MCP server vetting
read source before install] + P2[CLAUDE.md restrictions
define forbidden actions] + P3[.claudeignore
hide sensitive files] + P4[Minimal permissions
bypassPermissions only in CI] end subgraph L2["🔍 Layer 2: Detection"] - D1[PreToolUse hooks\nlog all tool calls] - D2[Audit logs\ncomplete history] - D3[Anomaly alerts\nunexpected file access] + D1[PreToolUse hooks
log all tool calls] + D2[Audit logs
complete history] + D3[Anomaly alerts
unexpected file access] end subgraph L3["🔒 Layer 3: Response"] - R1[Sandbox isolation\nDocker / Firecracker] - R2[Permission gates\nhuman approval on risk] - R3[Rollback capability\ngit revert, backups] + R1[Sandbox isolation
Docker / Firecracker] + R2[Permission gates
human approval on risk] + R3[Rollback capability
git revert, backups] end L1 -->|Bypassed| L2 @@ -85,23 +85,23 @@ Sandboxing adds overhead. Use this tree to decide when it's mandatory, recommend ```mermaid flowchart TD - A([Using Claude Code]) --> B{Running on\nproduction server?} - B -->|Yes| C([ALWAYS sandbox\nDocker / Firecracker]) - B -->|No| D{Executing untrusted\ncode or unknown MCP?} + A([Using Claude Code]) --> B{Running on
production server?} + B -->|Yes| C([ALWAYS sandbox
Docker / Firecracker]) + B -->|No| D{Executing untrusted
code or unknown MCP?} D -->|Yes| E{What platform?} - E -->|macOS| F([macOS Sandbox\nbuilt-in, free]) - E -->|Linux| G([Docker sandbox\nrecommended]) - E -->|CI/CD| H([Ephemeral container\nbest practice]) + E -->|macOS| F([macOS Sandbox
built-in, free]) + E -->|Linux| G([Docker sandbox
recommended]) + E -->|CI/CD| H([Ephemeral container
best practice]) - D -->|No| I{Personal project\nknown codebase?} - I -->|Yes| J{Comfortable with\ndefault permissions?} - J -->|Yes| K([Default mode\nsandbox optional]) - J -->|No| L([acceptEdits mode\nmanual file review]) + D -->|No| I{Personal project
known codebase?} + I -->|Yes| J{Comfortable with
default permissions?} + J -->|Yes| K([Default mode
sandbox optional]) + J -->|No| L([acceptEdits mode
manual file review]) - I -->|No / Unsure| M([Sandbox recommended\nerr on side of caution]) + I -->|No / Unsure| M([Sandbox recommended
err on side of caution]) - NOTE["Rule of thumb:\nIf in doubt → sandbox it\nCost: low. Risk without it: high."] --> A + NOTE["Rule of thumb:
If in doubt → sandbox it
Cost: low. Risk without it: high."] --> A style C fill:#E85D5D,color:#fff style F fill:#7BC47F,color:#333 @@ -146,10 +146,10 @@ Asking Claude to verify its own work is circular. The same model that produced t ```mermaid flowchart TD subgraph BAD["❌ Anti-Pattern: Circular Verification"] - BA([Claude writes code]) --> BB(Ask Claude:\n'Is this correct?') - BB --> BC{Claude says:\n'Yes, looks good!'} + BA([Claude writes code]) --> BB(Ask Claude:
'Is this correct?') + BB --> BC{Claude says:
'Yes, looks good!'} BC -->|Deploy| BD([Bug in production]) - BC --> BE["Why it fails:\nSame model\nSame training biases\nSame blind spots"] + BC --> BE["Why it fails:
Same model
Same training biases
Same blind spots"] style BA fill:#E85D5D,color:#fff style BD fill:#E85D5D,color:#fff style BE fill:#E85D5D,color:#fff @@ -157,10 +157,10 @@ flowchart TD end subgraph GOOD["✅ Best Practice: Independent Verification"] - GA([Claude writes code]) --> GB(Human reviews\ncritical sections) - GA --> GC(Automated test suite\nruns independently) - GA --> GD(Different tool validates\nSemgrep, ESLint, etc.) - GB & GC & GD --> GE{All checks\npass?} + GA([Claude writes code]) --> GB(Human reviews
critical sections) + GA --> GC(Automated test suite
runs independently) + GA --> GD(Different tool validates
Semgrep, ESLint, etc.) + GB & GC & GD --> GE{All checks
pass?} GE -->|Yes| GF([Safe to deploy]) GE -->|No| GG([Fix before deploy]) style GA fill:#7BC47F,color:#333 @@ -198,21 +198,21 @@ Claude Code can run in non-interactive mode inside CI/CD pipelines for automated ```mermaid flowchart LR - PR([PR Created]) --> GH{GitHub Actions\ntrigger} - GH --> ENV[Set up environment\nANTHROPIC_API_KEY secret] - ENV --> CC[claude --print --headless\n'Run quality checks'] + PR([PR Created]) --> GH{GitHub Actions
trigger} + GH --> ENV[Set up environment
ANTHROPIC_API_KEY secret] + ENV --> CC[claude --print --headless
'Run quality checks'] CC --> subgraph TASKS["Parallel Checks"] - T1[Lint check\nESLint / Prettier] - T2[Test suite\nVitest / Jest] - T3[Security scan\nSemgrep MCP] - T4[Doc completeness\ncheck exports] + T1[Lint check
ESLint / Prettier] + T2[Test suite
Vitest / Jest] + T3[Security scan
Semgrep MCP] + T4[Doc completeness
check exports] end - T1 & T2 & T3 & T4 --> AGG{All\nchecks pass?} - AGG -->|Yes| OK([✓ Checks green\nhuman review next]) - AGG -->|No| FAIL([✗ Report failures\non PR]) - FAIL --> FIX([Developer fixes\nre-trigger CI]) + T1 & T2 & T3 & T4 --> AGG{All
checks pass?} + AGG -->|Yes| OK([✓ Checks green
human review next]) + AGG -->|No| FAIL([✗ Report failures
on PR]) + FAIL --> FIX([Developer fixes
re-trigger CI]) FIX --> CC style PR fill:#F5E6D3,color:#333 diff --git a/guide/diagrams/09-cost-and-optimization.md b/guide/diagrams/09-cost-and-optimization.md index 3e0ecd7..6258187 100644 --- a/guide/diagrams/09-cost-and-optimization.md +++ b/guide/diagrams/09-cost-and-optimization.md @@ -18,17 +18,17 @@ Not all tasks need the most powerful model. Using the right model for the right flowchart TD A([Task to complete]) --> B{Task complexity?} - B -->|Simple| C["Simple tasks:\ntypo fixes, renames,\nformatting, translations"] - C --> D([Haiku 4.5\n💰 Cheapest, fastest\n~$0.80/MTok input]) + B -->|Simple| C["Simple tasks:
typo fixes, renames,
formatting, translations"] + C --> D([Haiku 4.5
💰 Cheapest, fastest
~$0.80/MTok input]) - B -->|Standard| E["Standard tasks:\nfeature implementation,\nbug fixes, refactoring"] - E --> F([Sonnet 4.5/4.6\n💰💰 Balanced\n~$3/MTok input]) + B -->|Standard| E["Standard tasks:
feature implementation,
bug fixes, refactoring"] + E --> F([Sonnet 4.5/4.6
💰💰 Balanced
~$3/MTok input]) - B -->|Complex| G{Needs deep\nreasoning?} - G -->|Yes| H["Complex tasks:\narchitecture decisions,\nsecurity review,\nmulti-file analysis"] - H --> I([Opus 4.6 / Sonnet + --think-hard\n💰💰💰 Most capable\n~$15/MTok input]) + B -->|Complex| G{Needs deep
reasoning?} + G -->|Yes| H["Complex tasks:
architecture decisions,
security review,
multi-file analysis"] + H --> I([Opus 4.6 / Sonnet + --think-hard
💰💰💰 Most capable
~$15/MTok input]) - G -->|No: just large| J["Large but clear tasks:\nbig refactors,\ndoc generation"] + G -->|No: just large| J["Large but clear tasks:
big refactors,
doc generation"] J --> F style A fill:#F5E6D3,color:#333 @@ -67,27 +67,27 @@ High token costs are usually fixable. This systematic tree identifies the root c ```mermaid flowchart TD - A([High token costs?]) --> B{Context\ntoo large?} - B -->|Yes| C(Use /compact\nor start fresh session) - C --> Z([Saves 40-60%\nper session]) + A([High token costs?]) --> B{Context
too large?} + B -->|Yes| C(Use /compact
or start fresh session) + C --> Z([Saves 40-60%
per session]) - B -->|No| D{Verbose\nresponses?} - D -->|Yes| E(Add CLAUDE.md instruction:\n'Be concise, avoid explanations') + B -->|No| D{Verbose
responses?} + D -->|Yes| E(Add CLAUDE.md instruction:
'Be concise, avoid explanations') E --> Z2([Saves 20-30%]) - D -->|No| F{Re-explaining\ncontext repeatedly?} - F -->|Yes| G(Move repeated context\nto CLAUDE.md) + D -->|No| F{Re-explaining
context repeatedly?} + F -->|Yes| G(Move repeated context
to CLAUDE.md) G --> Z3([Saves 15-25%]) - F -->|No| H{Using wrong\nmodel for task?} - H -->|Yes| I(Use Haiku for simple tasks\nSee model selection tree) - I --> Z4([Saves 50-90%\non simple tasks]) + F -->|No| H{Using wrong
model for task?} + H -->|Yes| I(Use Haiku for simple tasks
See model selection tree) + I --> Z4([Saves 50-90%
on simple tasks]) - H -->|No| J{MCP server\nnoisy output?} - J -->|Yes| K(Review MCP verbosity\nFilter tool output) + H -->|No| J{MCP server
noisy output?} + J -->|Yes| K(Review MCP verbosity
Filter tool output) K --> Z5([Saves 10-20%]) - J -->|No| L([Baseline cost\nacceptable]) + J -->|No| L([Baseline cost
acceptable]) style A fill:#F5E6D3,color:#333 style B fill:#E87E2F,color:#fff @@ -137,9 +137,9 @@ flowchart LR subgraph PRO["Pro ($20/mo)"] P1[Claude Code CLI ✓] - P2[Limited usage\n~1x baseline] + P2[Limited usage
~1x baseline] P3[Personal projects] - P4[❌ No parallel sessions\nout of the box] + P4[❌ No parallel sessions
out of the box] end subgraph MAX["Max ($100-200/mo)"] @@ -196,39 +196,39 @@ Multiple strategies stack for cumulative token savings. Apply them in order from ```mermaid flowchart LR - BASE([Baseline:\n100% tokens]) --> RTK + BASE([Baseline:
100% tokens]) --> RTK subgraph RTK["Strategy 1: RTK Proxy"] - R1[Raw CLI output\n→ filtered output] - R2["git status, cargo test,\npnpm list → compressed"] - R3[Saves 60-90%\non CLI commands] + R1[Raw CLI output
→ filtered output] + R2["git status, cargo test,
pnpm list → compressed"] + R3[Saves 60-90%
on CLI commands] end RTK --> COMP subgraph COMP["Strategy 2: /compact"] - C1[Long conversation\n→ summarized] - C2[Keep decisions,\ndrop verbose reasoning] - C3[Saves 40-60%\nat checkpoint] + C1[Long conversation
→ summarized] + C2[Keep decisions,
drop verbose reasoning] + C3[Saves 40-60%
at checkpoint] end COMP --> CLAUDE_MD subgraph CLAUDE_MD["Strategy 3: CLAUDE.md"] - CM1[Repeated context\n→ persistent instructions] - CM2[No re-explaining\nproject conventions] - CM3[Saves 15-25%\nper session] + CM1[Repeated context
→ persistent instructions] + CM2[No re-explaining
project conventions] + CM3[Saves 15-25%
per session] end CLAUDE_MD --> MODEL subgraph MODEL["Strategy 4: Model Selection"] - MO1[Haiku for simple tasks\ninstead of Sonnet] - MO2[Same quality output\nat fraction of cost] - MO3[Saves 50-90%\non simple tasks] + MO1[Haiku for simple tasks
instead of Sonnet] + MO2[Same quality output
at fraction of cost] + MO3[Saves 50-90%
on simple tasks] end - MODEL --> RESULT([Optimized:\n10-20% of baseline\nfor typical usage]) + MODEL --> RESULT([Optimized:
10-20% of baseline
for typical usage]) style BASE fill:#E85D5D,color:#fff style R3 fill:#7BC47F,color:#333 diff --git a/guide/diagrams/10-adoption-and-learning.md b/guide/diagrams/10-adoption-and-learning.md index 969bf48..d175f71 100644 --- a/guide/diagrams/10-adoption-and-learning.md +++ b/guide/diagrams/10-adoption-and-learning.md @@ -18,23 +18,23 @@ Different backgrounds require different onboarding approaches. Forcing developer flowchart TD A([Start: New to Claude Code]) --> B{Your background?} - B -->|Developer| C["🧑‍💻 Developer Path\n~2 days to productivity"] + B -->|Developer| C["🧑‍💻 Developer Path
~2 days to productivity"] C --> C1(Quick Start: first session) C1 --> C2(Workflows: TDD, spec-first, plan-driven) C2 --> C3(Advanced: agents, hooks, MCP servers) C3 --> C4([Productive developer ✓]) - B -->|Non-technical| D["👤 Non-Tech Path\n~1 week to basic usage"] - D --> D1(What is Claude Code?\nKey concepts only) - D1 --> D2(Basic usage: editing,\nexplaining, simple tasks) - D2 --> D3(Limited scope: no\nproduction deployments) + B -->|Non-technical| D["👤 Non-Tech Path
~1 week to basic usage"] + D --> D1(What is Claude Code?
Key concepts only) + D1 --> D2(Basic usage: editing,
explaining, simple tasks) + D2 --> D3(Limited scope: no
production deployments) D3 --> D4([Safe basic user ✓]) - B -->|Team lead| E["👔 Team Lead Path\n~2 weeks to team adoption"] - E --> E1(ROI assessment\nvalue vs cost analysis) - E1 --> E2(CLAUDE.md strategy\nteam conventions) - E2 --> E3(Pilot with 2-3 devs\ncollect feedback) - E3 --> E4(Gradual rollout\nwith guardrails) + B -->|Team lead| E["👔 Team Lead Path
~2 weeks to team adoption"] + E --> E1(ROI assessment
value vs cost analysis) + E1 --> E2(CLAUDE.md strategy
team conventions) + E2 --> E3(Pilot with 2-3 devs
collect feedback) + E3 --> E4(Gradual rollout
with guardrails) E4 --> E5([Team adoption ✓]) style A fill:#F5E6D3,color:#333 @@ -74,18 +74,18 @@ The UVAL protocol prevents the "copy-paste trap" — where you use Claude Code w ```mermaid flowchart LR - U([U — Use It\nTry the feature\nyourself first]) --> V + U([U — Use It
Try the feature
yourself first]) --> V - V([V — Verify\nUnderstand what\nClaude did and why]) --> A + V([V — Verify
Understand what
Claude did and why]) --> A - A([A — Adapt\nModify the approach,\nexperiment with variants]) --> L + A([A — Adapt
Modify the approach,
experiment with variants]) --> L - L([L — Learn\nNote the pattern\nfor future use]) --> NEXT + L([L — Learn
Note the pattern
for future use]) --> NEXT - NEXT{More tasks\nusing this pattern?} -->|Yes| U + NEXT{More tasks
using this pattern?} -->|Yes| U NEXT -->|No| DONE([Pattern internalized ✓]) - TRAP["❌ Copy-Paste Trap:\nAccept output →\nDeploy → Bug →\n'Claude broke it'"] -.->|avoid| V + TRAP["❌ Copy-Paste Trap:
Accept output →
Deploy → Bug →
'Claude broke it'"] -.->|avoid| V style U fill:#6DB3F2,color:#fff style V fill:#E87E2F,color:#fff @@ -122,25 +122,25 @@ Knowing when to trust Claude's output and when to verify is the most important s ```mermaid flowchart TD - A([Claude produces output]) --> B{Can I test\nthis output?} + A([Claude produces output]) --> B{Can I test
this output?} - B -->|Yes| C{Do the tests\nactually pass?} + B -->|Yes| C{Do the tests
actually pass?} C -->|Yes| D([Trust with test coverage ✓]) C -->|No| E([Fix before using]) - B -->|No| F{Do I understand\nwhat it did?} - F -->|No| G(Ask Claude to explain\nstep by step) + B -->|No| F{Do I understand
what it did?} + F -->|No| G(Ask Claude to explain
step by step) G --> F - F -->|Yes| H{Is this\nreversible?} + F -->|Yes| H{Is this
reversible?} H -->|Yes, easily| I([Trust with git safety net ✓]) - H -->|No: hard to undo| J(Extra review required\ncheck before applying) - J --> K{Is it\nsecurity-critical?} + H -->|No: hard to undo| J(Extra review required
check before applying) + J --> K{Is it
security-critical?} - K -->|Yes: auth, crypto, perms| L([Human expert review\nnever trust blindly]) - K -->|No| M{Familiar\ndomain?} + K -->|Yes: auth, crypto, perms| L([Human expert review
never trust blindly]) + K -->|No| M{Familiar
domain?} M -->|Yes| I - M -->|No| N([Pair with domain expert\nor verify by testing]) + M -->|No| N([Pair with domain expert
or verify by testing]) style A fill:#F5E6D3,color:#333 style B fill:#E87E2F,color:#fff