Skip to content

WORKTREE-WORKFLOW-v0.4.3.md

Latest commit

 

History

History
569 lines (414 loc) · 11.1 KB

WORKTREE-WORKFLOW-v0.4.3.md

File metadata and controls

569 lines (414 loc) · 11.1 KB

Worktree Workflow Guide - v0.4.3

Guide complet pour utiliser les worktrees hybrides avec flexibilité et efficacité.

🎯 Philosophie

Principe: Start simple (Main), scale up (Worktree) when needed.

  • 🚀 Main pour quick fixes rapides
  • 🛡️ Worktree pour isolation quand nécessaire
  • 🔄 Migration facile si le fix grossit
  • 🎨 Choix à chaque étape

📦 Setup Initial (Une fois)

# Créer les worktrees permanents
$ /worktree setup

✅ worktrees/hotfix/ created
✅ worktrees/debug/ created
✅ Configuration initialized

Résultat:

claude-plugin-prd-workflow/
├── worktrees/
│   ├── hotfix/     (permanent, pour /ship --worktree)
│   └── debug/      (permanent, pour /debugging --worktree)
└── .claude/
    └── config-worktrees.json

🎨 Arbre de Décision

Quand utiliser Main vs Worktree ?

Nouveau fix à faire
      │
      ├─── Petit fix ? (< 5 fichiers, < 100 lignes, < 30 min)
      │    │
      │    └─── OUI → /ship "Fix X" (Main)
      │         │
      │         ├─── Reste petit → /ship --complete
      │         └─── Devient gros → /ship --to-worktree
      │
      └─── Gros fix ? (refactor, multi-fichiers)
           │
           └─── OUI → /ship "Fix X" --worktree
                      ou /hotfix "Fix X"

Quand utiliser Main vs Worktree pour Debug ?

Bug à investiguer
      │
      ├─── Investigation read-only ? (logs, code reading)
      │    │
      │    └─── OUI → /debugging "Issue" (Main)
      │         │
      │         ├─── Pas de fix → /debugging --resolve
      │         └─── Besoin fix → /debugging --to-worktree
      │
      └─── Reproduction / Fix nécessaire ?
           │
           └─── OUI → /debugging "Issue" --worktree

🚀 Workflows par Scenario

Scenario 1: Quick Fix Ultra-Rapide

Contexte: Typo, petit changement évident

# Sur Main
$ /ship "Fix typo in error message"

✅ Quick fix on Main
📝 Branch: quickship/fix-typo

# Modification: 1 fichier, 2 lignes
# Pas de warning

$ /ship --complete

✅ Committed
✅ PR merged
🧹 Done!

Durée: 2-5 minutes Localisation: Main uniquement

Scenario 2: Fix qui Commence Petit, Devient Gros

Contexte: Fix commence simple mais révèle plus de work

# Commence sur Main
$ /ship "Fix dark mode issues"

✅ Working on Main

# Après 15 minutes...
# 6 fichiers modifiés, 120 lignes

⚠️  LARGE FIX DETECTED
- 6 files changed
- 120 lines modified
- 18 minutes elapsed

💡 Suggest migration to worktree

$ /ship --to-worktree

🔄 Migrating to worktree...

✅ Moved to worktrees/hotfix/
📂 Branch: hotfix/fix-dark-mode
💻 Open: code worktrees/hotfix/

# Continue tranquillement dans worktree

$ /ship --complete

✅ Done from worktree!

Durée: 30-60 minutes Localisation: Main → Worktree (migration)

Scenario 3: Gros Fix Direct en Worktree

Contexte: Refactor ou changement multi-fichiers dès le départ

# Direct en worktree
$ /ship "Refactor authentication module" --worktree

🔍 Checking worktree hotfix/...
🔄 Syncing (3 commits behind)...
✅ Synced with main

✅ Started in worktrees/hotfix/
📝 Branch: hotfix/refactor-auth
🔒 Locked worktree

# Ou version courte:
$ /hotfix "Refactor authentication module"

# Développement isolé
# Pas de limites

$ /ship --complete

✅ Done!

Durée: 1-4 heures Localisation: Worktree uniquement

Scenario 4: Debugging Read-Only

Contexte: Investigation sans modifications de code

# Sur Main
$ /debugging "OAuth timeout in production"

🔍 Debugging on Main (read-only)
📝 Session: .prds/debug-sessions/2025-01-14-oauth-timeout.md

# Investigation:
# - Lecture logs
# - Analyse code
# - Check config

# Trouvé: Config issue
$ /debugging --resolve

💬 Status?
2. Resolved without fix (config issue)

✅ Documented
Root cause: Redis TTL too short
Solution: Updated prod config

Durée: 15-60 minutes Localisation: Main uniquement

Scenario 5: Debugging avec Reproduction & Fix

Contexte: Bug complexe nécessitant reproduction et fix

# En worktree
$ /debugging "Memory leak in WebSocket handler" --worktree

🔍 Checking worktree debug/...
🔄 Syncing...
✅ Synced

✅ Started in worktrees/debug/
📝 Branch: debug/memory-leak-websocket
📄 Session doc created

# Investigation:
# - Reproduction du bug
# - Tests hypothèses
# - Debug logging
# - Fix implementation

$ /debugging --resolve

💬 Status?
1. Resolved with fix

✅ Committed fix
📤 PR #236 created
📝 Session documented
🧹 Worktree cleaned up

Durée: 1-4 heures Localisation: Worktree uniquement

Scenario 6: Deux Fixes Urgents en Parallèle

Contexte: Fix en cours dans worktree, nouveau fix urgent arrive

# Fix 1 déjà en cours dans worktree
$ /ship "Fix A" --worktree
# En cours de travail...

# Fix 2 urgent arrive
$ /ship "Critical bug B" --worktree

❌ Fix already in progress in worktrees/hotfix/

Current: hotfix/fix-a
Options:
1. Complete current
2. Work on Main (quick)
3. Abort current

# Choix 2: Fix urgent sur Main
$ /ship "Critical bug B"

✅ Working on Main

# Fix rapide, pas de blocage
$ /ship --complete

✅ Done!

# Retour au fix 1
$ cd worktrees/hotfix/
$ /ship --complete

✅ Done!

Durée: Variable Localisation: Worktree + Main en parallèle

Scenario 7: Long Debug avec Pause

Contexte: Investigation longue avec interruption

# Debug session en worktree
$ /debugging "Complex race condition" --worktree

✅ Started investigation

# Après 2 heures, meeting...
$ /debugging --pause

💾 Paused
🔄 Returned to parking branch

# Lendemain matin
$ /debugging --resume

📋 Paused sessions:
1. debug/complex-race-condition (2h ago)

Resume: 1

✅ Resumed
Continue debugging!

# Trouve solution
$ /debugging --resolve

✅ Done!

Durée: Multiple sessions Localisation: Worktree avec pause/resume

🔄 Routine Quotidienne

Morning Routine

# 1. Sync worktrees avec main
$ /worktree sync

🔄 Syncing all worktrees...

worktrees/hotfix/: ✅ Synced (3 commits)
worktrees/debug/: ✅ Already up-to-date

# 2. Check status
$ /worktree status

📊 Worktree Status
hotfix: 🔓 IDLE
debug: 🔓 IDLE

# 3. Ready to work!

Evening Cleanup

# Check pour worktrees obsolètes
$ /worktree prune

# Ou laisser auto-cleanup faire son travail

📊 Matrice de Décision

Type de Tâche Durée Fichiers Commande Localisation
Typo < 5 min 1-2 /ship "Fix" Main
Small fix < 30 min 2-5 /ship "Fix" Main
Medium fix 30-60 min 5-10 /ship "Fix" → --to-worktree Main → Worktree
Large fix > 1h 10+ /ship "Fix" --worktree Worktree
Refactor > 1h Any /hotfix "Refactor" Worktree
Quick debug < 30 min 0 /debugging "Issue" Main
Complex debug > 1h Any /debugging "Issue" --worktree Worktree

🎓 Best Practices

✅ DO

  • ✅ Start simple (Main) pour quick fixes
  • ✅ Migrate vers worktree si fix grossit
  • ✅ Use worktree direct pour refactors
  • ✅ Sync worktrees chaque matin
  • ✅ Use /hotfix si préférence worktree
  • ✅ Documenter debug sessions

❌ DON'T

  • ❌ Forcer worktree pour petits fixes
  • ❌ Ignorer smart warnings sur Main
  • ❌ Oublier de sync avant gros travail
  • ❌ Laisser worktree locked longtemps
  • ❌ Skip documentation de debug

🔧 Configuration Avancée

Ajuster les Seuils

.claude/config-worktrees.json:

{
  "warnings": {
    "files_threshold": 5,        // Warning si > 5 fichiers
    "lines_threshold": 100,      // Warning si > 100 lignes
    "time_threshold_minutes": 30 // Warning après 30 min
  },
  "sync": {
    "thresholds": {
      "silent_sync_max_commits": 10,  // Sync auto < 10 commits
      "warn_sync_max_commits": 50,    // Demande si 10-50 commits
      "force_sync_min_commits": 100   // Force sync si > 100
    }
  }
}

Personnalisation par Profil

Profil "Aggressive Worktree" (toujours isolé):

{
  "warnings": {
    "files_threshold": 2,
    "lines_threshold": 50,
    "time_threshold_minutes": 15
  }
}

Profil "Lazy Sync" (sync moins fréquent):

{
  "sync": {
    "thresholds": {
      "silent_sync_max_commits": 20,
      "warn_sync_max_commits": 100,
      "force_sync_min_commits": 200
    }
  }
}

🐛 Troubleshooting

Worktree Locked mais Aucun Fix en Cours

$ /ship "Fix X" --worktree

❌ Locked

# Solution:
$ cd worktrees/hotfix/
$ git status
# Si rien en cours:
$ git checkout hotfix
$ rm .claude-lock

# Ou:
$ /ship --abort  # Force cleanup

Worktree Très Derrière Main

$ /worktree sync

⚠️  50+ commits behind!

# Force sync
$ /worktree sync --force

Migration Échoue

$ /ship --to-worktree

❌ Failed

# Vérifier:
1. Uncommitted changes? → Commit first
2. Worktree locked? → Finish current fix
3. Worktree not setup? → /worktree setup

📚 Référence Rapide

Commandes Principales

Commande Action
/worktree setup Setup initial
/worktree sync Sync tous les worktrees
/worktree status Status détaillé
/ship "Fix" Quick fix sur Main
/ship "Fix" --worktree Fix en worktree
/ship --to-worktree Migrer vers worktree
/ship --complete Terminer fix
/hotfix "Fix" Alias /ship --worktree
/debugging "Issue" Debug sur Main
/debugging "Issue" --worktree Debug en worktree

Raccourcis

# Setup rapide
alias wt-setup="/worktree setup"
alias wt-sync="/worktree sync"
alias wt-status="/worktree status"

# Fixes
alias fix="/ship"
alias fixw="/ship --worktree"
alias hf="/hotfix"

# Debug
alias dbg="/debugging"
alias dbgw="/debugging --worktree"

🎉 Exemples Réels

Exemple 1: Journée Typique

# Matin
$ /worktree sync
✅ All synced

# Fix 1 (petit)
$ /ship "Fix login typo"
$ /ship --complete
✅ Done (5 min)

# Fix 2 (moyen, devient gros)
$ /ship "Fix dark mode"
# ... travail ...
⚠️  Large fix detected
$ /ship --to-worktree
# ... continue ...
$ /ship --complete
✅ Done (45 min)

# Bug investigation
$ /debugging "API timeout"
# ... investigation ...
$ /debugging --resolve
✅ Config issue, documented

# Gros refactor
$ /hotfix "Refactor auth system"
# ... travail ...
$ /ship --complete
✅ Done (2h)

Total: 4 tâches, 3h de travail, 0 conflits

Exemple 2: Urgence Production

# Refactor en cours dans worktree
$ /hotfix "Refactor API"
# En cours...

# BUG URGENT PRODUCTION!
$ /ship "Critical security fix" --worktree

❌ Worktree busy!

# Option: Main pour urgent
$ /ship "Critical security fix"

✅ On Main
# Fix rapide
$ /ship --complete
✅ Merged! (10 min)

# Retour au refactor
$ cd worktrees/hotfix/
$ /ship --complete
✅ Done

Résultat: Urgent fix sans interrompre long refactor

Version: 0.4.3 Plugin: claude-prd-workflow Last Updated: 2025-01-14