docs: add advanced worktree tooling section (Worktrunk + DIY alternatives)
Added Section 9.17 "Advanced Tooling for Worktree Management (Optional)" based on deep-dive analysis of 4 sources (Worktrunk GitHub, incident.io blog, Anthropic best practices, GitHub issue #1052). Key additions: - Pattern validation: 3 independent teams created worktree wrappers - Benchmark: Worktrunk vs vanilla git vs custom wrappers - Option 1: Worktrunk (1.6K stars, multi-platform, CI/LLM integration) - Option 2: DIY custom wrappers (incident.io, GitHub #1052 examples) - Philosophy: Learn fundamentals first, add wrapper for productivity later Updated machine-readable/reference.yaml: - Added advanced_worktree_tooling: 10661 - Fixed line references for sections after git worktrees - Updated Appendix references (14356, 14530, 14532, 14601) Score: 3/5 (pertinent - complément utile) Evaluation: claudedocs/resource-evaluations/worktrunk-evaluation.md Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
3e5a35295c
commit
da8dedc7f8
2 changed files with 236 additions and 12 deletions
|
|
@ -6561,6 +6561,99 @@ mgrep "code that handles user authentication"
|
|||
- Finding correct API usage
|
||||
- Checking official patterns
|
||||
|
||||
### ast-grep (Structural Code Search)
|
||||
|
||||
**Purpose**: AST-based pattern matching for precise structural code searches.
|
||||
|
||||
**Type**: Optional Community Plugin (not core Claude Code)
|
||||
|
||||
**Installation**:
|
||||
|
||||
```bash
|
||||
# Install ast-grep skill for Claude Code
|
||||
npx skills add ast-grep/agent-skill
|
||||
|
||||
# Or manually via plugin marketplace
|
||||
/plugin marketplace add
|
||||
```
|
||||
|
||||
**What is ast-grep?**
|
||||
|
||||
ast-grep searches code based on **syntax structure** (Abstract Syntax Tree) rather than plain text. This enables finding patterns like "async functions without error handling" or "React components using specific hooks" that regex cannot reliably detect.
|
||||
|
||||
**Key Characteristics**:
|
||||
|
||||
| Aspect | Behavior |
|
||||
|--------|----------|
|
||||
| **Invocation** | **Explicit** - Claude cannot automatically detect when to use it |
|
||||
| **Integration** | Plugin that teaches Claude how to write ast-grep rules |
|
||||
| **Languages** | JavaScript, Python, Rust, Go, Java, C/C++, Ruby, PHP + more |
|
||||
| **Pattern matching** | Metavariables (`$VAR`), relational queries, composite logic |
|
||||
|
||||
**When to use ast-grep**:
|
||||
|
||||
✅ **Use for**:
|
||||
- **Large-scale refactoring** (>50k lines, indicative threshold)
|
||||
- **Framework migrations** (React class→hooks, Vue 2→3)
|
||||
- **Structural patterns**:
|
||||
- Async functions lacking error handling
|
||||
- Functions exceeding parameter thresholds
|
||||
- Console.log calls within class methods
|
||||
- React components using specific hooks
|
||||
- **Architecture analysis** (identify coupled components, dependency patterns)
|
||||
|
||||
❌ **Don't use for** (grep suffices):
|
||||
- Simple string searches (function names, imports)
|
||||
- Small projects (<10k lines)
|
||||
- One-off searches
|
||||
- Text-based patterns (TODO comments, log messages)
|
||||
|
||||
**Decision Tree**:
|
||||
|
||||
```
|
||||
Search need?
|
||||
├─ String/regex pattern → Grep (native, fast)
|
||||
├─ Semantic meaning → Serena MCP (symbol search) or grepai (RAG-based)
|
||||
└─ Structural pattern (AST) → ast-grep (plugin, setup required)
|
||||
```
|
||||
|
||||
**Trade-offs**:
|
||||
|
||||
| Aspect | Grep | ast-grep | Serena MCP | grepai |
|
||||
|--------|------|----------|------------|--------|
|
||||
| **Speed** | ⚡ Fast (~20ms) | Moderate | Fast | Slower (embedding) |
|
||||
| **Setup** | ✅ None | ⚠️ Installation + learning | ⚠️ MCP config | ⚠️ MCP + Ollama |
|
||||
| **Precision** | Regex-based | AST-accurate | Symbol-aware | Semantic |
|
||||
| **Use case** | Text patterns | Code structure | Symbols/functions | Meaning-based |
|
||||
|
||||
**Example usage**:
|
||||
|
||||
```bash
|
||||
# User explicitly requests ast-grep
|
||||
You: Use ast-grep to find all async functions without try/catch blocks
|
||||
|
||||
# Claude uses the ast-grep skill to construct rules
|
||||
Claude: [Constructs AST pattern, executes search, reports results]
|
||||
```
|
||||
|
||||
**Important limitations** (as of Nov 2025):
|
||||
|
||||
> "Claude Code cannot automatically detect when to use ast-grep for all appropriate use cases." - ast-grep/claude-skill README
|
||||
|
||||
This means you must **explicitly tell Claude** to use ast-grep. It won't decide on its own.
|
||||
|
||||
**Sources**:
|
||||
- [ast-grep Documentation](https://ast-grep.github.io/advanced/prompting.html)
|
||||
- [ast-grep/claude-skill GitHub](https://github.com/ast-grep/claude-skill)
|
||||
|
||||
**Design Philosophy Context**:
|
||||
|
||||
Early Claude Code versions used RAG with Voyage embeddings for semantic search. Anthropic switched to grep-based (ripgrep) agentic search after benchmarks showed superior performance with lower operational complexity (no index sync, no security liabilities). This "Search, Don't Index" philosophy prioritizes simplicity.
|
||||
|
||||
ast-grep is a **community extension** for specialized structural searches where grep's regex approach isn't sufficient, but it's not a replacement for grep — it's a surgical tool for specific use cases.
|
||||
|
||||
**Related**: See [Section 8.4 - Server Selection Guide](#84-server-selection-guide) for choosing between grep/ast-grep/Serena/grepai.
|
||||
|
||||
### Sequential Thinking (Structured Reasoning)
|
||||
|
||||
**Purpose**: Multi-step analysis with explicit reasoning.
|
||||
|
|
@ -10565,6 +10658,127 @@ Multi-instance workflows **REQUIRE** git worktrees to avoid conflicts. Without w
|
|||
|
||||
---
|
||||
|
||||
### Advanced Tooling for Worktree Management (Optional)
|
||||
|
||||
While git worktrees are foundational, **daily productivity** improves with automation wrappers. Multiple professional teams have independently created worktree management tools—a validated pattern.
|
||||
|
||||
#### Pattern Validation: 3 Independent Implementations
|
||||
|
||||
| Team | Solution | Key Features |
|
||||
|------|----------|--------------|
|
||||
| **incident.io** | Custom bash wrapper `w` | Auto-completion, organized in `~/projects/worktrees/`, Claude auto-launch |
|
||||
| **GitHub #1052** | Fish shell functions (8 commands) | LLM commits, rebase automation, worktree lifecycle |
|
||||
| **Worktrunk** | Rust CLI (1.6K stars, 64 releases) | Project hooks, CI status, PR links, multi-platform |
|
||||
|
||||
**Conclusion**: The worktree wrapper pattern is reinvented by power users. Vanilla git is sufficient but verbose for 5-10+ daily worktree operations.
|
||||
|
||||
#### Benchmark: Wrapper vs Vanilla Git
|
||||
|
||||
| Operation | Vanilla Git | Worktrunk | Custom Wrapper |
|
||||
|-----------|-------------|-----------|----------------|
|
||||
| Create + switch | `git worktree add -b feat ../repo.feat && cd ../repo.feat` | `wt switch -c feat` | `w myproject feat` |
|
||||
| List worktrees | `git worktree list` | `wt list` (with CI status) | `w list` |
|
||||
| Remove + cleanup | `git worktree remove ../repo.feat && git worktree prune` | `wt remove feat` | `w finish feat` |
|
||||
| LLM commit msg | Manual or custom script | Built-in via `llm` tool | Custom via LLM API |
|
||||
| Setup time | 0 (git installed) | 2 min (Homebrew/Cargo) | 10-30 min (copy-paste script) |
|
||||
| Maintenance | Git updates only | Active (64 releases) | Manual (custom code) |
|
||||
|
||||
**Trade-off**: Wrappers reduce typing ~60% but add dependency. Learn git fundamentals first, add wrapper for speed later.
|
||||
|
||||
#### Option 1: Worktrunk (Recommended for Scale)
|
||||
|
||||
**What**: Rust CLI simplifying worktree management (1.6K stars, active development since 2023)
|
||||
|
||||
**Unique features not in git**:
|
||||
- **Project-level hooks**: Automate post-create, pre-remove actions
|
||||
- **LLM integration**: `wt commit` generates messages via `llm` tool
|
||||
- **CI status tracking**: See build status inline with `wt list`
|
||||
- **PR link generation**: Quick links to open PRs per worktree
|
||||
- **Path templates**: Configure worktree location pattern once
|
||||
|
||||
**Installation**:
|
||||
```bash
|
||||
# macOS/Linux
|
||||
brew install worktrunk
|
||||
|
||||
# Or via Rust
|
||||
cargo install worktrunk
|
||||
|
||||
# Windows
|
||||
winget install worktrunk
|
||||
```
|
||||
|
||||
**Typical workflow**:
|
||||
```bash
|
||||
# Create worktree + switch
|
||||
wt switch -c feature/auth
|
||||
|
||||
# Work with Claude...
|
||||
claude
|
||||
|
||||
# LLM-powered commit
|
||||
wt commit # Generates message from diff
|
||||
|
||||
# List all worktrees with status
|
||||
wt list
|
||||
|
||||
# Remove when done
|
||||
wt remove feature/auth
|
||||
```
|
||||
|
||||
**When to use**: Managing 5+ worktrees daily, want CI integration, multi-platform team (macOS/Linux/Windows).
|
||||
|
||||
**Source**: [github.com/max-sixty/worktrunk](https://github.com/max-sixty/worktrunk)
|
||||
|
||||
#### Option 2: DIY Custom Wrapper (Lightweight Alternative)
|
||||
|
||||
**What**: 10-50 lines of bash/fish/PowerShell tailored to your workflow.
|
||||
|
||||
**Examples from production teams**:
|
||||
|
||||
1. **incident.io approach** (bash wrapper):
|
||||
```bash
|
||||
# Function: w myproject feature-name claude
|
||||
# - Creates worktree in ~/projects/worktrees/myproject.feature-name
|
||||
# - Auto-completion for projects and branches
|
||||
# - Launches Claude automatically
|
||||
```
|
||||
- **ROI**: 18% improvement (30s) on API generation time
|
||||
- **Source**: [incident.io blog post](https://incident.io/blog/shipping-faster-with-claude-code-and-git-worktrees)
|
||||
|
||||
2. **GitHub #1052 approach** (Fish shell, 8 functions):
|
||||
```fish
|
||||
git worktree-llm feature-name # Create + start Claude
|
||||
git worktree-merge # Finish, commit, rebase, merge
|
||||
git commit-llm # LLM-generated commit messages
|
||||
```
|
||||
- **Author quote**: *"I now use it for basically all my development where I can use claude code"*
|
||||
- **Source**: [Claude Code issue #1052](https://github.com/anthropics/claude-code/issues/1052)
|
||||
|
||||
**When to use**: Want full control, small team (same shell), already have shell functions for git.
|
||||
|
||||
**Trade-off**: Custom scripts lack maintenance, cross-platform support, but are zero-dependency and infinitely customizable.
|
||||
|
||||
#### Recommendation: Learn → Wrapper → Scale
|
||||
|
||||
```
|
||||
Phase 1 (Weeks 1-2): Master vanilla git worktree via /git-worktree command
|
||||
└─ Understand fundamentals, safety checks, database branching
|
||||
|
||||
Phase 2 (Week 3+): Add wrapper for productivity
|
||||
├─ Worktrunk (if multi-platform, want CI status, LLM commits)
|
||||
└─ DIY bash/fish (if lightweight, team uses same shell)
|
||||
|
||||
Phase 3 (Multi-instance scale): Combine with orchestration
|
||||
└─ Worktrunk/wrapper + Headless PM for 5-10 instances
|
||||
```
|
||||
|
||||
**Philosophy**: Tools amplify knowledge. Master git patterns (this guide) before adding convenience layers. Wrappers save 5-10 minutes/day but don't replace understanding.
|
||||
|
||||
**Anthropic stance**: Official best practices recommend git worktrees (vanilla) but remain agnostic on wrappers. Choose what fits your team.
|
||||
|
||||
---
|
||||
|
||||
### Anthropic Internal Study (August 2025)
|
||||
|
||||
Anthropic studied how their own engineers use Claude Code, providing empirical data on productivity and limitations.
|
||||
|
|
|
|||
|
|
@ -243,13 +243,15 @@ deep_dive:
|
|||
multi_instance_workflows: 9583
|
||||
boris_cherny_case_study: 9617
|
||||
anthropic_study_metrics: 9721
|
||||
git_worktrees_multi_instance: 9762
|
||||
multi_instance_costs: 9796
|
||||
orchestration_frameworks: 9864
|
||||
headless_pm_framework: 9876
|
||||
multi_instance_implementation: 9934
|
||||
multi_instance_monitoring: 10016
|
||||
multi_instance_decision_matrix: 10144
|
||||
git_worktrees_multi_instance: 10634
|
||||
advanced_worktree_tooling: 10661
|
||||
anthropic_internal_study: 10782
|
||||
multi_instance_costs: 10816
|
||||
orchestration_frameworks: 10853
|
||||
headless_pm_framework: 10865
|
||||
multi_instance_implementation: 10891
|
||||
multi_instance_monitoring: 10964
|
||||
multi_instance_decision_matrix: 11037
|
||||
# External orchestration systems
|
||||
external_orchestrators:
|
||||
gas_town:
|
||||
|
|
@ -278,7 +280,7 @@ deep_dive:
|
|||
shortcuts_table: 10246
|
||||
troubleshooting: 10372
|
||||
cheatsheet: 10747
|
||||
daily_workflow: 10823
|
||||
daily_workflow: 13581
|
||||
# AI Ecosystem (Section 11, ~line 10525)
|
||||
ai_ecosystem: 10525
|
||||
ai_ecosystem_complementarity: 10527
|
||||
|
|
@ -317,10 +319,10 @@ deep_dive:
|
|||
cowork_section: "guide/ai-ecosystem.md:760"
|
||||
cowork_ultimate_guide: 10759
|
||||
# Appendix
|
||||
appendix_a_file_locations: 14087
|
||||
appendix_b_faq: 14263
|
||||
faq_clawdbot_vs_claudecode: 14265
|
||||
faq_product_managers: 14335
|
||||
appendix_a_file_locations: 14356
|
||||
appendix_b_faq: 14530
|
||||
faq_clawdbot_vs_claudecode: 14532
|
||||
faq_product_managers: 14601
|
||||
|
||||
# ════════════════════════════════════════════════════════════════
|
||||
# DECISION TREE (most important - en premier)
|
||||
|
|
@ -470,6 +472,14 @@ mcp:
|
|||
sequential: "structured multi-step reasoning"
|
||||
playwright: "browser automation / E2E"
|
||||
figma: "design file access, tokens, structure (official)"
|
||||
ast_grep: "optional plugin for AST-based code search (explicit invocation required)"
|
||||
ast_grep_guide: "guide/ultimate-guide.md:6564"
|
||||
ast_grep_skill: "examples/skills/ast-grep-patterns.md"
|
||||
ast_grep_install: "npx skills add ast-grep/agent-skill"
|
||||
ast_grep_when: "structural patterns (>50k lines, migrations, AST rules)"
|
||||
ast_grep_not_for: "simple string search, small projects (<10k lines)"
|
||||
search_decision_tree: "grep (text) | ast-grep (structure) | Serena (symbols) | grepai (semantic)"
|
||||
grep_vs_rag_history: "guide/architecture.md:33"
|
||||
check: "/mcp"
|
||||
config: ".claude/mcp.json or ~/.claude.json"
|
||||
tool_search: "lazy loading MCP tools (v2.1.7+) - 85% token reduction - auto:N threshold config"
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue