fix(docs): remove marketing language and unverified claims v3.0.6

Documentation honesty overhaul addressing community feedback: README.md: - Add transparency disclaimer - Replace time estimates with depth categories - Fix privacy claim accuracy - Remove "superpower" marketing language english-ultimate-claude-code-guide.md: - Add "Before You Start" disclaimer section - Remove "Guide Status 100%" false certainty table - Replace invented percentages with qualified observations - Remove fake ROI calculations - Add LLM hallucination warnings adoption-approaches.md: - Add uncertainty acknowledgment - Change prescriptive tone to tentative observations ~30 edits removing invented metrics and marketing claims. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-13 14:15:39 +01:00 · 2026-01-13 14:15:39 +01:00 · 12da452c89
commit 12da452c89
parent 1b3310c93e
5 changed files with 300 additions and 271 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -6,6 +6,40 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

 ## [Unreleased]

+## [3.0.6] - 2026-01-13
+
+### Changed
+- **Documentation honesty overhaul** - Removed marketing language and unverified claims
+  - **README.md** (~12 edits):
+    - Added transparency disclaimer after badges
+    - Changed "Transform...superpower" → factual description of content
+    - Changed "Our Solution: in hours, not weeks" → honest framing
+    - Replaced time estimates with depth categories (Essentials, Foundation, Intermediate, Comprehensive)
+    - Fixed "2 seconds" claims → "Quick (~30 seconds)"
+    - Corrected privacy claim ("Everything runs locally" → accurate API explanation)
+    - Changed "mentor for Claude Code mastery" → "structured learning companion"
+  - **english-ultimate-claude-code-guide.md** (~15 edits):
+    - Added "Before You Start" disclaimer section at top
+    - Removed "Guide Status 100% Complete" table (false certainty)
+    - Added qualifying note after context thresholds table
+    - "90% of daily usage" → "the ones I use most frequently"
+    - "20-30% faster" → subjective productivity indicators
+    - "Saves 30-40%" → "Frees significant context space"
+    - Removed invented ROI table with fake calculations
+    - "Never guesses - always verifies" → with LLM hallucination warning
+    - Removed "12,400% ROI" ridiculous claim
+    - "90% of tasks" → "most common tasks"
+    - "80-90% savings" → "significant (varies by project)"
+  - **adoption-approaches.md** (already in 3.0.5):
+    - Added disclaimer about Claude Code being young (~1 year)
+    - Added "What We Don't Know Yet" section
+    - Changed prescriptive language to tentative observations
+
+### Stats
+- 3 files modified (README.md, english-ultimate-claude-code-guide.md, cheatsheet-en.md)
+- ~30 edits removing invented percentages, times, and marketing claims
+- Focus on honest, qualified observations over false authority
+
 ## [3.0.5] - 2026-01-13

 ### Added
--- a/README.md
+++ b/README.md
@ -1,33 +1,48 @@
-# Master Claude Code: The Complete Guide from Beginner to Power User
-
-> **Transform Anthropic's AI coding CLI into your superpower.** 8500+ lines covering installation, agents, MCP servers, hooks, skills, and CI/CD integration—presented as a learning journey, not a reference manual.
+# Claude Code Guide

 [![License: CC BY-SA 4.0](https://img.shields.io/badge/License-CC%20BY--SA%204.0-blue.svg)](https://creativecommons.org/licenses/by-sa/4.0/)
 [![GitHub stars](https://img.shields.io/github/stars/FlorianBruniaux/claude-code-ultimate-guide?style=social)](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/stargazers)
 [![Ask Zread](https://img.shields.io/badge/Ask_Zread-_.svg?style=flat&color=00b0aa&labelColor=000000&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTQuOTYxNTYgMS42MDAxSDIuMjQxNTZDMS44ODgxIDEuNjAwMSAxLjYwMTU2IDEuODg2NjQgMS42MDE1NiAyLjI0MDFWNC45NjAxQzEuNjAxNTYgNS4zMTM1NiAxLjg4ODEgNS42MDAxIDIuMjQxNTYgNS42MDAxSDQuOTYxNTZDNS4zMTUwMiA1LjYwMDEgNS42MDE1NiA1LjMxMzU2IDUuNjAxNTYgNC45NjAxVjIuMjQwMUM1LjYwMTU2IDEuODg2NjQgNS4zMTUwMiAxLjYwMDEgNC45NjE1NiAxLjYwMDFaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00Ljk2MTU2IDEwLjM5OTlIMi4yNDE1NkMxLjg4ODEgMTAuMzk5OSAxLjYwMTU2IDEwLjY4NjQgMS42MDE1NiAxMS4wMzk5VjEzLjc1OTlDMS42MDE1NiAxNC4xMTM0IDEuODg4MSAxNC4zOTk5IDIuMjQxNTYgMTQuMzk5OUg0Ljk2MTU2QzUuMzE1MDIgMTQuMzk5OSA1LjYwMTU2IDE0LjExMzQgNS42MDE1NiAxMy43NTk5VjExLjAzOTlDNS42MDE1NiAxMC42ODY0IDUuMzE1MDIgMTAuMzk5OSA0Ljk2MTU2IDEwLjM5OTlaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik0xMy43NTg0IDEuNjAwMUgxMS4wMzg0QzEwLjY4NSAxLjYwMDEgMTAuMzk4NCAxLjg4NjY0IDEwLjM5ODQgMi4yNDAxVjQuOTYwMUMxMC4zOTg0IDUuMzEzNTYgMTAuNjg1IDUuNjAwMSAxMS4wMzg0IDUuNjAwMUgxMy43NTg0QzE0LjExMTkgNS42MDAxIDE0LjM5ODQgNS4zMTM1NiAxNC4zOTg0IDQuOTYwMVYyLjI0MDFDMTQuMzk4NCAxLjg4NjY0IDE0LjExMTkgMS42MDAxIDEzLjc1ODQgMS42MDAxWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNCAxMkwxMiA0TDQgMTJaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00IDEyTDEyIDQiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgo8L3N2Zz4K&logoColor=ffffff)](https://zread.ai/FlorianBruniaux/claude-code-ultimate-guide)

-**By [Florian BRUNIAUX](https://github.com/FlorianBruniaux)** | Founding Engineer [@Méthode Aristote](https://methode-aristote.fr) | [Connect on LinkedIn](https://www.linkedin.com/in/florian-bruniaux-43408b83/)
+```bash
+npm install -g @anthropic-ai/claude-code && claude
+```

 ---

-## Why This Guide Exists
+**Transparency note**: This guide reflects my personal experience after several months of daily Claude Code usage. I'm sharing what I've learned, not claiming expertise. The tool evolves constantly, and so does my understanding. [Feedback welcome](./CONTRIBUTING.md).

-**The Problem**: Most Claude Code resources are either scattered blog posts or dense reference manuals. You're left piecing together workflows, guessing at best practices, and discovering critical concepts too late.
+---

-**Our Solution**: A structured learning journey that takes you from installation to advanced orchestration in hours, not weeks—with ready-to-use examples you can deploy immediately.
+**Start here:**
+- [Cheat Sheet](./cheatsheet-en.md) — print this, start coding
+- [15-min Quick Start](./english-ultimate-claude-code-guide.md#1-quick-start-day-1) — first workflow
+- [Audit your setup](./examples/scripts/audit-scan.sh) — quick scan

-### What Makes This Different
+**Go deeper** (optional): [Learning paths by role](#-by-role-tailored-learning-paths) | [Full guide](./english-ultimate-claude-code-guide.md)
+
+---
+
+## Why This Guide?
+
+> Installation, agents, MCP servers, hooks, skills, and CI/CD integration—documented through several months of daily practice. A structured learning journey sharing what I've learned so far.
+
+**By [Florian BRUNIAUX](https://github.com/FlorianBruniaux)** | Founding Engineer [@Méthode Aristote](https://methode-aristote.fr) | [Connect on LinkedIn](https://www.linkedin.com/in/florian-bruniaux-43408b83/)
+
+**The Problem**: Most Claude Code resources are scattered blog posts or dense reference manuals. You're left piecing together workflows and discovering critical concepts too late.
+
+**This guide**: A structured learning journey with ready-to-use examples. Your mileage will vary—the goal is to save you the exploration time I've already spent.

 | Traditional Docs | This Guide |
 |------------------|------------|
 | Lists features | Teaches workflows |
-| Reference lookup | Progressive mastery |
+| Reference lookup | Progressive learning |
 | Theoretical concepts | Production-ready patterns |
 | "Figure it out" | "Here's exactly how" |

-**Your Investment**: 45 minutes to productivity. 2 hours to mastery. 8500+ lines organized by learning path, not alphabetically.
+**Reading time**: The Quick Start takes ~15 minutes. Full guide is ~3 hours but most people read by section as needed.

-> **If this guide saves you hours of trial-and-error, please star it.** Your support helps others discover this resource and motivates continued updates.
+> **If this guide saves you hours of trial-and-error, please star it.**

 ### Prerequisites

@ -37,43 +52,28 @@

 ---

-## Start Here: Choose Your Path
-
-### 🚀 Quick Start (15 minutes)
-
-**Goal**: Be productive immediately.
-
-```bash
-# Install (all platforms)
-npm install -g @anthropic-ai/claude-code
-
-# Start coding
-cd your-project
-claude
-```
-
-**Learn**: [Installation Guide](./english-ultimate-claude-code-guide.md#11-installation) → [First Workflow](./english-ultimate-claude-code-guide.md#12-first-workflow) → [Cheat Sheet](./cheatsheet-en.md)
+## Choose Your Path

 ### 🧭 Not Sure Where to Start?

-| If you... | Start here | Time |
-|-----------|------------|------|
-| Just installed Claude Code | [Quick Start](#-quick-start-15-minutes) | 15 min |
-| Want to understand core concepts | [Junior Path](#-by-role-tailored-learning-paths) | 45 min |
-| Already use AI coding tools | [Senior Path](#-by-role-tailored-learning-paths) | 40 min |
-| Need to configure a team setup | [Power User Path](#-by-role-tailored-learning-paths) | 2h |
-| Need to evaluate/approve adoption | [PM Path](#-by-role-tailored-learning-paths) | 20 min |
-| Choosing turnkey vs. autonomous approach | [Adoption Guide](./adoption-approaches.md) | 5 min |
-| Want to check your current setup | [Audit Your Setup](#-audit-your-setup) | 2 sec |
-| Want AI assistants to know Claude Code | [LLM Reference](#-llm-reference) | 1 curl |
-| Want personalized recommendations | [Deep Audit](#-deep-audit-personalized-recommendations) | 30 sec |
-| Want to test your knowledge | [Knowledge Quiz](#-knowledge-quiz) | 10 min |
-| Want a guided tour | [Personalized Onboarding](./personalized-onboarding-prompt.md) | ~15 min |
-| Having issues with Claude Code | [/diagnose command](./examples/commands/diagnose.md) | ~2 min |
+| If you... | Start here | Depth |
+|-----------|------------|-------|
+| Just installed Claude Code | [Quick Start](#-quick-start-15-minutes) | Essentials |
+| Want to understand core concepts | [Junior Path](#-by-role-tailored-learning-paths) | Foundation |
+| Already use AI coding tools | [Senior Path](#-by-role-tailored-learning-paths) | Intermediate |
+| Need to configure a team setup | [Power User Path](#-by-role-tailored-learning-paths) | Comprehensive |
+| Need to evaluate/approve adoption | [PM Path](#-by-role-tailored-learning-paths) | Overview |
+| Choosing turnkey vs. autonomous approach | [Adoption Guide](./adoption-approaches.md) | Quick read |
+| Want to check your current setup | [Audit Your Setup](#-audit-your-setup) | Quick scan |
+| Want AI assistants to know Claude Code | [LLM Reference](#-llm-reference) | Reference |
+| Want personalized recommendations | [Deep Audit](#-deep-audit-personalized-recommendations) | Quick scan |
+| Want to test your knowledge | [Knowledge Quiz](#-knowledge-quiz) | Interactive |
+| Want a guided tour | [Personalized Onboarding](./personalized-onboarding-prompt.md) | Interactive |
+| Having issues with Claude Code | [/diagnose command](./examples/commands/diagnose.md) | Quick fix |

 ### ⚡ Audit Your Setup

-Already have Claude Code installed? Scan your configuration in 2 seconds:
+Already have Claude Code installed? Quickly scan your configuration:

 ```bash
 curl -sL https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/examples/scripts/audit-scan.sh | bash
@ -99,7 +99,7 @@ curl -sL https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-

 Get a comprehensive, **context-aware** audit that analyzes your project's README, CLAUDE.md files, and business domain to provide tailored recommendations:

-> 🔒 **Privacy**: Everything runs locally on your machine. The script only downloads reference files from this repo—your project files (README, CLAUDE.md) are read locally and sent only to your own Claude CLI. Nothing is sent back to this repository or any third party.
+> 🔒 **Privacy**: The audit downloads reference files from this repo, then analyzes YOUR local files with your Claude CLI. Your project files are sent only to your Anthropic API endpoint, not to this repository or any third party.

 **Quick Version** (~10 sec):
 ```bash
@ -245,7 +245,7 @@ Weak Areas (< 75%):
 <tr>
 <td width="50%">

-**Junior Developer** (45 min to productivity)
+**Junior Developer** (Foundation path)

 1. [Quick Start](./english-ultimate-claude-code-guide.md#1-quick-start-day-1) — Install & first workflow
 2. [Essential Commands](./english-ultimate-claude-code-guide.md#13-essential-commands) — The 7 commands
@ -256,7 +256,7 @@ Weak Areas (< 75%):
 </td>
 <td width="50%">

-**Senior Developer** (40 min to mastery)
+**Senior Developer** (Intermediate path)

 1. [Core Concepts](./english-ultimate-claude-code-guide.md#2-core-concepts) — Mental model
 2. [Plan Mode](./english-ultimate-claude-code-guide.md#23-plan-mode) — Safe exploration
@ -269,7 +269,7 @@ Weak Areas (< 75%):
 <tr>
 <td width="50%">

-**Power User** (2 hours for full mastery)
+**Power User** (Comprehensive path)

 1. [Complete Guide](./english-ultimate-claude-code-guide.md) — End-to-end
 2. [MCP Servers](./english-ultimate-claude-code-guide.md#8-mcp-servers) — Extended capabilities
@ -280,7 +280,7 @@ Weak Areas (< 75%):
 </td>
 <td width="50%">

-**Product Manager** (20 min overview)
+**Product Manager** (Overview path)

 1. [What's Inside](#-complete-toolkit) — Scope
 2. [Golden Rules](#-golden-rules) — Key principles
@ -299,7 +299,7 @@ Weak Areas (< 75%):

 | File | Purpose | Time Investment |
 |------|---------|-----------------|
-| **[Ultimate Guide](./english-ultimate-claude-code-guide.md)** | 8500+ lines, 32K+ words, 10 sections | ~3 hours (or by section) |
+| **[Ultimate Guide](./english-ultimate-claude-code-guide.md)** | Complete reference, 10 sections | ~3 hours (or by section) |
 | **[Cheat Sheet](./cheatsheet-en.md)** | 1-page printable reference | 5 minutes |
 | **[LLM Reference](./claude-code-reference.yaml)** | Machine-optimized index (~2K tokens) | For Claude/AI assistants |
 | **[Setup Audit](./claude-setup-audit-prompt.md)** | Optimize your configuration | ~10 minutes |
@ -388,6 +388,8 @@ Master these five principles before diving deeper:
 | 70-90% | Orange | `/compact` now |
 | 90%+ | Red | `/clear` required |

+> *These thresholds are based on my experience. Your optimal workflow may differ.*
+
 ---

 ## 🌍 About This Guide
@ -401,7 +403,7 @@ Master these five principles before diving deeper:
 - Progressive complexity — start simple, master advanced at your pace
 - Practical workflows over theoretical concepts

-Think of this as **your mentor for Claude Code mastery** — not just documentation.
+Think of this as **a structured learning companion** — not just documentation.

 ### Origins & Transparency

--- a/adoption-approaches.md
+++ b/adoption-approaches.md
@ -1,17 +1,32 @@
 # Choosing Your Adoption Approach

-> **This guide is a springboard, not a destination.** Copy what serves you, ignore what doesn't.
+> **Disclaimer**: Claude Code is young (~1 year). Nobody has definitive answers yet — including this guide. These are starting points based on observed patterns, not proven best practices. Adapt heavily to your context.

 ---

-## Quick Decision
+## What We Don't Know Yet

-| Your Context | Recommended Approach |
+Before diving in, here's what remains genuinely uncertain:
+
+- **Optimal CLAUDE.md size** — Some teams thrive with 10 lines, others with 100. No clear winner.
+- **Team adoption patterns** — Whether top-down standardization beats organic adoption is unproven.
+- **Context management thresholds** — The 70%/90% numbers are heuristics, not science.
+- **ROI of advanced features** — MCP servers, hooks, agents — unclear when the setup cost pays off.
+
+If anyone tells you they've figured this out, they're ahead of the field or overconfident.
+
+---
+
+## Starting Points (Not Prescriptions)
+
+| Your Context | One Approach to Try |
 |--------------|---------------------|
-| Time constraint (<1 day to setup) | **Turnkey** — copy minimal template, verify, ship |
-| Solo developer wanting mastery | **Autonomous** — concepts first, config second |
-| 4-10 developers | **Hybrid** — shared core + personal extensions |
-| 10+ developers or high turnover | **Turnkey** — standardized setup + onboarding docs |
+| Limited setup time | **Turnkey** — minimal config, iterate based on friction |
+| Solo developer | **Autonomous** — learn concepts first, configure when needed |
+| Small team (4-10) | **Hybrid** — shared basics + room for personal preferences |
+| Larger team (10+) | **Turnkey + docs** — consistency matters more at scale |
+
+These are hypotheses. Your mileage will vary.

 ---

@ -20,22 +35,22 @@
 ```
 Starting Claude Code?
 │
-├─ Time constraint (<1 day)?
-│   └─ YES → Turnkey Quickstart (below)
+├─ Need to ship today?
+│   └─ YES → Turnkey Quickstart
 │   └─ NO ↓
 │
-├─ Need team consistency now?
-│   └─ YES → Turnkey + document 3 conventions
+├─ Team needs shared conventions?
+│   └─ YES → Turnkey + document what matters to you
 │   └─ NO ↓
 │
-├─ Unique workflow or project?
-│   └─ YES → Autonomous Learning Path (below)
-│   └─ NO → Turnkey, customize later
+├─ Want to understand before configuring?
+│   └─ YES → Autonomous Learning Path
+│   └─ NO → Turnkey, adjust as you go
 ```

 ---

-## Turnkey Quickstart (15 minutes)
+## Turnkey Quickstart

 ### Step 1: Create Minimal Config

@ -88,268 +103,264 @@ Claude should reference your stack and conventions automatically.

 ## Autonomous Learning Path

-### Phase 1: Mental Model (2 hours)
+If you prefer understanding before configuring, here's a progressive approach. No time estimates — speed depends on your familiarity with AI tools.

-**Goal**: Understand how Claude Code thinks before configuring.
+### Phase 1: Mental Model
+
+**Goal**: Understand how Claude Code operates before adding config.

 1. Read [Section 5: Mental Model](./english-ultimate-claude-code-guide.md) (line 1675)
-2. Key insight: Claude operates in a loop — prompt → plan → execute → verify
-3. **Hands-on**: Complete 3 simple tasks with zero config. Note what friction you experience.
+2. Core concept: Claude works in a loop — prompt → plan → execute → verify
+3. **Try it**: Complete a few real tasks with zero config. Notice where friction appears.

-### Phase 2: Context Management (1 hour)
+### Phase 2: Context Management

-**Goal**: Learn the constraint that shapes all Claude Code usage.
+**Goal**: Understand the main constraint of the tool.

 1. Read [Context Management](./english-ultimate-claude-code-guide.md) (line 944)
-2. Memorize the zones:
-   - Green (0-50%): work freely
-   - Yellow (50-70%): be selective
-   - Orange (70-90%): `/compact` now
-   - Red (90%+): `/clear` required
-3. **Hands-on**: Run `/status` after every 3 prompts for one day. Learn your pattern.
+2. The general idea (exact thresholds vary by use case):
+   - Low usage: work freely
+   - Medium usage: be more selective
+   - High usage: consider `/compact`
+   - Near limit: `/clear` to reset
+3. **Try it**: Check `/status` periodically. See how your usage patterns develop.

-### Phase 3: Memory Files (1 hour)
+### Phase 3: Memory Files

-**Goal**: Configure Claude to know your project.
+**Goal**: Give Claude project context.

 1. Read [Memory Files](./english-ultimate-claude-code-guide.md) (line 2218)
-2. Understand precedence: project `.claude/CLAUDE.md` > global `~/.claude/CLAUDE.md`
-3. **Hands-on**: Create minimal CLAUDE.md (see Turnkey Step 1), verify with test prompt.
+2. Precedence: project `.claude/CLAUDE.md` > global `~/.claude/CLAUDE.md`
+3. **Try it**: Create a minimal CLAUDE.md, test if Claude picks it up.

-### Phase 4: Extensions (as needed)
+### Phase 4: Extensions (when friction appears)

-Only proceed when you identify specific friction:
+Add complexity only when you hit real problems:

-| Friction | Solution | Reference |
-|----------|----------|-----------|
-| Same task repeated 5+ times | Create agent | [Agent Template](./english-ultimate-claude-code-guide.md) line 2793 |
-| Security concern after incident | Add hook | [Hook Templates](./english-ultimate-claude-code-guide.md) line 4172 |
-| Need external tool (DB, browser) | Configure MCP | [MCP Config](./english-ultimate-claude-code-guide.md) line 4771 |
-| AI repeats same mistake | Add specific rule | One line in CLAUDE.md, not ten |
+| Friction | Possible Solution | Reference |
+|----------|-------------------|-----------|
+| Repeating same task often | Consider an agent | [Agent Template](./english-ultimate-claude-code-guide.md) line 2793 |
+| Security concern | Consider a hook | [Hook Templates](./english-ultimate-claude-code-guide.md) line 4172 |
+| Need external tool access | Consider MCP | [MCP Config](./english-ultimate-claude-code-guide.md) line 4771 |
+| AI repeats same mistake | Add a specific rule | Start with one line, not ten |
+
+Whether these solutions are worth the setup cost depends on your context.

 ---

-## Adoption Checkpoints
+## Sanity Checks

-### Checkpoint 1: Base Setup (Day 1)
+These are signals that things are working, not rigid milestones.
+
+### Basic Setup Works

 ```bash
-claude --version          # Should be ≥2.x
-claude /status            # Shows project context, 0% usage
+claude --version          # Responds with version
+claude /status            # Shows context info
 claude /mcp               # Lists MCP servers (may be empty)
 ```

-**Pass**: All commands respond correctly.
-**Fail**: Installation issue — run `claude doctor`.
+If these fail: installation issue — try `claude doctor`.

-### Checkpoint 2: Config Active (Week 1)
+### Config Is Being Read

 **Test**: Ask Claude "What's the test command for this project?"

-**Pass**: Returns your configured command exactly.
-**Fail**: CLAUDE.md not loaded or wrong path.
+If it returns your configured command, CLAUDE.md is loaded. If not, check the path.

-### Checkpoint 3: Context Awareness (Week 2)
+### You're Managing Context

-**Metric**: You've used `/compact` when context exceeded 70%.
+**Signal**: You've noticed when context gets high and acted on it.

-**Pass**: You're managing context proactively.
-**Fail**: Either underusing Claude or ignoring `/status` signals.
+This develops naturally with use. If you never think about context, either you're not using Claude intensively, or you're ignoring signals that might matter.

-### Checkpoint 4: First Extension (Month 1)
+### Extensions Feel Useful (or not needed)

-**Metric**: Created one agent, command, or hook that you use weekly.
+**Signal**: You've either created something (agent, hook, command) that helps, or you haven't needed to.

-**Pass**: Tool matches your actual workflow.
-**Fail**: Either no repetitive patterns yet, or framework friction — revisit Phase 1.
+Both are fine. Extensions are optional — don't add them just to have them.

 ---

-## Anti-Patterns to Avoid
+## Common Pitfalls

-| Anti-Pattern | Symptoms | Solution |
-|--------------|----------|----------|
-| **"Copied 500-line CLAUDE.md"** | Rules get ignored, AI responses don't improve, overhead without benefit | Start with 10 lines, add only what you actually need |
-| **"Rebuilt everything from scratch"** | 2 weeks tweaking config instead of coding, reinventing existing solutions | Use templates as starting point, then adapt |
-| **"Team setup without documentation"** | Everyone does it differently, no shared conventions, onboarding chaos | Document 3-5 essential conventions, not more |
-| **"All features enabled Day 1"** | MCP servers unused, hooks never triggered, complexity without value | Enable features when you hit the problem they solve |
+These patterns seem problematic based on observations, though individual experiences vary.
+
+| Pattern | What happens | Alternative |
+|---------|--------------|-------------|
+| **Large copied config** | Rules get ignored, unclear what matters | Start small, add based on friction |
+| **Over-engineering setup** | Time spent configuring instead of coding | Use templates as starting point |
+| **No shared conventions** | Team members diverge, onboarding confusion | Document a few essentials |
+| **Everything enabled immediately** | Complexity without clear benefit | Enable features when you need them |
+
+These aren't universal truths — some teams thrive with large configs or full feature sets.

 ---

-## Team Size Guidelines
+## Team Size Considerations

-### Solo / 2-3 Developers
+These are starting points, not rules. Team dynamics matter more than headcount.

-**Config structure**:
+### Solo / Small Team (2-3)
+
+**Typical structure**:
 ```
-./CLAUDE.md                    # Minimal, committed
-~/.claude/CLAUDE.md            # Personal preferences (model, flags)
+./CLAUDE.md                    # Project basics, committed
+~/.claude/CLAUDE.md            # Personal preferences
 ```

-**Recommended setup**:
- 10-line project CLAUDE.md (stack, commands, 1-2 conventions)
- Personal: preferred model (`/model sonnet` vs `opus`), `--think` flag preferences
- No hooks unless you've had a security incident
- No agents unless workflow repeats 5+ times weekly
+**What might work**:
+- Short project CLAUDE.md with stack and main commands
+- Personal config for model preferences, flags
+- Extensions only if you find yourself repeating tasks often

-**Verification**: `claude /status` shows project name, no permission warnings.
+**Watch for**: Over-engineering. If you're spending more time on config than coding, step back.

-**Risk**: Over-engineering. If your CLAUDE.md exceeds 30 lines, you're probably solo-optimizing for imaginary team problems.
+### Medium Team (4-10)

-### 4-10 Developers
-
-**Config structure**:
+**Typical structure**:
 ```
 ./CLAUDE.md                    # Team conventions (committed)
-./.claude/settings.json        # Hooks for all (committed)
+./.claude/settings.json        # Shared hooks (committed)
 ~/.claude/CLAUDE.md            # Individual preferences (not committed)
 ```

-**Recommended setup**:
- Project CLAUDE.md: stack, commands, 3-5 conventions everyone follows
- One security hook: `dangerous-actions-blocker.sh` (see examples/)
- Personal extensions allowed: model preferences, custom agents, thinking flags
+**What might work**:
+- Shared conventions that the team actually follows
+- Security hooks if relevant to your context
+- Room for personal preferences

-**Split decisions**:
-| In repo (team) | In ~/.claude (personal) |
-|----------------|-------------------------|
+**One way to split things**:
+
+| Shared (repo) | Personal (~/.claude) |
+|---------------|----------------------|
 | Test/lint commands | Model preferences |
-| Error handling patterns | Custom agents for your workflow |
-| Commit message format | Thinking flag defaults |
+| Project conventions | Custom agents |
+| Commit format | Flag defaults |

-**Verification**: New team member runs `claude "What conventions should I follow?"` — answer should match team docs.
+**Watch for**: Conventions that exist on paper but aren't followed.

-### 10+ Developers / High Turnover
+### Larger Team (10+)

-**Config structure**:
+**Typical structure**:
 ```
-./CLAUDE.md                    # Strict, documented, committed
-./.claude/settings.json        # All hooks required, committed
-./.claude/agents/              # Approved agents only, committed
-./.claude/commands/            # Standardized commands, committed
-~/.claude/CLAUDE.md            # Minimal personal overrides
+./CLAUDE.md                    # Documented, committed
+./.claude/settings.json        # Standard hooks, committed
+./.claude/agents/              # Shared agents, committed
+~/.claude/CLAUDE.md            # Personal additions
 ```

-**Recommended setup**:
- Documented CLAUDE.md with rationale for each rule
- Security hooks: mandatory, no exceptions
- Approved agents list: new agents require review
- Onboarding: 30-minute session covering context management (`/status`, `/compact`)
+**What might work**:
+- Documented conventions with rationale
+- Standardized hooks across the team
+- Onboarding that covers basics like `/status`

-**Governance**:
-```bash
-# Monthly audit command
-claude "Review .claude/ config against our team conventions doc"
-```
-
-**Verification**: Run `/diagnose` (if available) or manual audit quarterly.
-
-**Risk**: Config drift. Without governance, 10 developers = 10 different setups in 3 months.
+**Watch for**: Config drift. Without some coordination, setups diverge over time. Whether that matters depends on your team.

 ---

-## Scenario Decisions
+## Common Situations

-### "I'm a CTO evaluating Claude Code"
+### "I'm evaluating Claude Code for my team"

-**Fast evaluation path (2 hours)**:
+**Quick test approach**:
 1. Install: `npm i -g @anthropic-ai/claude-code`
-2. Run in existing project: `claude`
-3. Test with real task: `claude "Analyze this codebase architecture"`
-4. Use Plan Mode for safety: `Shift+Tab` twice before risky operations
-5. Check cost: `/status` shows token usage
+2. Run in an existing project: `claude`
+3. Try a real task: `claude "Analyze this codebase architecture"`
+4. Check `/status` to understand token usage

-**Evaluation criteria**:
- Does Claude understand your stack without config? (baseline)
- Does it improve with minimal CLAUDE.md? (config value)
- Can your team adopt context management? (`/compact` discipline)
+**Questions to answer**:
+- Does Claude understand your stack without config?
+- Does a minimal CLAUDE.md improve results?
+- Can your team learn context management basics?

-**Skip for now**: MCP servers, hooks, agents — evaluate core workflow first.
+Consider skipping advanced features (MCP, hooks, agents) during initial evaluation.

 ### "My team disagrees on configuration"

-**Resolution hierarchy**:
+**One way to think about it**:

-| Layer | Who decides | What goes there |
-|-------|-------------|-----------------|
-| Repo CLAUDE.md | Tech lead | Stack, test commands, 3 conventions |
-| Repo hooks | Security team | Dangerous action blockers |
-| Personal ~/.claude | Individual | Model preferences, custom agents |
+| Layer | Typical owner | Typical content |
+|-------|---------------|-----------------|
+| Repo CLAUDE.md | Team decision | Stack, commands, core conventions |
+| Repo hooks | Security-minded team members | Guardrails if needed |
+| Personal ~/.claude | Individual | Preferences, personal agents |

-**Conflict resolution**:
- Security hooks: non-negotiable, everyone uses
- Conventions: majority vote, documented in CLAUDE.md
- Preferences: personal, never in repo config
+How you resolve conflicts depends on your team culture. Some teams vote, some defer to tech leads, some let individuals diverge.

 ### "Claude keeps making the same mistake"

-**Don't**: Add 50 lines of rules.
+**Tempting**: Add many rules to prevent it.
+
+**Often better**: Add one specific rule, test if it works, iterate.

-**Do**: Add exactly one rule:
 ```markdown
-## Anti-Pattern: [specific issue]
-When implementing [X], NEVER [specific mistake].
-Instead: [correct approach with 1-line example]
+## [Specific issue]
+When doing [X], avoid [specific mistake].
+Instead: [correct approach]
 ```

-**Verify**: Run the exact prompt that triggered the mistake. Fixed? Keep rule. Not fixed? Rule is too vague — make it more specific.
+If the rule doesn't help, it might be too vague. Make it more specific or reconsider if rules are the right solution.

-### "I inherited a 300-line CLAUDE.md"
+### "I inherited a large CLAUDE.md"

-**Audit process**:
-1. Ask Claude: `"Summarize the key conventions from CLAUDE.md"`
-2. Compare summary to what team actually follows
-3. Delete rules Claude doesn't reference or team doesn't follow
-4. Target: under 50 lines with clear purpose for each section
+**One approach**:
+1. Ask Claude to summarize what the CLAUDE.md says
+2. Compare to what the team actually does
+3. Remove rules that aren't followed or referenced
+4. Keep what's genuinely useful

-**Quick test**: If you can't explain why a rule exists in 10 words, delete it.
+**Heuristic**: If you can't explain why a rule exists, consider removing it.

-### "When should I upgrade from Turnkey to custom?"
+### "When should I add more complexity?"

-**Triggers for customization**:
+There's no universal answer. Some signals that might suggest it:

-| Signal | Action |
-|--------|--------|
-| Same prompt copy-pasted 5+ times | Create command |
-| Security incident | Add hook immediately |
-| External tool needed weekly | Configure MCP server |
-| Team asks same questions | Add to CLAUDE.md FAQ section |
-| Context hits 90% regularly | Review what's being loaded, use `--add-dir` selectively |
+| Signal | Possible response |
+|--------|-------------------|
+| Repeating the same prompt often | Consider a command |
+| Security concern | Consider a hook |
+| Need external tool access | Consider MCP |
+| Same questions from team | Consider documentation |
+
+But also: maybe you don't need more complexity. Simple setups work for many teams.

 ---

 ## Quick Reference

-### Commands You'll Use Daily
+### Useful Commands

-| Command | When | Why |
-|---------|------|-----|
-| `/status` | Every 5-10 prompts | Check context percentage |
-| `/compact` | Context >70% | Compress before degradation |
-| `/clear` | Context >90% or confusion | Hard reset |
-| `/plan` | Before risky changes | Safe exploration mode |
-| `/model` | Switching task complexity | sonnet (normal), opus (hard) |
+| Command    | Purpose                          |
+|------------|----------------------------------|
+| `/status`  | Check context usage              |
+| `/compact` | Compress context when it's high  |
+| `/clear`   | Reset context entirely           |
+| `/plan`    | Enter planning mode              |
+| `/model`   | Switch between models            |

-### Cost-Conscious Adoption
+How often you use these depends on your workflow.

-| Model | Cost | Use for |
-|-------|------|---------|
-| Haiku | $ | Simple reviews, formatting |
-| Sonnet | $$ | Daily development (default) |
-| Opus | $$$ | Architecture, complex debugging |
+### Model Costs (Relative)

-**Tip**: Start with Sonnet. Upgrade to Opus only when Sonnet demonstrably fails.
+| Model  | Cost | Typical use cases              |
+|--------|------|--------------------------------|
+| Haiku  | $    | Simple tasks, quick responses  |
+| Sonnet | $$   | General development            |
+| Opus   | $$$  | Complex analysis, architecture |
+
+Most people start with Sonnet. Adjust based on your experience.

 ---

 ## Related Resources

- [Personalized Onboarding](./personalized-onboarding-prompt.md) — Interactive setup for your context
- [Setup Audit](./claude-setup-audit-prompt.md) — Diagnose existing configuration issues
- [Examples Library](./examples/README.md) — Templates to copy selectively
- [Main Guide](./english-ultimate-claude-code-guide.md) — Full reference (use line numbers from this doc)
- [Reference YAML](./claude-code-reference.yaml) — Condensed lookup for quick answers
+- [Personalized Onboarding](./personalized-onboarding-prompt.md) — Interactive setup
+- [Setup Audit](./claude-setup-audit-prompt.md) — Diagnose configuration issues
+- [Examples Library](./examples/README.md) — Templates to adapt
+- [Main Guide](./english-ultimate-claude-code-guide.md) — Full reference
+- [Reference YAML](./claude-code-reference.yaml) — Condensed lookup

 ---

-*Addresses community feedback on adoption approaches. Contributions: [CONTRIBUTING.md](./CONTRIBUTING.md)*
+*This guide reflects current observations, not proven best practices. The field is young — adapt heavily to your context. Feedback welcome: [CONTRIBUTING.md](./CONTRIBUTING.md)*
--- a/cheatsheet-en.md
+++ b/cheatsheet-en.md
@ -6,7 +6,7 @@

 **Written with**: Claude (Anthropic)

-**Version**: 3.0.5 | **Last Updated**: January 2026
+**Version**: 3.0.6 | **Last Updated**: January 2026

 ---

@ -378,4 +378,4 @@ where.exe claude; claude doctor; claude mcp list

 **Author**: Florian BRUNIAUX | [@Méthode Aristote](https://methode-aristote.fr) | Written with Claude

-*Last updated: January 2026 | Version 3.0.5*
+*Last updated: January 2026 | Version 3.0.6*
--- a/english-ultimate-claude-code-guide.md
+++ b/english-ultimate-claude-code-guide.md
@ -10,28 +10,25 @@

 **Last updated**: January 2026

-**Version**: 3.0.4
+**Version**: 3.0.6

 ---

-<div align="center">
+## Before You Start

-### 📊 Guide Status Overview
+**This guide is not official Anthropic documentation.** It's a community resource based on my exploration of Claude Code over several months.

-| Section | Status | Coverage | Last Updated |
-|---------|--------|----------|--------------|
-| **Quick Start & Installation** | ✅ Complete | 100% | Jan 2026 |
-| **Core Concepts** | ✅ Complete | 100% | Jan 2026 |
-| **Memory & Settings** | ✅ Complete | 100% | Jan 2026 |
-| **Agents & Skills** | ✅ Complete | 100% | Jan 2026 |
-| **Commands & Hooks** | ✅ Complete | 100% | Jan 2026 |
-| **MCP Integration** | ✅ Complete | 100% | Jan 2026 |
-| **Advanced Patterns** | ✅ Complete | 100% | Jan 2026 |
-| **Reference & Troubleshooting** | ✅ Complete | 100% | Jan 2026 |
+**What you'll find:**
+- Patterns that have worked for me
+- Observations that may not generalize to your workflow
+- Time estimates and percentages that are rough approximations, not measurements

-**Legend**: ✅ Complete | 🔄 In Progress | 📝 Planned | ⚠️ Needs Update
+**What you won't find:**
+- Definitive answers (the tool is too new)
+- Benchmarked performance claims
+- Guarantees that any technique will work for you

-</div>
+**Use critically. Experiment. Share what works for you.**

 ---

@ -63,6 +60,8 @@ Describe → Claude Analyzes → Review Diff → Accept/Reject → Verify
 | 70-90% | `/compact` now |
 | 90%+ | `/clear` required |

+*These thresholds are based on my experience. Your optimal workflow may differ depending on task complexity and working style.*
+
 ### Memory Hierarchy
 ```
 ~/.claude/CLAUDE.md       → Global (all projects)
@ -314,7 +313,7 @@ Claude will create a commit with an appropriate message.

 ## 1.3 Essential Commands

-These 7 commands cover 90% of daily usage:
+These 7 commands are the ones I use most frequently:

 | Command | Action | When to Use |
 |---------|--------|-------------|
@ -865,11 +864,11 @@ Keep Copilot/Cursor for:
 - [ ] You prefer Claude Code's explanations over inline docs
 - [ ] You've integrated Claude Code into your daily workflow

-**Productivity indicators:**
+**Subjective productivity indicators** (your experience may vary):

- Completing features 20-30% faster
- Spending less time debugging
- Higher code quality (caught by Claude reviews)
+- Feeling more productive on complex tasks
+- Spending less time on boilerplate and debugging
+- Catching more issues through Claude reviews
 - Better understanding of unfamiliar code

 ---
@ -1160,7 +1159,7 @@ Cost per message increases as context grows

 # With /compact at 70%
 Context: 10% → 30% → 50% → 70% → [/compact] → 30% → 50%
-Saves 30-40% on subsequent messages
+Frees significant context space for subsequent messages
 ```

 **Strategy 3: Choose the right model**
@ -1282,15 +1281,7 @@ Check your Anthropic Console for detailed usage:

 #### Cost vs. Value

-**Don't over-optimize!**
-
-Spending $0.50 to save 30 minutes is a **60x ROI** if your time is worth $30/hour.
-
-| Time Saved | Cost | Your Hourly Rate | ROI |
-|------------|------|------------------|-----|
-| 30 min | $0.50 | $30/hr | 30x |
-| 1 hour | $1.00 | $50/hr | 50x |
-| 2 hours | $2.00 | $75/hr | 75x |
+**Perspective on costs**: If Claude Code saves you meaningful time on a task, the API cost is usually negligible compared to your hourly rate. Don't over-optimize for token costs at the expense of productivity.

 **When to optimize**:
 - ✅ You're on a tight budget (student, hobbyist)
@ -3013,7 +3004,7 @@ tools: Read, Bash, Grep, Glob
 You are a systematic debugger who:
 - Investigates root causes, not symptoms
 - Uses evidence-based debugging
- Never guesses - always verifies
+- Aims to verify rather than assume (but always review output—LLMs can make mistakes)

 ## Methodology

@ -3268,7 +3259,7 @@ Evaluate this interface with perspectives:
 │                    └──────────────┘                         │
 │                                                             │
 │   Cost: 2-2.5x cheaper than Opus everywhere                 │
-│   Quality: Equivalent for 90% of tasks                      │
+│   Quality: Equivalent for most common tasks                 │
 └─────────────────────────────────────────────────────────────┘
 ```

@ -3300,7 +3291,7 @@ Scenario: Refactoring 100 files
 - Cost: ~$5-15
 - Time: 1h (parallelized)

-Savings: 80-90%
+Estimated savings: significant (varies by project)
 ```

 ---
@ -7680,18 +7671,9 @@ Smart escalation (Haiku → Sonnet for 10% of PRs):
 - Invest in good prompts and memory files (reduce iterations)
 - Automate with agents (consistent, efficient)

-**ROI calculation:**
+**Perspective on ROI:**

-```
-Your hourly rate: $50/hour
-Claude Sonnet request: $0.10
-
-Time saved per request: 15 minutes (0.25 hours)
-Value of time saved: $50 × 0.25 = $12.50
-ROI: ($12.50 - $0.10) / $0.10 = 12,400% ROI
-
-Conclusion: Focus on productivity, not penny-pinching.
-```
+Time savings from effective Claude Code usage typically far outweigh API costs for most development tasks. Rather than calculating precise ROI (which depends heavily on your specific context, hourly rate, and task complexity), focus on whether the tool is genuinely helping you ship faster.

 **When to optimize aggressively:**
 - High-volume operations (>1000 requests/day)
@ -9050,4 +9032,4 @@ Thumbs.db

 **Contributions**: Issues and PRs welcome.

-**Last updated**: January 2026 | **Version**: 3.0.4
+**Last updated**: January 2026 | **Version**: 3.0.6