feat: add git best practices, worktrees, and cost optimization sections

- Add Section 9.12: Git Best Practices & Workflows (~400 lines) - Commit message best practices with Conventional Commits - Git amend workflow with safety rules - Branch management and naming conventions - Rewind vs Revert decision tree - Comprehensive git worktrees documentation - Add Section 9.13: Cost Optimization Strategies (~350 lines) - Model selection matrix (Haiku/Sonnet/Opus) - OpusPlan mode for efficient workflows - Token-saving techniques and cost tracking - ROI calculations and economic workflows - Add examples/commands/git-worktree.md slash command template - Update CHANGELOG.md with v2.0.0 additions - Update version metadata to 2.0 across documentation Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-10 17:00:45 +01:00 · 2026-01-10 17:00:45 +01:00 · 2dd2744721
commit 2dd2744721
parent 2f84c2a769
6 changed files with 1252 additions and 39 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -6,6 +6,85 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

 ## [Unreleased]

+## [2.0.0] - 2026-01-10
+
+### Added
+- **Section 9.12: Git Best Practices & Workflows** (~400 lines)
+  - Commit message best practices with Conventional Commits format
+  - Git amend workflow with safety rules and verification process
+  - Branch management patterns and naming conventions
+  - Rewind vs Revert decision tree for different scenarios
+  - **Git Worktrees comprehensive documentation**
+    - Parallel branch development without context switching
+    - Setup process and directory structure
+    - Claude Code integration patterns
+    - CLAUDE.md memory file strategies for worktrees
+    - Best practices and troubleshooting guide
+    - Cleanup procedures
+- **Section 9.13: Cost Optimization Strategies** (~350 lines)
+  - Model selection matrix (Haiku/Sonnet/Opus use cases and costs)
+  - OpusPlan mode (Opus for planning, Sonnet for execution)
+  - Token-saving techniques (selective loading, .claudeignore, proactive compacting)
+  - Agent specialization for efficiency
+  - Cost tracking with /status command and budget alerts
+  - Economic workflows (Haiku for tests, Sonnet for implementation)
+  - Token calculation reference with real pricing examples
+  - Cost vs productivity trade-offs analysis
+  - ROI calculations and cost-effectiveness metrics
+- **examples/commands/git-worktree.md** - Slash command template
+  - Systematic worktree setup workflow
+  - Directory selection priority logic (.worktrees/ vs worktrees/)
+  - Safety verification (.gitignore checks)
+  - Auto-detection of package managers (pnpm, cargo, poetry, go)
+  - Baseline test verification
+  - Complete quick reference table
+- **8 TL;DR/Recap sections** for improved navigation and learning journey
+  - Section 2 TL;DR (Core Concepts) - 2 minute overview of mental model
+  - Section 3 TL;DR (Memory & Settings) - 90 second memory hierarchy guide
+  - Section 4 TL;DR (Agents) - 60 second quick start guide
+  - Section 7 TL;DR (Hooks) - 60 second event system overview
+  - Section 9 TL;DR (Advanced Patterns) - 3 minute pattern categories breakdown
+  - Section 10 TL;DR (Reference) - 1 minute navigation table
+  - Subsection 2.2 Quick Reference (Context Management zones)
+  - Section 9 Recap Checklist (Pattern mastery verification before Section 10)
+- **Format Enhancements** for better readability
+  - Collapsible tables using `<details>` tags for dense content (MCP Server Catalog)
+  - C-style comment format (`/*──────*/`) for multi-OS installation commands
+  - Quick navigation anchor links at top of all 10 major sections
+- **zebbern/claude-code-guide reference** in README Resources
+  - New "Related Guides" section grouping zebbern and Claudelog as peer guides
+  - Positioned prominently after Official docs section
+  - Added context: "Comprehensive reference & troubleshooting guide with cybersecurity focus"
+
+### Changed
+- **Updated statistics** throughout documentation
+  - Guide expanded from 7,481 to 7,668 lines (+187 lines, +2.5%)
+  - Word count: 27,471 words (27K+)
+  - Reading time estimate: 2.5 hours → 3 hours (more accurate for full guide)
+  - README: "4000+ lines" → "7500+ lines, 27K+ words"
+  - PDF Kimi reading time: 2.5 hours → 3 hours
+- **Version alignment** across all files to 2.0
+  - english-ultimate-claude-code-guide.md: Version 1.0 → 2.0
+  - README.md: Version 1.0 → 2.0
+  - claude-setup-audit-prompt.md: Version 1.0 → 2.0
+  - cheatsheet-en.md: Already 2.0
+- **Date updates** to January 2026
+  - All "Last updated" fields across documentation
+  - Status Overview Table dates (Jan 2025 → Jan 2026)
+  - Pricing model reference date (January 2026)
+  - Footer timestamps in all major files
+
+### Fixed
+- Removed duplicate Claudelog reference from "Frameworks & Tools" section (was in both Key inspirations and Resources)
+- Improved organization of Resources section with clearer categorization
+
+### Stats
+- Guide now 7,668 lines (from 6,250 lines in v1.2.0)
+- Added 187 lines of TL;DR/navigation content
+- ~23% growth from v1.2.0
+- Focus on user experience optimization and learning journey enhancement
+- Major version bump reflects structural documentation paradigm shift (learning-focused TL;DRs throughout)
+
 ## [1.2.0] - 2025-01-10

 ### Added
--- a/README.md
+++ b/README.md
@ -73,11 +73,11 @@ If you find value in this guide, have questions, or want to discuss Claude Code

 | File | Description | Reading Time |
 |------|-------------|--------------|
-| [`english-ultimate-claude-code-guide.md`](./english-ultimate-claude-code-guide.md) | Complete guide (4000+ lines) | ~2.5 hours |
+| [`english-ultimate-claude-code-guide.md`](./english-ultimate-claude-code-guide.md) | Complete guide (7500+ lines, 27K+ words) | ~3 hours |
 | [`cheatsheet-en.md`](./cheatsheet-en.md) | 1-page printable daily reference | 5 minutes |
 | [`claude-setup-audit-prompt.md`](./claude-setup-audit-prompt.md) | Self-audit prompt for your setup | ~10 minutes |
-| [`claude-code-ultimate-guide_notebooklm.pdf`](./claude-code-ultimate-guide_notebooklm.pdf) | Audio Deep Dive (NotebookLM podcast) | ~1 hour |
-| [`claude-code-ultimate-guide_kimi.pdf`](./claude-code-ultimate-guide_kimi.pdf) | PDF version (Kimi export) | ~2.5 hours |
+| [`claude-code-ultimate-guide_notebooklm.pdf`](./claude-code-ultimate-guide_notebooklm.pdf) | NotebookLM slides export | ~20 minutes |
+| [`claude-code-ultimate-guide_kimi.pdf`](./claude-code-ultimate-guide_kimi.pdf) | PDF version (Kimi export) | ~3 hours |

 ---

@ -241,6 +241,10 @@ Want to know if your Claude Code setup follows best practices?
 ### Official
 - [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code) — Official Anthropic docs

+### Related Guides
+- [zebbern/claude-code-guide](https://github.com/zebbern/claude-code-guide) — Comprehensive reference & troubleshooting guide with cybersecurity focus (excellent for security practitioners)
+- [Claudelog.com](https://claudelog.com/) — Tips, patterns & tutorials (highly recommended for all users)
+
 ### Community Curated Lists
 - [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) — Commands, workflows, IDE integrations
 - [awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills) — Custom skills collection
@ -250,7 +254,6 @@ Want to know if your Claude Code setup follows best practices?

 ### Frameworks & Tools
 - [SuperClaude](https://github.com/SuperClaude-Org/SuperClaude_Framework) — Advanced configuration framework with 30+ commands
- [Claudelog.com](https://claudelog.com/) — Tips, patterns & tutorials

 ### Further Reading
 - [Nick Tune: Coding Agent Development Workflows](https://medium.com/nick-tune-tech-strategy-blog/coding-agent-development-workflows-af52e6f912aa) — Advanced autonomous workflow patterns
@ -273,4 +276,4 @@ You are free to share and adapt this material, provided you give appropriate cre

 ---

-*Last updated: January 2025 | Version 1.0*
+*Last updated: January 2026 | Version 2.0*
--- a/cheatsheet-en.md
+++ b/cheatsheet-en.md
@ -6,7 +6,7 @@

 **Written with**: Claude (Anthropic)

-**Version**: 2.0 | **Last Updated**: January 2025
+**Version**: 2.0 | **Last Updated**: January 2026

 ---

@ -364,4 +364,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 2025 | Version 2.0*
+*Last updated: January 2026 | Version 2.0*
--- a/claude-setup-audit-prompt.md
+++ b/claude-setup-audit-prompt.md
@ -440,4 +440,4 @@ Here's an example of what the audit report looks like:

 ---

-*Last updated: January 2025 | Version 1.0*
+*Last updated: January 2026 | Version 2.0*
--- a/english-ultimate-claude-code-guide.md
+++ b/english-ultimate-claude-code-guide.md
--- a/examples/commands/git-worktree.md
+++ b/examples/commands/git-worktree.md
@ -0,0 +1,142 @@
+# Git Worktree Setup
+
+Create isolated git worktrees for feature development without switching branches.
+
+**Core principle:** Systematic directory selection + safety verification = reliable isolation.
+
+## Process
+
+1. **Check Existing Directories**: `.worktrees/` or `worktrees/`
+2. **Verify .gitignore**: Ensure worktree dir is ignored
+3. **Create Worktree**: `git worktree add`
+4. **Install Dependencies**: Auto-detect package manager
+5. **Run Baseline Tests**: Verify clean state
+6. **Report Location**: Confirm ready
+
+## Directory Selection
+
+### Priority Order
+
+```bash
+# 1. Check existing directories
+ls -d .worktrees 2>/dev/null     # Preferred (hidden)
+ls -d worktrees 2>/dev/null      # Alternative
+
+# 2. Check CLAUDE.md for preference
+grep -i "worktree.*director" CLAUDE.md 2>/dev/null
+
+# 3. Ask user if neither exists
+```
+
+**If both exist:** `.worktrees/` wins.
+
+## Safety Verification
+
+**For project-local directories:**
+
+```bash
+# Check if directory in .gitignore
+grep -q "^\.worktrees/$" .gitignore || grep -q "^worktrees/$" .gitignore
+```
+
+**If NOT in .gitignore:**
+1. Add line to .gitignore
+2. Commit the change
+3. Proceed with worktree creation
+
+**Why critical:** Prevents accidentally committing worktree contents.
+
+## Creation Steps
+
+```bash
+# 1. Detect project name
+project=$(basename "$(git rev-parse --show-toplevel)")
+
+# 2. Create worktree with new branch
+git worktree add .worktrees/$BRANCH_NAME -b $BRANCH_NAME
+
+# 3. Navigate
+cd .worktrees/$BRANCH_NAME
+```
+
+## Auto-Detect Setup
+
+```bash
+# Node.js
+if [ -f package.json ]; then pnpm install; fi
+
+# Rust
+if [ -f Cargo.toml ]; then cargo build; fi
+
+# Python
+if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+if [ -f pyproject.toml ]; then poetry install; fi
+
+# Go
+if [ -f go.mod ]; then go mod download; fi
+```
+
+## Baseline Verification
+
+```bash
+# Run tests to verify clean state
+pnpm test        # Node.js
+cargo test       # Rust
+pytest           # Python
+go test ./...    # Go
+```
+
+**If tests fail:** Report failures, ask whether to proceed.
+**If tests pass:** Report ready.
+
+## Final Report
+
+```
+Worktree ready at <full-path>
+Tests passing (<N> tests, 0 failures)
+Ready to implement <feature-name>
+```
+
+## Quick Reference
+
+| Situation | Action |
+|-----------|--------|
+| `.worktrees/` exists | Use it (verify .gitignore) |
+| `worktrees/` exists | Use it (verify .gitignore) |
+| Both exist | Use `.worktrees/` |
+| Neither exists | Check CLAUDE.md → Ask user |
+| Not in .gitignore | Add + commit immediately |
+| Tests fail | Report + ask to proceed |
+
+## Common Mistakes
+
+**Skipping .gitignore verification**
+- Worktree contents get tracked, pollute git status
+
+**Assuming directory location**
+- Follow priority: existing > CLAUDE.md > ask
+
+**Proceeding with failing tests**
+- Can't distinguish new bugs from pre-existing
+
+## Cleanup (After Work Complete)
+
+```bash
+# Remove worktree
+git worktree remove .worktrees/$BRANCH_NAME
+
+# Or force if uncommitted changes
+git worktree remove --force .worktrees/$BRANCH_NAME
+
+# Prune stale worktrees
+git worktree prune
+```
+
+## Usage
+
+```
+/git-worktree feature/auth
+/git-worktree fix/session-bug
+```
+
+Branch name: $ARGUMENTS