release: v3.28.1 - Visual Diagrams Series (40 Mermaid diagrams)

guide/diagrams/: new directory with 40 interactive Mermaid diagrams - 10 thematic files: foundations, context/sessions, configuration, architecture, MCP ecosystem, dev workflows, multi-agent patterns, security/production, cost/optimization, adoption/learning - Each diagram: Mermaid (GitHub-native) + ASCII fallback + source link - Bold Guy palette (6-color system) consistent across all diagrams - README with index, visual palette legend, navigation by use case Also includes (backlog from v3.28.0→v3.28.1): - guide/ultimate-guide.md: Managing Large MCP Server Sets, AI Code Disclosure Policy, claude-mem Gemini alternative, observability - guide/workflows/plan-driven.md: Boris Tane custom markdown plans (+172L) - guide/security-hardening.md: Part 4 PR security review workflow - examples/agents/security-patcher.md: new security agent - examples/hooks/bash/security-gate.sh: PreToolUse security hook - guide/observability.md: activity monitoring, external tools, proxying - docs/resource-evaluations/: 4 new evaluations (Boris Cherny, Moigneu, Boris Tane, Aristote AI instructions) - README.md: Visual Diagrams section in "What Makes This Guide Unique" Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-02-22 15:51:21 +01:00 · 2026-02-22 15:51:21 +01:00 · dbb62306d7
commit dbb62306d7
parent 9218ab37d6
27 changed files with 3355 additions and 19 deletions
--- a/docs/resource-evaluations/2026-02-22-boris-cherny-worktree-tips-reddit.md
+++ b/docs/resource-evaluations/2026-02-22-boris-cherny-worktree-tips-reddit.md
@ -0,0 +1,178 @@
+# Évaluation: "5 Claude Code Worktree Tips from Creator" - Reddit/Twitter
+
+**Date d'évaluation**: 2026-02-22
+**Évaluateur**: Claude Code (auto)
+**Ressource**: Reddit r/ClaudeAI + Tweet Boris Cherny (@bcherny)
+
+---
+
+## Métadonnées
+
+| Champ | Valeur |
+|-------|--------|
+| **Source primaire** | Tweet @bcherny, 2026-02-21 · 40.2K views |
+| **Source secondaire** | Reddit r/ClaudeAI, 164 upvotes |
+| **Auteur** | Boris Cherny (créateur et head of Claude Code @ Anthropic) |
+| **Catégorie** | Productivity - Worktrees |
+| **URL Reddit** | https://www.reddit.com/r/ClaudeAI/comments/1rae05r/ |
+| **Tweet original** | https://x.com/bcherny/status/2025007393290272904 |
+
+---
+
+## 📄 Résumé du contenu
+
+- **Annonce officielle**: `claude --worktree` / `-w` flag désormais disponible en CLI (existait en Desktop, maintenant porté en CLI)
+- **Modèle concurrent natif**: Chaque agent obtient son propre worktree isolé, pas d'interférence entre sessions parallèles
+- **Patterns communautaires validés**: Per-worktree port management (scripts, docker-compose override, ports aléatoires), per-worktree `.claude/settings.json` tuning, "main worktree as integration branch"
+- **Ressource externe identifiée**: [claude-worktree-hooks](https://github.com/tfriedel/claude-worktree-hooks) — port isolation automatique pour `claude --worktree`
+- **Débat worktrees vs multi-clone**: Worktrees partagent le même objet git (branches, commits, moins de disk), mais multi-clone reste valide pour équipes non-familières
+
+---
+
+## 🎯 Score de pertinence
+
+| Score | Signification |
+|-------|---------------|
+| 5 | Essentiel - Gap majeur dans le guide |
+| **4** | **Très pertinent - Amélioration significative** |
+| 3 | Pertinent - Complément utile |
+| 2 | Marginal - Info secondaire |
+| 1 | Hors scope - Non pertinent |
+
+**Score: 4/5**
+
+**Justification**: Trois facteurs convergents :
+1. **Gap documenté**: `claude --worktree` / `-w` est dans `claude-code-releases.md` (v2.1.49) mais **absent du guide principal** (section 13408) qui couvre encore uniquement le `git worktree add` manuel
+2. **Patterns actionnables manquants**: port management, per-worktree settings.json tuning, integration branch pattern — rien de cela dans le guide
+3. **Source primo-autoritaire**: Boris Cherny est le créateur de Claude Code → contenu directement pertinent, pas de filtre communautaire non vérifié
+
+---
+
+## ⚖️ Comparatif
+
+| Aspect | Cette ressource | Notre guide (section 13408) |
+|--------|----------------|------------------------------|
+| `claude --worktree` CLI flag | ✅ Annoncé + context | ❌ Absent du guide principal |
+| `git worktree add` manuel | ✅ Mentionné (comparaison) | ✅ Documenté avec exemples |
+| Port conflict management | ✅ Patterns concrets (docker, scripts, random ports) | ❌ Non couvert |
+| Per-worktree `.claude/settings.json` | ✅ Tip BP041 (7 upvotes) | ❌ Non couvert |
+| Integration branch pattern | ✅ Tip BP041 | ❌ Non couvert |
+| 4 custom commands (/git-worktree, etc.) | ❌ Non mentionné | ✅ Documenté |
+| Worktrees vs multi-clone trade-offs | ✅ Débat riche | ❌ Non couvert |
+
+---
+
+## 📍 Recommandations d'intégration
+
+**Score ≥ 3 → Intégrer**
+
+### Action unique recommandée
+
+**Fichier**: `guide/ultimate-guide.md`
+**Section**: 13408 - "Git Worktrees for Parallel Development"
+**Priorité**: Haute (dans la semaine — le flag date du 2026-02-20)
+
+**Contenu à ajouter** (~30-40 lignes) :
+
+```markdown
+#### Using the `--worktree` CLI Flag (v2.1.49+)
+
+Since v2.1.49, Claude Code includes built-in worktree support:
+
+```bash
+# Create an isolated worktree automatically
+claude --worktree        # or -w (short form)
+
+# Equivalent manual setup
+git worktree add ../myproject-feature feature-a && cd ../myproject-feature && claude
+```
+
+**What `--worktree` does**: Creates a temporary git worktree, launches Claude in it,
+and cleans up on exit if no changes were made.
+
+**Practical patterns:**
+
+**Port isolation** (when services need to run per worktree):
+- Use docker-compose override files auto-generated at worktree creation
+- Assign random ports dynamically and inject via env variables
+- See [claude-worktree-hooks](https://github.com/tfriedel/claude-worktree-hooks) for port automation
+
+**Per-worktree behavior tuning:**
+```bash
+# In each worktree, create a .claude/settings.json
+# Tighter permissions for refactoring worktrees, looser for exploration
+```
+
+**Integration branch pattern:**
+Keep one 'main' worktree as your integration branch.
+Only merge into it from parallel worktrees — never develop directly there.
+```
+
+**Ne pas créer** de section séparée pour `claude-worktree-hooks` — juste une note de bas de section.
+
+---
+
+## 🔥 Challenge (technical-writer agent)
+
+> *Score 4/5 justifié, mais pour la mauvaise raison. L'argument "créateur = autorité" est biaisé — c'est la convergence (gap documenté + patterns actionnables vérifiables via release v2.1.49 + communauté) qui justifie le score.*
+>
+> *Plan d'intégration initial trop dispersé (3 points d'entrée). Bonne simplification : une seule extension de la section 13408.*
+>
+> *Risque de non-intégration : modéré. Le flag est dans les releases (trouvable), mais la section 13408 devient incohérente si elle n'inclut pas la commande native — elle enseigne encore uniquement le git manuel alors que la feature native existe depuis 2 jours.*
+
+- **Score ajusté**: 4/5 (confirmé)
+- **Points manqués**: Source primaire = changelog v2.1.49, pas le tweet (le tweet disparaît, le changelog reste)
+- **Risques de non-intégration**: Incohérence interne (section 13408 outdated vs releases.md à jour)
+
+---
+
+## ✅ Fact-Check
+
+| Affirmation | Vérifiée | Source |
+|-------------|----------|--------|
+| `claude --worktree` / `-w` existe en v2.1.49 | ✅ | `guide/claude-code-releases.md` ligne 53 |
+| Boris Cherny = créateur de Claude Code | ✅ | Perplexity (ITPro, Lenny's Newsletter, YouTube) |
+| Tweet date: 21 Feb 2026 | ✅ | Screenshot utilisateur |
+| 40.2K views sur le tweet | ✅ | Screenshot utilisateur |
+| Reddit: 164 upvotes | ✅ | Screenshot utilisateur |
+| `claude-worktree-hooks` existe sur GitHub | ⚠️ | Mentionné par u/cygn — non vérifié directement |
+| `workmux` existe sur GitHub | ⚠️ | Mentionné par u/philosophical_lens — non vérifié directement |
+
+**Corrections apportées**: Aucune (aucune stat inventée)
+
+**Stats nécessitant vérification externe avant intégration**: Les repos GitHub (`claude-worktree-hooks`, `workmux`) — vérifier existence + activité avant de les mentionner dans le guide.
+
+---
+
+## 🔗 Sources complémentaires
+
+| Source | Apport principal |
+|--------|-----------------|
+| [LinkedIn Guillaume Moigneu (2026-02-22)](./2026-02-22-guillaume-moigneu-worktree-linkedin.md) | `WorktreeCreate`/`WorktreeRemove` hooks, `isolation: worktree` déclaratif (v2.1.50), support Desktop + IDE, article externe |
+
+**Clarification versions** (Guillaume attribue tout à v2.1.50, incorrect) :
+- `--worktree` CLI + `isolation: "worktree"` subagents → **v2.1.49**
+- `WorktreeCreate`/`WorktreeRemove` hooks + déclaratif agent defs → **v2.1.50**
+
+---
+
+## 🎯 Décision finale
+
+- **Score final**: 4/5
+- **Action**: **Intégrer**
+- **Délai recommandé**: Dans la semaine (feature sortie le 2026-02-20)
+- **Effort estimé**: ~50-60 lignes dans la section 13408 + ~10 lignes section hooks
+- **Confiance**: Haute (confirmé dans nos propres release notes v2.1.49 + v2.1.50)
+
+### Périmètre d'intégration complet (après les deux évals)
+
+1. Section `13408` — ajouter :
+   - `claude --worktree` / `-w` native flag avec exemple
+   - `isolation: worktree` déclaratif dans agent defs (YAML)
+   - Subagents + worktrees pour migrations parallèles
+   - Port management patterns (docker-compose override, random ports)
+   - Per-worktree `.claude/settings.json` tuning
+   - Integration branch pattern
+   - Note Desktop + IDE support
+2. Section hooks — ajouter `WorktreeCreate`/`WorktreeRemove` (non-git SCM use case)
+3. Références externes : `claude-worktree-hooks` + article Guillaume Moigneu (à vérifier avant publication)
--- a/docs/resource-evaluations/2026-02-22-guillaume-moigneu-worktree-linkedin.md
+++ b/docs/resource-evaluations/2026-02-22-guillaume-moigneu-worktree-linkedin.md
@ -0,0 +1,117 @@
+# Évaluation: "Claude Code built-in git worktree support" - LinkedIn Guillaume Moigneu
+
+**Date d'évaluation**: 2026-02-22
+**Évaluateur**: Claude Code (auto)
+**Ressource**: LinkedIn post Guillaume Moigneu
+
+---
+
+## Métadonnées
+
+| Champ | Valeur |
+|-------|--------|
+| **Source** | LinkedIn post de Guillaume Moigneu, 2026-02-22 |
+| **Auteur** | Guillaume Moigneu — Solution Architecture/Advocacy @ Upsun, tech speaker |
+| **Autorité** | Praticien (pas Anthropic) — Solution Architect avec expertise déploiement |
+| **Catégorie** | Productivity - Worktrees + Subagents |
+| **Article lié** | https://lnkd.in/gCicQRHP (article personnel sur worktrees) |
+| **Relation** | Complément à [2026-02-22-boris-cherny-worktree-tips-reddit.md](./2026-02-22-boris-cherny-worktree-tips-reddit.md) |
+
+---
+
+## 📄 Résumé du contenu
+
+- **Subagent + worktree combinés**: Claude peut créer des worktrees pour ses propres subagents — migrations parallèles massives sans conflits d'écriture
+- **`isolation: worktree` déclaratif** (v2.1.50): Dans les agent defs, plus besoin de le spécifier à chaque appel
+- **Hooks `WorktreeCreate`/`WorktreeRemove`**: Setup/teardown custom VCS → **non-git SCM supporté** (Perforce, SVN, etc.)
+- **Disponible sur**: CLI (`--worktree`), Desktop app, IDE — pas seulement CLI
+- **Article détaillé**: Son propre article sur les worktrees (lnkd.in/gCicQRHP)
+
+---
+
+## 🔍 Clarification versions
+
+Guillaume attribue tout à v2.1.50 — c'est légèrement inexact :
+
+| Feature | Version réelle |
+|---------|----------------|
+| `--worktree` / `-w` CLI flag | **v2.1.49** (2026-02-20) |
+| `isolation: "worktree"` pour subagents | **v2.1.49** (2026-02-20) |
+| `WorktreeCreate`/`WorktreeRemove` hooks | **v2.1.50** (2026-02-21) |
+| `isolation: worktree` déclaratif dans agent defs | **v2.1.50** (2026-02-21) |
+| Support Desktop + IDE | **v2.1.50** (confirmé) |
+
+---
+
+## 🎯 Score de pertinence
+
+**Score: 3/5** (complément — ne justifie pas intégration indépendante)
+
+**Justification**: Le post n'apporte pas de contenu standalone suffisant pour une section dédiée. Sa valeur est dans les **deltas** par rapport à l'évaluation principale :
+1. Hooks `WorktreeCreate`/`WorktreeRemove` → non-git SCM (non couvert ailleurs)
+2. `isolation: worktree` déclaratif dans agent defs (précision v2.1.50 manquante)
+3. Confirmation Desktop + IDE (vs CLI-only dans l'autre éval)
+4. Article externe à référencer
+
+---
+
+## ⚖️ Delta vs évaluation principale (Boris Cherny Reddit)
+
+| Aspect | Reddit/Tweet | LinkedIn Guillaume | Dans le guide |
+|--------|-------------|-------------------|---------------|
+| `--worktree` CLI | ✅ | ✅ | ❌ guide principal |
+| Subagents + worktrees | Évoqué | **Détaillé (migrations parallèles)** | ❌ |
+| `WorktreeCreate`/`WorktreeRemove` hooks | ❌ | **✅ Non-git SCM** | ❌ |
+| `isolation: worktree` déclaratif | ❌ | **✅** | ❌ |
+| Desktop + IDE (pas que CLI) | ❌ | **✅** | ❌ |
+| Article de référence externe | ❌ | **✅** | ❌ |
+
+---
+
+## 📍 Intégration recommandée
+
+**Complète l'intégration définie dans l'éval principale.** Ajouter dans la même section `guide/ultimate-guide.md:13408` :
+
+```markdown
+#### Subagents + Worktree Isolation
+
+Claude can spin up worktrees for its own subagents. Declare isolation directly in agent definitions:
+
+```yaml
+# .claude/agents/migration-agent.md
+---
+isolation: worktree   # Each invocation gets its own worktree (v2.1.50+)
+background: true
+---
+```
+
+This enables write-safe parallel migrations: 4 agents refactoring different modules,
+no merge conflicts because each works in its own copy.
+```
+
+**Aussi**: Ajouter une note sur les hooks `WorktreeCreate`/`WorktreeRemove` dans la section hooks du guide (non-git SCM use case).
+
+---
+
+## ✅ Fact-Check
+
+| Affirmation | Vérifiée | Source |
+|-------------|----------|--------|
+| `WorktreeCreate`/`WorktreeRemove` hooks en v2.1.50 | ✅ | `guide/claude-code-releases.md` ligne 30-31 |
+| `isolation: worktree` déclaratif en v2.1.50 | ✅ | `guide/claude-code-releases.md` ligne 32 |
+| `--worktree` en v2.1.49 (pas v2.1.50) | ✅ | `guide/claude-code-releases.md` ligne 53 |
+| Support Desktop + IDE | ✅ (implicite) | v2.1.50 notes |
+| Non-git SCM via hooks | ✅ | `WorktreeCreate`/`WorktreeRemove` hook events |
+| Article Guillaume: lnkd.in/gCicQRHP | ⚠️ | URL LinkedIn raccourcie — non vérifié directement |
+
+---
+
+## 🎯 Décision finale
+
+- **Score final**: 3/5
+- **Action**: **Intégrer comme complément** — pas de section séparée, enrichit l'intégration de l'éval principale
+- **Nouveaux éléments à ajouter au guide**:
+  1. `isolation: worktree` déclaratif dans agent defs (YAML example)
+  2. `WorktreeCreate`/`WorktreeRemove` hooks → section hooks
+  3. Mention Desktop + IDE support
+  4. Article Guillaume comme référence externe
--- a/docs/resource-evaluations/aristote-ai-instructions-patterns.md
+++ b/docs/resource-evaluations/aristote-ai-instructions-patterns.md
@ -0,0 +1,75 @@
+# Resource Evaluation: Méthode Aristote — ai-instructions patterns
+
+**Source**: Internal project — `/Users/florianbruniaux/Sites/MethodeAristote/app/doc/guides/ai-instructions/`
+**Author**: Florian Bruniaux (same author as this guide)
+**Date analyzed**: 2026-02-22
+**Score**: 4/5
+
+---
+
+## Summary
+
+Production patterns from the Méthode Aristote EdTech platform (5 developers, Claude Code + Cursor + Codex). The ai-instructions directory contains 24 files documenting team workflows, memory systems, tool-specific configurations, and governance policies. Several patterns were novel or better-documented than what existed in the guide.
+
+---
+
+## Scoring Grid
+
+| Criterion | Score | Notes |
+|-----------|-------|-------|
+| **Novelty** | 3/5 | Profile assembly + claude-mem already in guide; disclosure policy new |
+| **Author credibility** | 5/5 | Same author, production data from real team |
+| **Actionability** | 5/5 | Concrete configs, measured results, copy-pastable templates |
+| **Accuracy** | 5/5 | Verified against actual codebase |
+| **Depth** | 4/5 | Cost measurements, architectural decisions, failure modes |
+
+**Overall: 4/5**
+
+---
+
+## Already Documented (no action needed)
+
+| Pattern | Guide location |
+|---------|---------------|
+| Profile-based module assembly | Section 3.5 (comprehensive) |
+| claude-mem basics | ~line 9140 |
+| Search cascade (grepai → Serena → Context7 → Perplexity) | ~line 9308 |
+
+---
+
+## Gaps Identified and Fixed
+
+### 1. AI Code Disclosure Policy
+**Gap**: No team governance pattern for AI-generated code visibility.
+**Fix**: Added section "AI Code Disclosure Policy" at end of Section 3.5.
+**Content**: >10 lines threshold, PR template, graduated enforcement by level, anti-pattern warning.
+
+### 2. claude-mem with Gemini (cost optimization)
+**Gap**: Guide said "AI summarization via Claude" — missed the Gemini 2.5 Flash alternative ($14/month vs $102 Haiku, -86%).
+**Fix**: Added "Cost optimization — use Gemini instead of Claude" block in claude-mem section.
+**Data source**: `claude-mem-analysis-corrected.md` (553 sessions, ~400/month, measured costs).
+
+### 3. claude-mem hooks coexistence
+**Gap**: Installation instructions didn't warn about hooks array overwrite risk.
+**Fix**: Added "Critical installation gotcha — hooks coexistence" with before/after JSON examples.
+**Source**: `claude-mem-install-prompt.md` (6 existing hooks, explicit preservation checklist).
+
+### 4. claude-mem fail-open (v9.1.0+)
+**Gap**: No mention of reliability behavior when worker is down.
+**Fix**: Added "Reliability: fail-open architecture" block with restart instructions.
+
+---
+
+## What Was Not Integrated
+
+- Aristote-specific architecture (3-tier Router/Service/Repository) — too project-specific
+- SSE real-time pattern — too domain-specific
+- SonarQube MCP details — already exists in examples
+- Multi-env .env.* pattern — marginal value, tips-level only
+- Specific team profiles (florian.yaml, nico.yaml) — not generalizable
+
+---
+
+## Attribution
+
+Internal source — Méthode Aristote project (`/app/doc/guides/ai-instructions/`). Same author as guide. Analysis performed 2026-02-22.
--- a/docs/resource-evaluations/boris-tane-how-i-use-claude-code.md
+++ b/docs/resource-evaluations/boris-tane-how-i-use-claude-code.md
@ -0,0 +1,96 @@
+# Resource Evaluation: "How I use Claude Code" — Boris Tane
+
+**URL**: https://boristane.com/blog/how-i-use-claude-code/
+**Author**: Boris Tane, Engineering Lead @ Cloudflare
+**Date published**: February 2026
+**Evaluation date**: 2026-02-22
+**Score**: 4/5
+
+---
+
+## Summary
+
+9-month practitioner account of using Claude Code in production at Cloudflare. Describes a structured plan-driven workflow with an original pattern — the **Annotation Cycle** — where human and agent iterate on a markdown plan file before any implementation begins.
+
+---
+
+## Scoring Grid
+
+| Criterion | Score | Notes |
+|-----------|-------|-------|
+| **Novelty** | 4/5 | Annotation Cycle not documented elsewhere in the guide |
+| **Author credibility** | 5/5 | Engineering Lead at Cloudflare, 9 months usage |
+| **Actionability** | 4/5 | Concrete prompts, phases, examples |
+| **Accuracy** | 4/5 | Consistent with Claude Code behavior (verified) |
+| **Depth** | 4/5 | Practitioner insights, not surface-level tips |
+
+**Overall: 4/5** — High value. Integrate within 1 week.
+
+---
+
+## Key Insights
+
+### 1. Emphatic Research Language
+Without strong signal, Claude skims. Words like "deeply", "in great detail", "intricacies" shift behavior from surface scan to thorough investigation. Output must be written to a file — verbal summaries disappear on context compaction.
+
+### 2. The Annotation Cycle
+Core innovation: iterate on `plan.md` with human annotations before any code is written. Human adds comments directly to the plan file, agent revises, repeat until no open questions remain. Typical: 1-6 iterations.
+
+The guard prompt "do NOT implement anything yet" is critical — without it, Claude will start coding during planning.
+
+### 3. Markdown as Shared Mutable State
+Quote: "The markdown file acts as shared mutable state between you and the agent." This is the key insight — the plan file isn't just documentation, it's the coordination artifact.
+
+### 4. Terse Feedback in Implementation Phase
+Once plan is approved, implementation is mechanical. Short feedback ("that looks right", screenshots) is more effective than paragraphs — decisions are already made.
+
+### 5. Complementary Techniques
+- Cherry-picking: implement a subset of the plan
+- Scope trimming: remove items before implementing
+- Reference-based guidance: "do it like auth.ts"
+- Revert & re-scope: `git revert` + restart with narrower plan
+
+---
+
+## Fact-Check
+
+| Claim | Verified | Notes |
+|-------|----------|-------|
+| Emphatic language changes research depth | ✓ Plausible | Consistent with prompt engineering principles |
+| Plan files survive context compaction | ✓ Accurate | Files are external to conversation |
+| "Guard prompt" prevents premature implementation | ✓ Accurate | Explicit constraints work as documented |
+| 1-6 annotation iterations typical | ○ Unverified | Author's personal experience, no sample size |
+
+---
+
+## Integration Decision
+
+**Decision**: Integrate (Score 4) — Added as new section in `guide/workflows/plan-driven.md`.
+
+**What was integrated**:
+- Section "Advanced: Custom Markdown Plans (Boris Tane Pattern)"
+- Three-phase workflow diagram (Research → Annotation Cycle → Implementation)
+- Emphatic research prompts with rationale
+- Annotation Cycle diagram with exit criteria
+- Guard prompt example
+- Phase 3 mechanical implementation guidance
+- Complementary techniques table
+- Decision table: `/plan` vs custom `.md`
+
+**Cross-references added**:
+- `guide/methodologies.md` — callout after Plan-First section
+- `machine-readable/reference.yaml` — 4 entries (pattern, source, author)
+
+---
+
+## What Was Not Integrated
+
+- Specific cost figures (not verifiable for general users)
+- Cloudflare-specific tooling references (not generalizable)
+- Exact iteration counts (too anecdotal without sample size)
+
+---
+
+## Attribution
+
+> Boris Tane, Engineering Lead @ Cloudflare. Source: ["How I use Claude Code"](https://boristane.com/blog/how-i-use-claude-code/) (Feb 2026).