feat(docs): add architecture deep-dive documentation v3.4.0

Add comprehensive technical documentation explaining Claude Code internals:

- NEW: guide/architecture.md (~800 lines) - Complete architecture deep-dive
  - Master Loop (while tool_call), Tool Arsenal, Context Management
  - Sub-Agent Architecture, Permission System, MCP Integration
  - Edit Tool mechanics, Session persistence, Philosophy comparison
  - 5 ASCII diagrams, source confidence tiers (Tier 1/2/3)

- guide/ultimate-guide.md: Add Section 2.7 "Under the Hood" summary
- guide/cheatsheet.md: Add "Under the Hood (Quick Facts)" section
- machine-readable/reference.yaml: Add architecture index + deep_dive refs
- Update all navigation links across repository

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX 2026-01-14 21:29:46 +01:00
parent fb49152ee5
commit f9044e2deb
11 changed files with 1003 additions and 7 deletions

View file

@ -3,14 +3,24 @@
# Source: guide/ultimate-guide.md
# Purpose: Condensed index for LLMs to quickly answer user questions about Claude Code
version: "3.3.0"
version: "3.4.0"
updated: "2026-01"
# ════════════════════════════════════════════════════════════════
# DEEP DIVE - Line numbers in guide/ultimate-guide.md
# Usage: Read file at line N for detailed documentation on topic
# For architecture internals, see guide/architecture.md
# ════════════════════════════════════════════════════════════════
deep_dive:
# Architecture internals (guide/architecture.md)
architecture_master_loop: "guide/architecture.md:60"
architecture_tools: "guide/architecture.md:130"
architecture_context: "guide/architecture.md:200"
architecture_subagents: "guide/architecture.md:280"
architecture_permissions: "guide/architecture.md:350"
architecture_mcp: "guide/architecture.md:450"
architecture_philosophy: "guide/architecture.md:580"
# Main guide (guide/ultimate-guide.md)
installation: 185
first_workflow: 266
essential_commands: 315
@ -197,6 +207,19 @@ mcp:
check: "/mcp"
config: ".claude/mcp.json or ~/.claude.json"
# ════════════════════════════════════════════════════════════════
# ARCHITECTURE INTERNALS - see guide/architecture.md
# ════════════════════════════════════════════════════════════════
architecture:
master_loop: "while(tool_call) - no DAG, no classifier, no RAG"
core_tools: "Bash, Read, Edit, Write, Grep, Glob, Task, TodoWrite"
context_budget: "~200K tokens, auto-compact at 75-92%"
subagents: "Task tool spawns isolated agents (depth=1 max)"
philosophy: "less scaffolding, more model - trust Claude's reasoning"
mcp_protocol: "JSON-RPC 2.0, treated as native tools"
permissions: "interactive prompts + allow/deny rules + hooks"
deep_dive: "guide/architecture.md"
# ════════════════════════════════════════════════════════════════
# THINK LEVELS - see deep_dive.trinity_pattern
# ════════════════════════════════════════════════════════════════