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

@ -8,7 +8,8 @@ This repository provides everything needed to go from Claude Code beginner to po
1. **Complete Guide** (`guide/ultimate-guide.md`) - 4700+ lines covering all aspects of Claude Code
2. **Cheatsheet** (`guide/cheatsheet.md`) - 1-page printable daily reference
3. **Audit Prompt** (`tools/audit-prompt.md`) - Self-contained prompt to analyze your Claude Code setup against best practices
3. **Architecture Internals** (`guide/architecture.md`) - How Claude Code works under the hood (master loop, tools, context)
4. **Audit Prompt** (`tools/audit-prompt.md`) - Self-contained prompt to analyze your Claude Code setup against best practices
## Target Audience
@ -56,6 +57,7 @@ claude-code-ultimate-guide/
├── guide/ # Core documentation
│ ├── ultimate-guide.md # Complete guide (main content)
│ ├── cheatsheet.md # 1-page reference
│ ├── architecture.md # How Claude Code works internally
│ └── adoption-approaches.md # Implementation strategy
├── tools/ # Interactive utilities
│ ├── audit-prompt.md # Setup audit tool
@ -77,8 +79,16 @@ claude-code-ultimate-guide/
└── quiz/ # Interactive knowledge quiz
```
## Guide Structure (10 Sections)
## Guide Structure (10 Sections + Architecture)
**Architecture Deep Dive** (`guide/architecture.md`):
- Master Loop: `while(tool_call)` - no DAGs, no classifiers, no RAG
- 8 Core Tools: Bash, Read, Edit, Write, Grep, Glob, Task, TodoWrite
- Context: ~200K tokens, auto-compact at 75-92%
- Sub-agents: isolated context, max depth=1
- Philosophy: "less scaffolding, more model"
**Main Guide Sections** (`guide/ultimate-guide.md`):
1. **Quick Start** - Installation, first workflow, essential commands
2. **Core Concepts** - Context management, Plan Mode, Rewind, Mental Model
3. **Memory & Settings** - CLAUDE.md files, .claude/ folder, precedence rules

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
# ════════════════════════════════════════════════════════════════