release: version 3.13.0 - Boris Cherny mental models integration
Major additions: - CLAUDE.md as Compounding Memory philosophy (never correct Claude twice) - Plan-First Discipline methodology (foundational pattern) - Verification Loops architectural pattern (8 domains) - Advanced Worktree Tooling section (3 independent tools validated) - Anthropic governance resources (Constitution, Petri v2) - Search tools mastery workflow (grep, grepai, ast-grep, Serena) Updates: - Boris Cherny case study enhanced with direct quotes - Templates count: 83 → 86 - Reference YAML: new architecture diagram, search tools comparison Resource evaluations: - Boris Cowork video (3/5 - pertinent) - Wooldridge productivity stack (3/5 - remote-first workflows) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
6ed7e92e64
commit
6f6cd90bc1
7 changed files with 187 additions and 15 deletions
36
CHANGELOG.md
36
CHANGELOG.md
|
|
@ -6,8 +6,38 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
|
|||
|
||||
## [Unreleased]
|
||||
|
||||
## [3.13.0] - 2026-01-26
|
||||
|
||||
### Added
|
||||
|
||||
- **Boris Cherny mental models integration** (from YouTube interview analysis)
|
||||
- **CLAUDE.md as Compounding Memory** (`guide/ultimate-guide.md:3254`)
|
||||
- New philosophy section: "You should never have to correct Claude twice for the same mistake"
|
||||
- 4-step cycle: error → rule → read → never repeated
|
||||
- Compounding effect visualization (5 → 20 → 50 rules over time)
|
||||
- Boris's practical example: 2.5K tokens grown over months
|
||||
- Anti-pattern warning: no preemptive documentation
|
||||
- Mental model shift: configuration file → organizational learning system
|
||||
- **Plan-First Discipline** (`guide/methodologies.md:61`)
|
||||
- New "Foundational Discipline" section (between Tier 1 and Tier 2)
|
||||
- Core principle: "Once the plan is good, the code is good" (Boris quote)
|
||||
- Decision table: when to plan first vs when to skip
|
||||
- 3-phase workflow: exploration → validation → execution
|
||||
- Benefits quantified vs "just start coding"
|
||||
- CLAUDE.md integration example for team planning policy
|
||||
- **Verification Loops architectural pattern** (`guide/methodologies.md:214`)
|
||||
- Extended beyond TDD to general architectural principle
|
||||
- 8 verification domains table (frontend, backend, types, style, performance, accessibility, security, UX)
|
||||
- Boris quote: "An agent that can 'see' what it has done produces better results"
|
||||
- Implementation patterns: hooks, browser extensions, test watchers, CI/CD gates
|
||||
- Anti-pattern: blind iteration without feedback mechanism
|
||||
- **Boris direct quotes in case study** (`guide/ultimate-guide.md:10743`)
|
||||
- 4 key insights: multi-clauding, CLAUDE.md compounding, plan-first, verification loops
|
||||
- Opus 4.5 ROI explanation: higher per-token cost but fewer corrections = net savings
|
||||
- Supervision model description: "tending to multiple agents" vs sequential execution
|
||||
- YouTube source citation added alongside InfoQ article
|
||||
- Resource evaluation saved in `claudedocs/resource-evaluations/boris-cowork-video-eval.md` (score: 3/5 - pertinent, amélioration modérée)
|
||||
- Source: [YouTube - I got a private lesson on Claude Cowork & Claude Code](https://www.youtube.com/watch?v=DW4a1Cm8nG4)
|
||||
- **Advanced Worktree Tooling section** (`guide/ultimate-guide.md:10748`)
|
||||
- New section "Advanced Tooling for Worktree Management (Optional)" in §9.17 Multi-Instance Workflows
|
||||
- Pattern validation: 3 independent teams created worktree wrappers (incident.io, GitHub #1052, Worktrunk)
|
||||
|
|
@ -48,6 +78,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
|
|||
- Golden rule banner: "LLM Thinks → MCP Controls → Tools Execute → Data Locked"
|
||||
- **machine-readable/reference.yaml**: Added `architecture_mcp_visual` (SVG diagram reference)
|
||||
|
||||
### Changed
|
||||
|
||||
- **README.md**: Updated templates count from 83 to 86 (badge and description text)
|
||||
- Reflects addition of 3 new evaluation documents in `claudedocs/resource-evaluations/`
|
||||
- Actual template count: 86 files in `examples/` directory
|
||||
|
||||
## [3.12.1] - 2026-01-25
|
||||
|
||||
### Added
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@
|
|||
|
||||
<p align="center">
|
||||
<a href="https://github.com/FlorianBruniaux/claude-code-ultimate-guide/stargazers"><img src="https://img.shields.io/github/stars/FlorianBruniaux/claude-code-ultimate-guide?style=for-the-badge" alt="Stars"/></a>
|
||||
<a href="./examples/"><img src="https://img.shields.io/badge/Templates-83-green?style=for-the-badge" alt="Templates"/></a>
|
||||
<a href="./examples/"><img src="https://img.shields.io/badge/Templates-86-green?style=for-the-badge" alt="Templates"/></a>
|
||||
<a href="./quiz/"><img src="https://img.shields.io/badge/Quiz-227_questions-orange?style=for-the-badge" alt="Quiz"/></a>
|
||||
</p>
|
||||
|
||||
|
|
@ -15,7 +15,7 @@
|
|||
<a href="https://zread.ai/FlorianBruniaux/claude-code-ultimate-guide"><img src="https://img.shields.io/badge/Ask_Zread-_.svg?style=flat&color=00b0aa&labelColor=000000&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTQuOTYxNTYgMS42MDAxSDIuMjQxNTZDMS44ODgxIDEuNjAwMSAxLjYwMTU2IDEuODg2NjQgMS42MDE1NiAyLjI0MDFWNC45NjAxQzEuNjAxNTYgNS4zMTM1NiAxLjg4ODEgNS42MDAxIDIuMjQxNTYgNS42MDAxSDQuOTYxNTZDNS4zMTUwMiA1LjYwMDEgNS42MDE1NiA1LjMxMzU2IDUuNjAxNTYgNC45NjAxVjIuMjQwMUM1LjYwMTU2IDEuODg2NjQgNS4zMTUwMiAxLjYwMDEgNC45NjxNTYgMS42MDAxWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNC45NjE1NiAxMC4zOTk5SDIuMjQxNTZDMS44ODgxIDEwLjM5OTkgMS42MDE1NiAxMC42ODY0IDEuNjAxNTYgMTEuMDM5OVYxMy43NTk5QzEuNjAxNTYgMTQuMTEzNCAxLjg4ODEgMTQuMzk5OSAyLjI0MTU2IDE0LjM5OTlINC45NjE1NkM1LjMxNTAyIDE0LjM5OTkgNS42MDE1NiAxNC4xMTM0IDUuNjAxNTYgMTMuNzU5OVYxMS4wMzk5QzUuNjAxNTYgMTAuNjg2NCA1LjMxNTAyIDEwLjM5OTkgNC45NjE1NiAxMC4zOTk5WiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNMTMuNzU4NCAxLjYwMDFIMTEuMDM4NEMxMC42ODUgMS42MDAxIDEwLjM5ODQgMS44ODY2NCAxMC4zOTg0IDIuMjQwMVY0Ljk2MDFDMTAuMzk4NCA1LjMxMzU2IDEwLjY4NSA1LjYwMDEgMTEuMDM4NCA1LjYwMDFIMTMuNzU4NEMxNC4xMTE5IDUuNjAwMSAxNC4zOTg0IDUuMzEzNTYgMTQuMzk4NCA0Ljk2MDFWMi4yNDAxQzE0LjM5ODQgMS44ODY2NCAxNC4xMTE5IDEuNjAwMSAxMy43NTg0IDEuNjAwMVoiIGZpbGw9IiNmZmYiLz4KPHBhdGggZD0iTTQgMTJMMTIgNEw0IDEyWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNCAxMkwxMiA0IiBzdHJva2U9IiNmZmYiIHN0cm9rZS13aWR0aD0iMS41IiBzdHJva2UtbGluZWNhcD0icm91bmQiLz4KPC9zdmc%2BCg%3D%3D&logoColor=ffffff" alt="Ask Zread"/></a>
|
||||
</p>
|
||||
|
||||
> Complete guide to Claude Code with 83 production-ready templates
|
||||
> Complete guide to Claude Code with 86 production-ready templates
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -64,7 +64,7 @@ Save as `CLAUDE.md` in your project root. Claude reads it automatically.
|
|||
|
||||
**The problem**: Awesome-lists give links, not learning paths. Official docs are dense. Tutorials get outdated in weeks.
|
||||
|
||||
**This guide**: Structured learning path with 82 copy-paste templates, from first install to advanced workflows.
|
||||
**This guide**: Structured learning path with 86 copy-paste templates, from first install to advanced workflows.
|
||||
|
||||
**Reading time**: Quick Start ~15 min. Full guide ~3 hours (most read by section).
|
||||
|
||||
|
|
@ -449,7 +449,7 @@ Licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).
|
|||
|
||||
---
|
||||
|
||||
*Version 3.12.1 | January 2026 | Crafted with Claude*
|
||||
*Version 3.13.0 | January 2026 | Crafted with Claude*
|
||||
|
||||
<!-- SEO Keywords -->
|
||||
<!-- claude code, claude code tutorial, anthropic cli, ai coding assistant, claude code mcp,
|
||||
|
|
|
|||
2
VERSION
2
VERSION
|
|
@ -1 +1 @@
|
|||
3.12.1
|
||||
3.13.0
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@
|
|||
|
||||
**Written with**: Claude (Anthropic)
|
||||
|
||||
**Version**: 3.12.1 | **Last Updated**: January 2026
|
||||
**Version**: 3.13.0 | **Last Updated**: January 2026
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -424,4 +424,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.12.1*
|
||||
*Last updated: January 2026 | Version 3.13.0*
|
||||
|
|
|
|||
|
|
@ -58,6 +58,72 @@ Organized in a 6-tier pyramid from strategic orchestration down to optimization
|
|||
|
||||
---
|
||||
|
||||
### Foundational Discipline: Plan-First Workflow
|
||||
|
||||
> **"Once the plan is good, the code is good."**
|
||||
> — Boris Cherny, creator of Claude Code
|
||||
|
||||
**Not just a feature (`/plan` command) — a systematic discipline.**
|
||||
|
||||
**The Mental Model**:
|
||||
|
||||
Planning isn't optional for complex tasks. It's the difference between:
|
||||
- ❌ 8 iterations of "try → fix → retry → fix again"
|
||||
- ✅ 1 iteration of "plan → validate → execute cleanly"
|
||||
|
||||
**When to plan first**:
|
||||
|
||||
| Task Complexity | Plan First? | Why |
|
||||
|----------------|-------------|-----|
|
||||
| >3 files modified | ✅ Yes | Cross-file dependencies need architecture |
|
||||
| >50 lines changed | ✅ Yes | Enough complexity for mistakes |
|
||||
| Architectural changes | ✅ Yes | Impact analysis required |
|
||||
| Unfamiliar codebase | ✅ Yes | Need exploration before action |
|
||||
| Typo/obvious fix | ❌ No | Planning overhead > task time |
|
||||
| Single-line change | ❌ No | Just do it |
|
||||
|
||||
**How plan-first works**:
|
||||
|
||||
1. **Exploration phase** (`/plan` mode):
|
||||
- Claude reads files, explores architecture
|
||||
- No edits allowed → forces thinking before action
|
||||
- Proposes approach with trade-offs
|
||||
|
||||
2. **Validation phase** (you review):
|
||||
- Plan exposes assumptions and gaps
|
||||
- Easier to correct direction now vs after 100 lines written
|
||||
- Plan becomes contract for execution
|
||||
|
||||
3. **Execution phase** (`/execute`):
|
||||
- Plan → code becomes mechanical translation
|
||||
- Fewer surprises, cleaner implementation
|
||||
- Faster overall despite "slower" start
|
||||
|
||||
**Boris Cherny workflow**:
|
||||
|
||||
> "I run many sessions, start in plan mode, then switch into execution once the plan looks right. The signature upgrade is verification—giving Claude a way to test and confirm its own output."
|
||||
|
||||
**Benefits over "just start coding"**:
|
||||
|
||||
- **Fewer correction iterations**: Plan catches issues before they become code
|
||||
- **Better architecture**: Forced to think about structure first
|
||||
- **Clearer communication**: Plan is shared understanding with team/Claude
|
||||
- **Reduced cost**: One clean iteration < multiple messy iterations (even if plan phase costs tokens)
|
||||
|
||||
**Integration with CLAUDE.md**:
|
||||
|
||||
Document your team's plan-first triggers:
|
||||
```markdown
|
||||
## Planning Policy
|
||||
- ALWAYS plan first: API changes, database migrations, new features
|
||||
- OPTIONAL planning: Bug fixes <10 lines, test additions
|
||||
- NEVER skip: Changes affecting >2 modules
|
||||
```
|
||||
|
||||
**See also**: [Plan Mode documentation](./ultimate-guide.md#23-plan-mode) for `/plan` command usage.
|
||||
|
||||
---
|
||||
|
||||
### Tier 2: Specification & Architecture
|
||||
|
||||
| Name | What | Best For | Claude Fit |
|
||||
|
|
@ -145,16 +211,44 @@ Strict iteration: 2 weeks max per feature.
|
|||
|
||||
With Claude: Be explicit. "Write FAILING tests that don't exist yet."
|
||||
|
||||
> **Verification Loops** — A formalized pattern for autonomous iteration:
|
||||
> **Verification Loops** — A formalized pattern for autonomous iteration (broader than TDD):
|
||||
>
|
||||
> Use testing as termination condition:
|
||||
> **Core principle**: Give Claude a mechanism to verify its own output.
|
||||
>
|
||||
> ```
|
||||
> Code generated → Verification tool → Feedback loop → Improvement
|
||||
> ```
|
||||
>
|
||||
> **Why it works** (Boris Cherny): *"An agent that can 'see' what it has done produces better results."*
|
||||
>
|
||||
> **Verification mechanisms by domain**:
|
||||
>
|
||||
> | Domain | Verification Tool | What Claude "Sees" |
|
||||
> |--------|-------------------|-------------------|
|
||||
> | **Frontend** | Browser preview (live reload) | Visual rendering, layout, interactions |
|
||||
> | **Backend** | Tests (unit/integration) | Pass/fail status, error messages |
|
||||
> | **Types** | TypeScript compiler | Type errors, incompatibilities |
|
||||
> | **Style** | Linters (ESLint, Prettier) | Style violations, formatting issues |
|
||||
> | **Performance** | Profilers, benchmarks | Execution time, memory usage |
|
||||
> | **Accessibility** | axe-core, screen readers | WCAG violations, navigation issues |
|
||||
> | **Security** | Static analyzers (Semgrep) | Vulnerability patterns |
|
||||
> | **UX** | User testing, recordings | Usability problems, confusion points |
|
||||
>
|
||||
> **TDD as canonical example**:
|
||||
> 1. Claude writes tests for the feature
|
||||
> 2. Claude iterates code until tests pass
|
||||
> 3. Continue until explicit completion criteria met
|
||||
>
|
||||
> **Official guidance**: *"Tell Claude to keep going until all tests pass. It will usually take a few iterations."* — [Anthropic Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)
|
||||
>
|
||||
> Implementation: Can be enforced via Stop hooks, multi-Claude verification, or explicit "DONE" markers in prompts.
|
||||
> **Implementation patterns**:
|
||||
> - **Hooks**: PostToolUse hook runs verification after each edit
|
||||
> - **Browser extension**: Claude in Chrome sees rendered output
|
||||
> - **Test watchers**: Jest/Vitest watch mode provides instant feedback
|
||||
> - **CI/CD gates**: GitHub Actions runs full validation suite
|
||||
> - **Multi-Claude verification**: One Claude codes, another reviews
|
||||
>
|
||||
> **Anti-pattern**: Blind iteration without feedback. Without verification mechanism, Claude can't converge toward correct solution—it guesses.
|
||||
|
||||
**Eval-Driven Development** — TDD for LLMs. Test agent behaviors via evals:
|
||||
- Code-based: `output == golden_answer`
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@
|
|||
|
||||
**Last updated**: January 2026
|
||||
|
||||
**Version**: 3.12.1
|
||||
**Version**: 3.13.0
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -3253,6 +3253,34 @@ Brief one-sentence description of what this project does.
|
|||
|
||||
**Rule of thumb**: If Claude makes a mistake twice because of missing context, add that context to CLAUDE.md. Don't preemptively document everything.
|
||||
|
||||
### CLAUDE.md as Compounding Memory
|
||||
|
||||
> **"You should never have to correct Claude twice for the same mistake."**
|
||||
> — Boris Cherny, creator of Claude Code
|
||||
|
||||
**The Mental Model**: CLAUDE.md isn't just a configuration file—it's an **organizational learning system** where every error compounds into permanent team knowledge.
|
||||
|
||||
**How it works**:
|
||||
1. **Claude makes an error** (e.g., uses `npm` instead of `pnpm`)
|
||||
2. **You add a rule** to CLAUDE.md: `"Always use pnpm, never npm"`
|
||||
3. **Claude reads CLAUDE.md** at session start → never repeats error
|
||||
4. **Knowledge compounds** over time as team catches and documents edge cases
|
||||
|
||||
**The compounding effect**:
|
||||
```
|
||||
Week 1: 5 rules → 5 mistakes prevented
|
||||
Week 4: 20 rules → 20 mistakes prevented
|
||||
Month 3: 50 rules → 50 mistakes prevented + faster onboarding
|
||||
```
|
||||
|
||||
**Practical example** (Boris Cherny's team):
|
||||
- CLAUDE.md grew to **2.5K tokens** (≈500 words) over months
|
||||
- Captured project-specific conventions, architectural decisions, and "gotchas"
|
||||
- New team members benefit from accumulated tribal knowledge instantly
|
||||
- Claude becomes increasingly aligned with team standards over time
|
||||
|
||||
**Anti-pattern**: Preemptively documenting everything. Instead, treat CLAUDE.md as a **living document** that grows through actual mistakes caught during development.
|
||||
|
||||
**Size guideline**: Keep CLAUDE.md files between **4-8KB total** (all levels combined). Practitioner studies show that context files exceeding 16K tokens degrade model coherence. Include architecture overviews, key conventions, and critical constraints—exclude full API references or extensive code examples (link to them instead).
|
||||
|
||||
### Level 1: Global (~/.claude/CLAUDE.md)
|
||||
|
|
@ -10714,7 +10742,21 @@ Boris Cherny, creator of Claude Code, shared his workflow orchestrating 5-15 Cla
|
|||
|
||||
**Critical context**: Boris is the creator of Claude Code, working with perfect architecture, Anthropic resources, and ideal conditions. **This is not representative of average teams.**
|
||||
|
||||
**Source**: [InfoQ - Claude Code Creator Workflow (Jan 2026)](https://www.infoq.com/news/2026/01/claude-code-creator-workflow/)
|
||||
**Key insights from Boris**:
|
||||
|
||||
> **On multi-clauding**: "I use Cowork as a 'doer,' not a chat: it touches files, browsers, and tools directly. I think about productivity as parallelism: multiple tasks running while I steer outcomes."
|
||||
|
||||
> **On CLAUDE.md**: "I treat Claude.md as compounding memory: every mistake becomes a durable rule for the team."
|
||||
|
||||
> **On plan-first workflow**: "I run plan-first workflows: once the plan is solid, execution gets dramatically cleaner."
|
||||
|
||||
> **On verification loops**: "I give Claude a way to verify output (browser/tests): verification drives quality."
|
||||
|
||||
**Why Opus 4.5 with Thinking**: Although more expensive per token (~$15/1M input vs $3/1M for Sonnet), Opus requires fewer correction iterations. Net result: faster delivery and lower total cost despite higher unit price.
|
||||
|
||||
**The supervision model**: Boris describes his role as "tending to multiple agents" rather than "doing every click yourself." The workflow becomes about **steering outcomes** across 5-10 parallel sessions, unblocking when needed, rather than sequential execution.
|
||||
|
||||
**Source**: [InfoQ - Claude Code Creator Workflow (Jan 2026)](https://www.infoq.com/news/2026/01/claude-code-creator-workflow/) | [Interview: I got a private lesson on Claude Cowork & Claude Code](https://www.youtube.com/watch?v=DW4a1Cm8nG4)
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -14863,4 +14905,4 @@ Common misconceptions we've seen:
|
|||
|
||||
**Contributions**: Issues and PRs welcome.
|
||||
|
||||
**Last updated**: January 2026 | **Version**: 3.12.1
|
||||
**Last updated**: January 2026 | **Version**: 3.13.0
|
||||
|
|
|
|||
|
|
@ -3,8 +3,8 @@
|
|||
# Source: guide/ultimate-guide.md
|
||||
# Purpose: Condensed index for LLMs to quickly answer user questions about Claude Code
|
||||
|
||||
version: "3.12.1"
|
||||
updated: "2026-01-25"
|
||||
version: "3.13.0"
|
||||
updated: "2026-01-26"
|
||||
|
||||
# ════════════════════════════════════════════════════════════════
|
||||
# DEEP DIVE - Line numbers in guide/ultimate-guide.md
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue