From a4a6c49cb5b94734730253ade1a14f9b62513c09 Mon Sep 17 00:00:00 2001 From: Florian BRUNIAUX Date: Thu, 12 Mar 2026 16:47:36 +0100 Subject: [PATCH] =?UTF-8?q?docs(diagrams):=20audit,=20fix=20and=20expand?= =?UTF-8?q?=20Mermaid=20diagram=20suite=20(7=20files=20=E2=86=92=209)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 1-2 — fixes on existing diagrams: - 01-foundations: add Plan Mode + dontAsk subgraphs (3→5 permission modes) - 04-architecture-internals: add Control Flow Tools category (5→6 tool categories) - 05-mcp-ecosystem: clarify local+user scopes both live in ~/.claude.json - 07-multi-agent-patterns: fix disconnected B2 node (now proper third branch) - 09-cost-and-optimization: replace hardcoded prices with relative ratios + disclaimer Phase 3 — new diagram files: - 11-context-engineering.md: 4 diagrams (3-layer system, budget/adherence, monolithic vs modular, rule placement decision tree) - 12-enterprise-governance.md: 3 diagrams (governance risk tiers, MCP approval workflow, data classification) README.md updated: 41→48 diagrams, navigation table extended, 2 new use-case sections Co-Authored-By: Claude Sonnet 4.6 --- guide/diagrams/01-foundations.md | 38 ++- guide/diagrams/04-architecture-internals.md | 19 +- guide/diagrams/05-mcp-ecosystem.md | 7 +- guide/diagrams/07-multi-agent-patterns.md | 22 +- guide/diagrams/09-cost-and-optimization.md | 16 +- guide/diagrams/11-context-engineering.md | 285 ++++++++++++++++++++ guide/diagrams/12-enterprise-governance.md | 208 ++++++++++++++ guide/diagrams/README.md | 19 +- 8 files changed, 589 insertions(+), 25 deletions(-) create mode 100644 guide/diagrams/11-context-engineering.md create mode 100644 guide/diagrams/12-enterprise-governance.md diff --git a/guide/diagrams/01-foundations.md b/guide/diagrams/01-foundations.md index 3fa49c0..a92accc 100644 --- a/guide/diagrams/01-foundations.md +++ b/guide/diagrams/01-foundations.md @@ -1,6 +1,6 @@ --- title: "Claude Code — Foundations Diagrams" -description: "Core concepts: 4-layer model, workflow pipeline, decision tree, permission modes" +description: "Core concepts: 4-layer model, workflow pipeline, decision tree, 5 permission modes" tags: [foundations, architecture, getting-started] --- @@ -208,7 +208,7 @@ Task involves codebase? ### Permission Modes Comparison -Claude Code has 3 permission modes that control what it can do automatically vs. what requires your approval. Choosing the wrong mode is the #1 safety mistake. +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. ```mermaid flowchart TD @@ -231,6 +231,18 @@ flowchart TD B3["Use only in:
CI/CD, sandboxed
environments"] --> B2 end + subgraph PLAN["🔍 Plan Mode (Read-Only)"] + PL1(File reads) --> PL2([Auto-approved]) + PL3(File writes) --> PL4([Blocked]) + PL5(Shell commands) --> PL6([Blocked]) + PL7["Exit with /execute
or Shift+Tab"] --> PL2 + end + + subgraph DONTASK["🚫 dontAsk Mode"] + DA1(ALL operations) --> DA2([Auto-denied]) + DA3["Unless pre-approved
via /permissions add"] --> DA2 + end + style D2 fill:#7BC47F,color:#333 style D4 fill:#E87E2F,color:#fff style D6 fill:#E87E2F,color:#fff @@ -241,6 +253,11 @@ flowchart TD style A8 fill:#E87E2F,color:#fff style B2 fill:#E85D5D,color:#fff style B3 fill:#F5E6D3,color:#333 + style PL2 fill:#7BC47F,color:#333 + style PL4 fill:#E85D5D,color:#fff + style PL6 fill:#E85D5D,color:#fff + style DA2 fill:#E85D5D,color:#fff + style DA3 fill:#F5E6D3,color:#333 click D1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "Default Mode — Permission Modes" click D2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "Auto-approved" @@ -261,6 +278,16 @@ flowchart TD click B1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "bypassPermissions Mode" click B2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "Auto-approved (all)" click B3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "CI/CD, sandboxed only" + click PL1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "Plan Mode — File reads" + click PL2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "Auto-approved" + click PL3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "Plan Mode — File writes blocked" + click PL4 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "Blocked" + click PL5 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "Plan Mode — Shell commands blocked" + click PL6 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "Blocked" + click PL7 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "Exit Plan Mode" + click DA1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "dontAsk Mode — All operations" + click DA2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "Auto-denied" + click DA3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#14-permission-modes" "Pre-approve via /permissions add" ```
@@ -273,6 +300,13 @@ File reads → AUTO ✓ File reads → AUTO ✓ ALL ops → AUTO File writes → PROMPT File writes → AUTO ✓ Shell cmds → PROMPT Shell cmds → PROMPT Use: CI/CD only, Risky ops → PROMPT Risky ops → PROMPT sandboxed env + +Plan Mode (Read-Only) dontAsk Mode +───────────────────── ──────────── +File reads → AUTO ✓ ALL ops → AUTO DENIED ✗ +File writes → BLOCKED ✗ Unless pre-approved via +Shell cmds → BLOCKED ✗ /permissions add +Exit: /execute or Shift+Tab ```
diff --git a/guide/diagrams/04-architecture-internals.md b/guide/diagrams/04-architecture-internals.md index 321bdca..37f8860 100644 --- a/guide/diagrams/04-architecture-internals.md +++ b/guide/diagrams/04-architecture-internals.md @@ -76,7 +76,7 @@ Tool calls? │ ### Tool Categories & Selection -Claude Code has 5 tool categories, each optimized for different operations. Understanding which tool Claude chooses (and why) helps you write instructions that guide better tool selection. +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. ```mermaid flowchart TD @@ -85,6 +85,7 @@ flowchart TD ROOT --> EXECUTE ROOT --> WEB ROOT --> WORKFLOW + ROOT --> CONTROL subgraph READ["📖 Read Tools"] R1[Glob
Find files by pattern] @@ -114,6 +115,12 @@ flowchart TD WF2[NotebookEdit
Jupyter notebooks] end + subgraph CONTROL["🎛️ Control Flow Tools"] + CF1[EnterPlanMode / ExitPlanMode
Toggle plan mode] + CF2[EnterWorktree / ExitWorktree
Worktree navigation] + CF3[AskUserQuestion
Request human input] + end + style ROOT fill:#E87E2F,color:#fff style R1 fill:#6DB3F2,color:#fff style R2 fill:#6DB3F2,color:#fff @@ -128,6 +135,9 @@ flowchart TD style WB2 fill:#7BC47F,color:#333 style WF1 fill:#B8B8B8,color:#333 style WF2 fill:#B8B8B8,color:#333 + style CF1 fill:#B8B8B8,color:#333 + style CF2 fill:#B8B8B8,color:#333 + style CF3 fill:#B8B8B8,color:#333 click ROOT href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "Claude Code Tools" click R1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "Glob — Find files by pattern" @@ -143,6 +153,10 @@ flowchart TD click WB2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "WebFetch" click WF1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "TodoWrite — Task list" click WF2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "NotebookEdit — Jupyter" + click CONTROL href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "Control Flow Tools" + click CF1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "EnterPlanMode / ExitPlanMode" + click CF2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "EnterWorktree / ExitWorktree" + click CF3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md#2-the-tool-arsenal" "AskUserQuestion" ```
@@ -154,12 +168,15 @@ WRITE: Write (create), Edit (modify), MultiEdit (batch) EXECUTE: Bash (shell), Task (sub-agent) ← most powerful/risky WEB: WebSearch, WebFetch WORKFLOW: TodoWrite, NotebookEdit +CONTROL: EnterPlanMode/ExitPlanMode, EnterWorktree/ExitWorktree, AskUserQuestion ```
> **Source**: [Architecture: Tools](../core/architecture.md#tools) — Line ~213 +> *Simplified — additional tools available. See [Architecture: Tool Arsenal](../core/architecture.md#tools) for the full list.* + --- ### System Prompt Assembly diff --git a/guide/diagrams/05-mcp-ecosystem.md b/guide/diagrams/05-mcp-ecosystem.md index 21d1648..e1c0f26 100644 --- a/guide/diagrams/05-mcp-ecosystem.md +++ b/guide/diagrams/05-mcp-ecosystem.md @@ -215,7 +215,7 @@ DEFENSE: Read MCP source before installing. Especially check tool descriptions. ### MCP Config Hierarchy -MCP server configurations can live in 4 different locations. The resolution order determines which servers are available and who can override what. +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. ```mermaid flowchart TD @@ -228,6 +228,9 @@ flowchart TD B1["Use for:
Team-shared servers
(playwright, github)"] --> B D1["Use for:
Personal tools
(context7, grepai)"] --> D + NOTE2["⚠️ local + user scopes
both stored in ~/.claude.json
(separate configuration keys)"] -.-> C + NOTE2 -.-> D + style A fill:#E87E2F,color:#fff style B fill:#6DB3F2,color:#fff style C fill:#6DB3F2,color:#fff @@ -236,6 +239,7 @@ flowchart TD style A1 fill:#B8B8B8,color:#333 style B1 fill:#B8B8B8,color:#333 style D1 fill:#B8B8B8,color:#333 + style NOTE2 fill:#F5E6D3,color:#333 click A href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#83-configuration" "CLI --mcp-config flag" click B href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#83-configuration" "Project .claude/mcp.json" @@ -257,6 +261,7 @@ PRIORITY (highest → lowest): 3. ~/.claude.json → local scope (private, current project) 4. ~/.claude.json → user scope (personal, all projects) 5. (none) → no MCP servers available +* local + user both in ~/.claude.json (different keys) ``` diff --git a/guide/diagrams/07-multi-agent-patterns.md b/guide/diagrams/07-multi-agent-patterns.md index e60164a..b0b2d1c 100644 --- a/guide/diagrams/07-multi-agent-patterns.md +++ b/guide/diagrams/07-multi-agent-patterns.md @@ -279,6 +279,7 @@ flowchart TD A([Task to complete]) --> B{Need multiple
Claude instances?} B -->|No| C([Single session
Standard usage]) B -->|Yes| D{How many
instances?} + B -->|"Planning separation?"| B2{Need planning
separation?} D -->|2-3| E{Need branch
isolation?} E -->|Yes| F([Git worktrees
Separate branches]) @@ -289,7 +290,7 @@ flowchart TD H -->|Sequential pipeline| J([Agent pipeline
A → B → C]) H -->|Mixed expertise| K([Specialist router
Route by task type]) - B2{Need planning
separation?} --> L([Dual-instance
Planner + Executor]) + B2 --> L([Dual-instance
Planner + Executor]) style A fill:#F5E6D3,color:#333 style B fill:#E87E2F,color:#fff @@ -326,16 +327,15 @@ flowchart TD ``` Need multiple instances? ├─ No → Single session -└─ Yes → How many? - ├─ 2-3 → Need branch isolation? - │ ├─ Yes → Git worktrees - │ └─ No → Multiple terminals - └─ 4+ → Task structure? - ├─ Independent → Task tool (parallel sub-agents) - ├─ Sequential → Agent pipeline A→B→C - └─ Mixed → Specialist router - -Special case: Need planning separation? → Dual-instance (Planner + Executor) +├─ Yes → How many? +│ ├─ 2-3 → Need branch isolation? +│ │ ├─ Yes → Git worktrees +│ │ └─ No → Multiple terminals +│ └─ 4+ → Task structure? +│ ├─ Independent → Task tool (parallel sub-agents) +│ ├─ Sequential → Agent pipeline A→B→C +│ └─ Mixed → Specialist router +└─ Planning separation? → Dual-instance (Planner + Executor) ``` diff --git a/guide/diagrams/09-cost-and-optimization.md b/guide/diagrams/09-cost-and-optimization.md index 6d00217..d90b5d0 100644 --- a/guide/diagrams/09-cost-and-optimization.md +++ b/guide/diagrams/09-cost-and-optimization.md @@ -21,14 +21,14 @@ flowchart TD A([Task to complete]) --> B{Task complexity?} B -->|Simple| C["Simple tasks:
typo fixes, renames,
formatting, translations"] - C --> D([Haiku 4.5
💰 Cheapest, fastest
~$0.80/MTok input]) + C --> D([Haiku 4.5
💰 Cheapest, fastest
~5x cheaper than Sonnet]) B -->|Standard| E["Standard tasks:
feature implementation,
bug fixes, refactoring"] - E --> F([Sonnet 4.5/4.6
💰💰 Balanced
~$3/MTok input]) + E --> F([Sonnet 4.5/4.6
💰💰 Balanced
Best price/quality ratio]) 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]) + H --> I([Opus 4.6 / Sonnet + --think-hard
💰💰💰 Most capable
~5x more than Sonnet]) G -->|No: just large| J["Large but clear tasks:
big refactors,
doc generation"] J --> F @@ -56,6 +56,8 @@ flowchart TD click J href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#25-model-selection--thinking-guide" "Large but clear tasks" ``` +> **Pricing**: Relative costs shown — check current rates at [anthropic.com/pricing](https://www.anthropic.com/pricing). + **Budget modifier** — On constrained plans, downgrade one tier per phase: | Plan | Planning phase | Implementation phase | @@ -71,11 +73,11 @@ flowchart TD ``` Task complexity? -├─ Simple (typos, format, rename) → Haiku 4.5 ($ — ~5x cheaper) -├─ Standard (features, bugs) → Sonnet 4.5/4.6 ($$ — balanced) +├─ 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.6 ($$$ — most capable) - └─ Just large/clear? → Sonnet 4.6 ($$ — handles it) + ├─ Needs deep reasoning? → Opus 4.6 ($$$ — ~5x more than Sonnet) + └─ Just large/clear? → Sonnet 4.6 ($$ — handles it) Budget modifier (downgrade one tier on constrained plans): Max/API → Opus plan, Sonnet impl diff --git a/guide/diagrams/11-context-engineering.md b/guide/diagrams/11-context-engineering.md new file mode 100644 index 0000000..93b58f2 --- /dev/null +++ b/guide/diagrams/11-context-engineering.md @@ -0,0 +1,285 @@ +--- +title: "Claude Code — Context Engineering Diagrams" +description: "3-layer context system, adherence degradation, modular architecture, rule placement decision tree" +tags: [context-engineering, configuration, architecture, modular, adherence] +--- + +# Context Engineering + +How to fill Claude's context window with the right information at the right time — and how architectural choices determine whether Claude consistently follows your conventions. + +> "Context engineering is the art of filling the context window with the right information at the right time." — Andrej Karpathy + +--- + +### The 3-Layer Context System + +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. + +```mermaid +flowchart TD + subgraph GLOBAL["🌍 Layer 1: Global — ~/.claude/CLAUDE.md"] + G1["Identity & tone preferences"] + G2["Universal tool preferences"] + G3["Cross-project coding conventions"] + G4["Target: under 200 lines"] + end + + subgraph PROJECT["📁 Layer 2: Project — ./CLAUDE.md + path modules"] + P1["Stack & architecture decisions"] + P2["Team conventions + deployment rules"] + P3["Path-scoped @imports for subsystems"] + P4["Target: under 150 lines (root) + modules"] + end + + subgraph SESSION["⚡ Layer 3: Session — inline instructions, /add, flags"] + S1["One-off task constraints"] + S2["Temporary overrides"] + S3["Ephemeral — not persisted after session"] + end + + GLOBAL --> PROJECT --> SESSION + + OVR["Override order: Session > Project > Global
More specific beats less specific
Later-declared beats earlier at same level"] -.-> SESSION + + style G1 fill:#E87E2F,color:#fff + style G2 fill:#E87E2F,color:#fff + style G3 fill:#E87E2F,color:#fff + style G4 fill:#B8B8B8,color:#333 + style P1 fill:#6DB3F2,color:#fff + style P2 fill:#6DB3F2,color:#fff + style P3 fill:#6DB3F2,color:#fff + style P4 fill:#B8B8B8,color:#333 + style S1 fill:#F5E6D3,color:#333 + style S2 fill:#F5E6D3,color:#333 + style S3 fill:#B8B8B8,color:#333 + style OVR fill:#7BC47F,color:#333 + + click G1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Identity & tone" + click G2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Universal tools" + click G3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Cross-project conventions" + click G4 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Target: under 200 lines" + click P1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Stack & architecture" + click P2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Team conventions" + click P3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Path-scoped imports" + click P4 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#4-modular-architecture" "Target: under 150 lines" + click S1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "One-off constraints" + click S2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Temporary overrides" + click S3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Ephemeral" + click OVR href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Override semantics" +``` + +
+ASCII version + +``` +GLOBAL ~/.claude/CLAUDE.md → Identity, universal tools, cross-project conventions (<200 lines) + │ overridden by ↓ +PROJECT ./CLAUDE.md + modules → Stack, architecture, team rules, path-scoped @imports (<150 lines root) + │ overridden by ↓ +SESSION inline / /add / flags → One-off constraints, temporary overrides (ephemeral) + +Override order: Session > Project > Global +More specific beats less specific at the same level +``` + +
+ +> **Source**: [Context Engineering — Configuration Hierarchy](../core/context-engineering.md#3-configuration-hierarchy) + +--- + +### Context Budget & Adherence Degradation + +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. + +```mermaid +flowchart LR + subgraph ZONES["Adherence by CLAUDE.md lines"] + Z1["1–100 lines
~95% adherence ✓"] + Z2["100–200 lines
~88% adherence"] + Z3["200–400 lines
~75% adherence ⚠️"] + Z4["400–600 lines
~60% adherence"] + Z5["600+ lines
~45% and falling ✗"] + end + + Z1 --> Z2 --> Z3 --> Z4 --> Z5 + + FIX["✅ Path-scoping fix:
Root CLAUDE.md: shared rules only (~2K tokens)
Per subsystem: module loaded on demand
Result: 40–50% always-on reduction
Adherence stays in green zone"] -.-> Z1 + + SIGNALS["🔴 Signs of context overload:
Rule silencing (80% followed, some ignored)
Contradictory behavior across files
Generic outputs instead of project-specific
Slow first responses"] -.-> Z5 + + style Z1 fill:#7BC47F,color:#333 + style Z2 fill:#7BC47F,color:#333 + style Z3 fill:#E87E2F,color:#fff + style Z4 fill:#E85D5D,color:#fff + style Z5 fill:#E85D5D,color:#fff + style FIX fill:#7BC47F,color:#333 + style SIGNALS fill:#E85D5D,color:#fff + + click Z1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#2-the-context-budget" "1-100 lines: ~95%" + click Z2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#2-the-context-budget" "100-200 lines: ~88%" + click Z3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#2-the-context-budget" "200-400 lines: ~75%" + click Z4 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#2-the-context-budget" "400-600 lines: ~60%" + click Z5 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#2-the-context-budget" "600+ lines: ~45%" + click FIX href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#2-the-context-budget" "Path-scoping fix" + click SIGNALS href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#2-the-context-budget" "Signs of overload" +``` + +
+ASCII version + +``` +Lines in CLAUDE.md Adherence Status +────────────────── ───────── ────── +1 – 100 ~95% ✓ Green zone +100 – 200 ~88% ✓ Acceptable +200 – 400 ~75% ⚠️ Caution +400 – 600 ~60% ✗ Degraded +600+ ~45% ↓ ✗ Critical + +Fix: path-scope by subsystem → root CLAUDE.md stays <150 lines +Result: 40-50% always-on context reduction, adherence back in green zone +``` + +
+ +> **Source**: [Context Budget](../core/context-engineering.md#2-the-context-budget) — Adherence data: HumanLayer production data (15-25% improvement with structured context) + +--- + +### Monolithic vs. Modular Architecture + +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. + +```mermaid +flowchart TD + subgraph BAD["❌ Anti-Pattern: Monolithic CLAUDE.md"] + B1(["CLAUDE.md (600 lines)
API rules + DB rules + UI rules
+ Deploy rules — all mixed together"]) + B2("All 600 lines loaded
for every session, every file") + B3("Rules 1–20 get ~95% attention
Rules 500+ get ~30% attention") + B4(["Adherence degrades continuously"]) + B1 --> B2 --> B3 --> B4 + style B1 fill:#E85D5D,color:#fff + style B2 fill:#E85D5D,color:#fff + style B3 fill:#E87E2F,color:#fff + style B4 fill:#E85D5D,color:#fff + end + + subgraph GOOD["✅ Best Practice: Path-Scoped Modules"] + G1(["CLAUDE.md root (~100 lines)
Shared rules only + @import declarations"]) + G2["src/api/CLAUDE-api.md
Loaded ONLY when in src/api/"] + G3["src/components/CLAUDE-components.md
Loaded ONLY when in src/components/"] + G4["prisma/CLAUDE-db.md
Loaded ONLY when in prisma/"] + G5(["Each module: full coverage
Always-on: 40–50% smaller"]) + G1 --> G2 + G1 --> G3 + G1 --> G4 + G2 & G3 & G4 --> G5 + style G1 fill:#7BC47F,color:#333 + style G2 fill:#6DB3F2,color:#fff + style G3 fill:#6DB3F2,color:#fff + style G4 fill:#6DB3F2,color:#fff + style G5 fill:#7BC47F,color:#333 + end + + click B1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#4-modular-architecture" "Anti-pattern: monolith" + click B4 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#2-the-context-budget" "Adherence degradation" + click G1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#4-modular-architecture" "Root CLAUDE.md" + click G2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#4-modular-architecture" "API module" + click G3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#4-modular-architecture" "Components module" + click G4 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#4-modular-architecture" "DB module" + click G5 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#4-modular-architecture" "Result: coverage with less bloat" +``` + +
+ASCII version + +``` +BAD: CLAUDE.md (600 lines, everything mixed) + → All 600 lines loaded every session + → Rules 500+ get ~30% attention weight + → Adherence degrades continuously + +GOOD: Root CLAUDE.md (~100 lines, shared only) + + src/api/CLAUDE-api.md ← loaded only when editing API files + + src/components/CLAUDE-*.md ← loaded only when editing components + + prisma/CLAUDE-db.md ← loaded only when editing DB files + +Result: 40-50% reduction in always-on tokens, full coverage per subsystem +``` + +
+ +> **Source**: [Modular Architecture](../core/context-engineering.md#4-modular-architecture) — Path-scoping pattern + +--- + +### Rule Placement Decision Tree + +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. + +```mermaid +flowchart TD + A([New rule or instruction to place]) --> B{Relevant to\nevery project\nyou work on?} + B -->|Yes| C([Global CLAUDE.md
~/.claude/CLAUDE.md]) + + B -->|No| D{Specific to\ncertain files\nor subsystems?} + D -->|Yes| E([Path-scoped module
e.g. src/api/CLAUDE-api.md]) + + D -->|No| F{Procedural
step-by-step\nworkflow?} + F -->|Yes: how to do something| G([Skill file
.claude/skills/task-name.md
Loaded on demand, not always-on]) + + F -->|No: constraint or standard| H{Applies to
whole project?} + H -->|Yes| I([Project CLAUDE.md root
./CLAUDE.md]) + H -->|No: one task only| J([Session inline instruction
Tell Claude directly this session]) + + RULE["Rule of thumb:
If you write it more than once
it belongs in a permanent layer"] -.-> J + + style A fill:#F5E6D3,color:#333 + style B fill:#E87E2F,color:#fff + style D fill:#E87E2F,color:#fff + style F fill:#E87E2F,color:#fff + style H fill:#E87E2F,color:#fff + style C fill:#E87E2F,color:#fff + style E fill:#6DB3F2,color:#fff + style G fill:#6DB3F2,color:#fff + style I fill:#6DB3F2,color:#fff + style J fill:#F5E6D3,color:#333 + style RULE fill:#7BC47F,color:#333 + + click A href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "New rule to place" + click B href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Relevant to every project?" + click C href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#31-memory-files-claudemd" "Global CLAUDE.md" + click D href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#4-modular-architecture" "Specific to certain files?" + click E href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#4-modular-architecture" "Path-scoped module" + click F href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#4-modular-architecture" "Procedural workflow?" + click G href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#51-understanding-skills" "Skill file" + click H href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Whole project?" + click I href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#31-memory-files-claudemd" "Project CLAUDE.md root" + click J href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Session inline" + click RULE href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/context-engineering.md#3-configuration-hierarchy" "Rule of thumb" +``` + +
+ASCII version + +``` +New rule to place +│ +Relevant to every project? ──Yes──► Global CLAUDE.md (~/.claude/CLAUDE.md) +│ No +Specific to certain files/subsystems? ──Yes──► Path-scoped module (src/area/CLAUDE-area.md) +│ No +Procedural step-by-step? ──Yes──► Skill file (.claude/skills/) [loaded on demand] +│ No +Applies to whole project? ──Yes──► Project CLAUDE.md root (./CLAUDE.md) +│ No +└──► Session inline instruction (ephemeral) + +Rule of thumb: if you say it more than once, promote it to a permanent layer. +``` + +
+ +> **Source**: [Rule Placement](../core/context-engineering.md#3-configuration-hierarchy) — Decision tree from §3 diff --git a/guide/diagrams/12-enterprise-governance.md b/guide/diagrams/12-enterprise-governance.md new file mode 100644 index 0000000..744854c --- /dev/null +++ b/guide/diagrams/12-enterprise-governance.md @@ -0,0 +1,208 @@ +--- +title: "Claude Code — Enterprise Governance Diagrams" +description: "Governance risk tiers, MCP approval workflow, guardrail tier selection" +tags: [security, enterprise, governance, compliance, mcp] +--- + +# Enterprise Governance + +Org-level patterns for teams deploying Claude Code at scale — usage tiers, MCP approval workflows, and guardrail configurations. + +> **Audience**: Tech leads, engineering managers, security officers. For individual dev security see [Security & Production](./08-security-and-production.md). + +--- + +### Governance Risk Tiers — What to Control and When + +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). + +```mermaid +flowchart TD + A([What are you governing?]) --> B{Usage context?} + + B --> P["Personal dev workflow
Local, throwaway code
One developer only"] + B --> T["Team codebase
Shared repo, not production
5–20 developers"] + B --> PR["Production system
Customer-facing, real data
Any team size"] + B --> REG["Regulated environment
HIPAA, SOC2, PCI, finance
Legal/compliance obligations"] + + P --> TIER1(["Tier 1: Starter
CLAUDE.md guidelines
+ dangerous-actions-blocker hook
10 min setup"]) + T --> TIER2(["Tier 2: Standard
Shared settings.json + MCP registry
+ PR gates + audit log
~2 hours setup"]) + PR --> TIER3(["Tier 3: Strict
Full permission deny list
+ approval workflow
+ session audit trail"]) + REG --> TIER4(["Tier 4: Regulated
All of above
+ compliance audit trail
+ SOC2/ISO27001 controls"]) + + NOTE["You CAN control: MCP servers, tool permissions,
CLAUDE.md content, hooks, CI/CD gates
You CANNOT control: personal ~/.claude settings,
models on personal API keys, personal projects"] -.-> B + + style A fill:#F5E6D3,color:#333 + style B fill:#E87E2F,color:#fff + style P fill:#B8B8B8,color:#333 + style T fill:#6DB3F2,color:#fff + style PR fill:#E87E2F,color:#fff + style REG fill:#E85D5D,color:#fff + style TIER1 fill:#7BC47F,color:#333 + style TIER2 fill:#7BC47F,color:#333 + style TIER3 fill:#E87E2F,color:#fff + style TIER4 fill:#E85D5D,color:#fff + style NOTE fill:#F5E6D3,color:#333 + + click A href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#1-local-vs-shared-the-governance-split" "What are you governing?" + click B href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#1-local-vs-shared-the-governance-split" "Usage context?" + click P href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#4-guardrail-tiers" "Personal dev workflow" + click T href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#4-guardrail-tiers" "Team codebase" + click PR href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#4-guardrail-tiers" "Production system" + click REG href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#4-guardrail-tiers" "Regulated environment" + click TIER1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#4-guardrail-tiers" "Tier 1: Starter" + click TIER2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#4-guardrail-tiers" "Tier 2: Standard" + click TIER3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#4-guardrail-tiers" "Tier 3: Strict" + click TIER4 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#4-guardrail-tiers" "Tier 4: Regulated" + click NOTE href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#12-what-you-can-and-cant-control" "What you can/cannot control" +``` + +
+ASCII version + +``` +Usage context? +├─ Personal dev workflow → Tier 1: Starter (CLAUDE.md + basic hooks, 10 min) +├─ Team codebase → Tier 2: Standard (shared settings.json + MCP registry + PR gates) +├─ Production system → Tier 3: Strict (full deny list + approval + audit trail) +└─ Regulated (HIPAA/SOC2/PCI) → Tier 4: Regulated (all above + compliance audit trail) + +You CAN control: settings.json in repo, CLAUDE.md, hooks, CI/CD gates, MCP registry +You CANNOT control: personal ~/.claude, personal API key model choice, personal projects +``` + +
+ +> **Source**: [Enterprise Governance](../security/enterprise-governance.md) — §1 Governance Split, §4 Guardrail Tiers + +--- + +### MCP Governance Workflow + +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. + +```mermaid +sequenceDiagram + participant DEV as Developer + participant TL as Tech Lead + Security + participant REG as MCP Registry
.claude/mcp-registry.yaml + participant REPO as Shared Config Repo
settings.json + + DEV->>TL: Submit MCP request
Name, source URL, use case, data scope + + TL->>TL: 5-min security audit
Stars >50? Recent commits?
CVEs? Dangerous flags? + TL->>TL: Classify risk: LOW / MEDIUM / HIGH + + alt LOW risk + TL->>REG: Approve — add to registry
Pin version, set 6-month expiry + else MEDIUM or HIGH risk + TL->>TL: 2-week sandbox trial
+ Security team sign-off + TL->>REG: Approve with restrictions
Shorter expiry (3 months) + else HIGH risk (unacceptable) + TL->>DEV: Denied — document reason in registry + end + + REG->>REPO: Deploy via committed settings.json
No local overrides for approved MCPs + Note over REPO: Version-pinned, team-wide, auditable + + REPO->>TL: Monitor every 30 days
Patch bumps: auto re-approve
Minor+ bumps: manual re-review
Quarterly: full registry audit +``` + +
+ASCII version + +``` +Developer submits MCP request (name, source, use case, data scope) + │ +Tech Lead: 5-min security audit (stars, commits, CVEs, flags) + │ +Classify risk: LOW / MEDIUM / HIGH + │ +┌───┴────────────────────────────┐ +LOW MED/HIGH +Approve immediately 2-week sandbox trial + + Security team sign-off + │ +Add to registry (.claude/mcp-registry.yaml) + - Pin exact version + - Set expiry (6 months for LOW, 3 months for MED) + - Document approved scope + │ +Deploy via committed settings.json (no local overrides) + │ +Monitor every 30 days: + - Check security advisories + - Patch bumps: auto | Minor+ bumps: manual re-review + - Quarterly: full registry audit +``` + +
+ +> **Source**: [MCP Governance Workflow](../security/enterprise-governance.md#3-mcp-governance-workflow) — §3.1 Approval Workflow + +--- + +### Data Classification & Claude Code Access Rules + +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. + +```mermaid +flowchart LR + subgraph PUBLIC["🟢 PUBLIC"] + PU1["Open source code
Public documentation
Shared blog content"] + PU2(["Allowed — no restrictions"]) + end + + subgraph INTERNAL["🔵 INTERNAL"] + IN1["Internal tools
Non-sensitive code
Team documentation"] + IN2(["Allowed — standard config"]) + end + + subgraph CONFIDENTIAL["🟠 CONFIDENTIAL"] + CO1["Internal business secrets
Non-regulated IP
Architecture docs"] + CO2(["Enterprise plan only
Zero Data Retention required"]) + end + + subgraph RESTRICTED["🔴 RESTRICTED"] + RE1["Customer PII
PCI card data / PHI
Credentials & API keys"] + RE2(["NEVER in AI context
Block via permissions.deny
No exceptions"]) + end + + PU1 --> PU2 + IN1 --> IN2 + CO1 --> CO2 + RE1 --> RE2 + + style PU2 fill:#7BC47F,color:#333 + style IN2 fill:#6DB3F2,color:#fff + style CO2 fill:#E87E2F,color:#fff + style RE2 fill:#E85D5D,color:#fff + style RE1 fill:#E85D5D,color:#fff + + click PU1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#2-ai-usage-charter" "PUBLIC data" + click IN1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#2-ai-usage-charter" "INTERNAL data" + click CO1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#2-ai-usage-charter" "CONFIDENTIAL data" + click RE1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#2-ai-usage-charter" "RESTRICTED data" + click PU2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#2-ai-usage-charter" "PUBLIC: allowed" + click IN2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#2-ai-usage-charter" "INTERNAL: standard config" + click CO2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#2-ai-usage-charter" "CONFIDENTIAL: Enterprise only" + click RE2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/security/enterprise-governance.md#2-ai-usage-charter" "RESTRICTED: never in AI context" +``` + +
+ASCII version + +``` +PUBLIC → Allowed, no restrictions +INTERNAL → Allowed, standard config +CONFIDENTIAL → Enterprise plan only (Zero Data Retention required) +RESTRICTED → NEVER in AI context (PII, PCI, PHI, credentials) + Block via: permissions.deny Read(.env, *.key, *.pem, secrets/**) + +Hard rule: RESTRICTED data never enters a context window. +Not in prompts, not in files Claude reads, not as examples. +``` + +
+ +> **Source**: [AI Usage Charter](../security/enterprise-governance.md#2-ai-usage-charter) — §2.1 Data Classification diff --git a/guide/diagrams/README.md b/guide/diagrams/README.md index 16e955d..a5a42f4 100644 --- a/guide/diagrams/README.md +++ b/guide/diagrams/README.md @@ -1,12 +1,12 @@ --- title: "Claude Code — Visual Diagrams" -description: "41 Mermaid interactive diagrams covering all major Claude Code concepts" +description: "48 Mermaid interactive diagrams covering all major Claude Code concepts" tags: [reference, architecture, diagrams, mermaid] --- # Claude Code — Visual Diagrams -41 interactive Mermaid diagrams organized in 10 thematic files. Each diagram includes a Mermaid version (rendered natively on GitHub) and an ASCII fallback. +48 interactive Mermaid diagrams organized in 10 thematic files. Each diagram includes a Mermaid version (rendered natively on GitHub) and an ASCII fallback. > For ASCII-only diagrams and a printable visual reference → [visual-reference.md](../core/visual-reference.md) @@ -52,7 +52,9 @@ All diagrams use the consistent Bold Guy palette: | [08-security-and-production.md](./08-security-and-production.md) | 4 | 3-layer defense, sandbox decision, verification paradox, CI/CD pipeline | | [09-cost-and-optimization.md](./09-cost-and-optimization.md) | 4 | Model selection, cost optimization, subscription tiers, token reduction | | [10-adoption-and-learning.md](./10-adoption-and-learning.md) | 3 | Onboarding paths, UVAL protocol, trust calibration | -| **Total** | **41** | | +| [11-context-engineering.md](./11-context-engineering.md) | 4 | 3-layer context system, adherence degradation, modular architecture, rule placement | +| [12-enterprise-governance.md](./12-enterprise-governance.md) | 3 | Governance risk tiers, MCP approval workflow, data classification | +| **Total** | **48** | | --- @@ -93,6 +95,17 @@ All diagrams use the consistent Bold Guy palette: 2. [MCP Architecture](./05-mcp-ecosystem.md#mcp-architecture-client-server) — How it works 3. [MCP Config Hierarchy](./05-mcp-ecosystem.md#mcp-config-hierarchy) — Where configs live +### "I want to govern Claude Code across my team" +1. [Governance Risk Tiers](./12-enterprise-governance.md#governance-risk-tiers) — Which control level fits your context? +2. [MCP Governance Workflow](./12-enterprise-governance.md#mcp-governance-workflow) — Approval pipeline for MCP servers +3. [Data Classification Rules](./12-enterprise-governance.md#data-classification--claude-code-access-rules) — What Claude can and cannot access + +### "I want to improve Claude's context adherence" +1. [Rule Placement Decision Tree](./11-context-engineering.md#rule-placement-decision-tree) — Where does this rule go? +2. [3-Layer Context System](./11-context-engineering.md#the-3-layer-context-system) — Global / Project / Session +3. [Context Budget & Adherence](./11-context-engineering.md#context-budget--adherence-degradation) — Why rules stop being followed +4. [Modular Architecture](./11-context-engineering.md#monolithic-vs-modular-architecture) — Path-scoping as the fix + --- *Back to [guide/README.md](../README.md) | ASCII diagrams → [visual-reference.md](../core/visual-reference.md)*