marketing-shibata50/claude-code-ultimate-guide

Florian BRUNIAUX a4a6c49cb5 docs(diagrams): audit, fix and expand Mermaid diagram suite (7 files → 9)

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 <noreply@anthropic.com>

2026-03-13 10:08:49 +01:00

15 KiB

Raw Blame History

title

description

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.

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<br/>More specific beats less specific<br/>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

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.

flowchart LR
    subgraph ZONES["Adherence by CLAUDE.md lines"]
        Z1["1–100 lines<br/>~95% adherence ✓"]
        Z2["100–200 lines<br/>~88% adherence"]
        Z3["200–400 lines<br/>~75% adherence ⚠️"]
        Z4["400–600 lines<br/>~60% adherence"]
        Z5["600+ lines<br/>~45% and falling ✗"]
    end

    Z1 --> Z2 --> Z3 --> Z4 --> Z5

    FIX["✅ Path-scoping fix:<br/>Root CLAUDE.md: shared rules only (~2K tokens)<br/>Per subsystem: module loaded on demand<br/>Result: 40–50% always-on reduction<br/>Adherence stays in green zone"] -.-> Z1

    SIGNALS["🔴 Signs of context overload:<br/>Rule silencing (80% followed, some ignored)<br/>Contradictory behavior across files<br/>Generic outputs instead of project-specific<br/>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 — 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.

flowchart TD
    subgraph BAD["❌ Anti-Pattern: Monolithic CLAUDE.md"]
        B1(["CLAUDE.md (600 lines)<br/>API rules + DB rules + UI rules<br/>+ Deploy rules — all mixed together"])
        B2("All 600 lines loaded<br/>for every session, every file")
        B3("Rules 1–20 get ~95% attention<br/>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)<br/>Shared rules only + @import declarations"])
        G2["src/api/CLAUDE-api.md<br/>Loaded ONLY when in src/api/"]
        G3["src/components/CLAUDE-components.md<br/>Loaded ONLY when in src/components/"]
        G4["prisma/CLAUDE-db.md<br/>Loaded ONLY when in prisma/"]
        G5(["Each module: full coverage<br/>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 — 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.

flowchart TD
    A([New rule or instruction to place]) --> B{Relevant to\nevery project\nyou work on?}
    B -->|Yes| C([Global CLAUDE.md<br/>~/.claude/CLAUDE.md])

    B -->|No| D{Specific to\ncertain files\nor subsystems?}
    D -->|Yes| E([Path-scoped module<br/>e.g. src/api/CLAUDE-api.md])

    D -->|No| F{Procedural<br/>step-by-step\nworkflow?}
    F -->|Yes: how to do something| G([Skill file<br/>.claude/skills/task-name.md<br/>Loaded on demand, not always-on])

    F -->|No: constraint or standard| H{Applies to<br/>whole project?}
    H -->|Yes| I([Project CLAUDE.md root<br/>./CLAUDE.md])
    H -->|No: one task only| J([Session inline instruction<br/>Tell Claude directly this session])

    RULE["Rule of thumb:<br/>If you write it more than once<br/>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 — Decision tree from §3

15 KiB Raw Blame History Unescape Escape

Context Engineering

The 3-Layer Context System

Context Budget & Adherence Degradation

Monolithic vs. Modular Architecture

Rule Placement Decision Tree

15 KiB

Raw Blame History