Initial commit

2025-11-29 18:16:54 +08:00
commit 2eeb6e60c6
39 changed files with 10735 additions and 0 deletions
--- a/skills/git-worktree-setup/data/best-practices.md
+++ b/skills/git-worktree-setup/data/best-practices.md
@@ -0,0 +1,666 @@
+# Git Worktree Best Practices
+
+A comprehensive guide to using git worktrees effectively for parallel development with Claude Code.
+
+## Table of Contents
+
+1. [Branch Naming Conventions](#branch-naming-conventions)
+2. [Worktree Organization](#worktree-organization)
+3. [Resource Management](#resource-management)
+4. [Workflow Patterns](#workflow-patterns)
+5. [Cleanup Strategies](#cleanup-strategies)
+6. [Team Collaboration](#team-collaboration)
+7. [Performance Optimization](#performance-optimization)
+8. [Security Considerations](#security-considerations)
+
+---
+
+## Branch Naming Conventions
+
+### Recommended Patterns
+
+**Feature Branches:**
+```
+feature/descriptive-name
+feature/user-authentication
+feature/payment-integration
+feature/dashboard-redesign
+```
+
+**Bugfix Branches:**
+```
+bugfix/issue-number-description
+bugfix/123-login-redirect
+bugfix/456-memory-leak
+bugfix/789-validation-error
+```
+
+**Hotfix Branches:**
+```
+hotfix/critical-issue
+hotfix/security-patch
+hotfix/production-crash
+```
+
+**Experimental Branches:**
+```
+experiment/idea-name
+experiment/new-architecture
+experiment/performance-test
+```
+
+**Chore Branches:**
+```
+chore/dependency-updates
+chore/refactor-auth
+chore/update-docs
+```
+
+### Why Good Names Matter
+
+- **Clarity:** Instantly understand the purpose
+- **Organization:** Easy to group and filter
+- **Cleanup:** Identify old branches quickly
+- **Collaboration:** Team members know what's being worked on
+
+### Naming Anti-Patterns
+
+❌ **Avoid:**
+- Vague names: `fix`, `update`, `changes`
+- Personal names: `johns-branch`, `temp-work`
+- Dates only: `2025-09-04`, `sept-changes`
+- No context: `test`, `wip`, `tmp`
+
+✅ **Use:**
+- Descriptive: `feature/oauth-integration`
+- Issue-linked: `bugfix/1234-payment-error`
+- Purpose-clear: `experiment/graphql-migration`
+
+---
+
+## Worktree Organization
+
+### Directory Structure
+
+**Recommended: Sibling Directories**
+```
+~/projects/
+├── myapp/                    # Main worktree
+├── myapp-feature-auth/       # Feature worktree
+├── myapp-bugfix-login/       # Bugfix worktree
+└── myapp-experiment-ui/      # Experiment worktree
+```
+
+**Alternative: Dedicated Worktrees Directory**
+```
+~/projects/
+├── myapp/                    # Main worktree
+└── myapp-worktrees/          # All worktrees
+    ├── feature-auth/
+    ├── bugfix-login/
+    └── experiment-ui/
+```
+
+**Team Shared Setup:**
+```
+~/work/
+├── myapp/                    # Main (stable)
+├── myapp-review/             # For PR reviews
+├── myapp-hotfix/             # Emergency fixes
+└── myapp-current/            # Active feature work
+```
+
+### Location Best Practices
+
+✅ **Do:**
+- Keep worktrees near main repo (faster operations)
+- Use consistent naming pattern
+- Group by purpose if many worktrees
+- Document custom locations in team wiki
+
+❌ **Don't:**
+- Scatter worktrees across filesystem
+- Use deep nested paths (slow operations)
+- Mix worktrees with unrelated projects
+- Create worktrees inside other worktrees
+
+---
+
+## Resource Management
+
+### Disk Space
+
+**Understanding Space Usage:**
+```
+Main repository: 150 MB
+Each worktree:
+  - Repository files: 150 MB
+  - node_modules: 700 MB
+  - Build artifacts: 50 MB
+  Total: ~900 MB per worktree
+```
+
+**Space Management Strategies:**
+
+1. **Limit Active Worktrees**
+   - Keep 3-5 active worktrees maximum
+   - Clean up merged branches weekly
+   - Archive instead of keeping indefinitely
+
+2. **Share When Possible**
+   - Use pnpm for shared node_modules
+   - Enable yarn's zero-installs
+   - Share build caches
+
+3. **Clean Build Artifacts**
+   ```bash
+   # Clean before removing worktree
+   cd worktree-path
+   npm run clean
+   rm -rf dist/ build/ .next/
+   ```
+
+4. **Monitor Disk Usage**
+   ```bash
+   # Check worktree sizes
+   du -sh ../myapp-*
+
+   # Find largest directories
+   du -sh */ | sort -hr | head -10
+   ```
+
+### Memory Considerations
+
+**Running Multiple Claude Code Sessions:**
+- Each session: ~500MB RAM
+- 3 parallel sessions: ~1.5GB RAM
+- Keep system RAM usage < 80%
+
+**Tips:**
+- Close unused sessions
+- Restart sessions periodically
+- Use `/handoff` to preserve context
+- Monitor system performance
+
+### CPU Management
+
+**Avoid Parallel Builds:**
+```bash
+# Bad: Running builds in all worktrees simultaneously
+cd worktree1 && npm run build &
+cd worktree2 && npm run build &
+cd worktree3 && npm run build &
+
+# Good: Sequential or limited parallel
+npm run build  # One at a time
+```
+
+**Use Build Queues:**
+- Serialize resource-intensive operations
+- Limit concurrent processes
+- Use tools like `make -j2` for controlled parallelism
+
+---
+
+## Workflow Patterns
+
+### Pattern 1: Feature Development
+
+```
+1. Create worktree for feature
+   └─ git worktree add ../myapp-feature-x -b feature-x
+
+2. Develop in isolation
+   └─ cd ../myapp-feature-x && claude
+
+3. Test independently
+   └─ npm test && npm run build
+
+4. Merge when ready
+   └─ git checkout main && git merge feature-x
+
+5. Clean up
+   └─ git worktree remove ../myapp-feature-x
+```
+
+### Pattern 2: PR Review
+
+```
+1. Create worktree from PR branch
+   └─ git worktree add ../myapp-review pr-branch
+
+2. Review code with Claude Code
+   └─ cd ../myapp-review && claude
+
+3. Test changes
+   └─ npm install && npm test
+
+4. Leave feedback
+   └─ (Review in Claude Code)
+
+5. Remove when done
+   └─ git worktree remove ../myapp-review
+```
+
+### Pattern 3: Hotfix While Developing
+
+```
+Current state: Working on feature-x in worktree
+
+1. Create hotfix worktree from main
+   └─ git worktree add ../myapp-hotfix -b hotfix-critical
+
+2. Fix issue in hotfix worktree
+   └─ cd ../myapp-hotfix && claude
+
+3. Test and deploy
+   └─ npm test && deploy
+
+4. Continue feature work
+   └─ cd ../myapp-feature-x
+
+5. Merge hotfix to both main and feature
+   └─ git checkout feature-x && git merge main
+```
+
+### Pattern 4: Integration Testing
+
+```
+1. Create worktrees for all features
+   └─ Batch create: feature-a, feature-b, feature-c
+
+2. Test each independently
+   └─ Parallel Claude Code sessions
+
+3. Create integration worktree
+   └─ git worktree add ../myapp-integration -b integration
+
+4. Merge all features to integration
+   └─ git merge feature-a feature-b feature-c
+
+5. Test combined functionality
+   └─ npm test && npm run e2e
+
+6. Clean up all worktrees after merge
+```
+
+### Pattern 5: Comparison Testing
+
+```
+1. Keep main worktree as baseline
+2. Create feature worktree for new implementation
+3. Run same tests in both
+4. Compare results side-by-side
+5. Make decision based on data
+```
+
+---
+
+## Cleanup Strategies
+
+### Daily Cleanup
+
+**Check merged branches:**
+```bash
+# List merged branches
+git branch --merged main | grep -v "main"
+
+# Remove worktrees for merged branches
+for branch in $(git branch --merged main | grep -v "main"); do
+  git worktree remove ../myapp-$branch 2>/dev/null || true
+  git branch -d $branch
+done
+```
+
+### Weekly Cleanup
+
+**Review all worktrees:**
+```bash
+# List all worktrees with age
+git worktree list | while read path commit branch; do
+  cd "$path"
+  age=$(git log -1 --format=%ar)
+  echo "$branch: last activity $age"
+done
+```
+
+**Remove stale worktrees (30+ days):**
+```bash
+# Manual review first, then remove
+git worktree list | grep -v main | while read path; do
+  cd "$path"
+  last_commit=$(git log -1 --format=%ct)
+  current_time=$(date +%s)
+  days_old=$(( (current_time - last_commit) / 86400 ))
+
+  if [ $days_old -gt 30 ]; then
+    echo "Stale: $path ($days_old days old)"
+  fi
+done
+```
+
+### Automated Cleanup
+
+**Git hooks for cleanup:**
+```bash
+# .git/hooks/post-merge
+#!/bin/bash
+# Auto-cleanup merged branches
+
+CURRENT_BRANCH=$(git branch --show-current)
+
+if [ "$CURRENT_BRANCH" = "main" ]; then
+  echo "Checking for merged worktrees..."
+
+  git branch --merged main | grep -v "main" | while read branch; do
+    # Check if worktree exists
+    if git worktree list | grep -q "\\[$branch\\]"; then
+      echo "Found merged worktree: $branch"
+      echo "Run: git worktree remove /path/to/$branch"
+    fi
+  done
+fi
+```
+
+### Cleanup Checklist
+
+Before removing a worktree:
+- [ ] No uncommitted changes
+- [ ] Branch merged or backed up
+- [ ] No important local files
+- [ ] Dependencies can be reinstalled
+- [ ] No running processes
+
+---
+
+## Team Collaboration
+
+### Shared Worktree Conventions
+
+**Team Standards Document:**
+```markdown
+# Worktree Standards
+
+## Naming
+- Features: feature/{jira-id}-{description}
+- Bugfixes: bugfix/{issue-id}-{description}
+- Reviews: review-{pr-number}
+
+## Location
+- All worktrees in ~/projects/myapp-worktrees/
+
+## Lifecycle
+- Create: Before starting work
+- Update: Sync with main daily
+- Remove: Within 24h of merge
+
+## Resources
+- Max 3 active worktrees per developer
+- Clean up merged branches in daily standup
+```
+
+### Communication
+
+**Notify team of worktrees:**
+```bash
+# In team chat
+Working on worktrees:
+- feature-auth (for AUTH-123)
+- bugfix-login (for BUG-456)
+- review-pr-789 (reviewing Sarah's PR)
+
+Will clean up by EOD.
+```
+
+### Shared Scripts
+
+**Team cleanup script:**
+```bash
+#!/bin/bash
+# team-worktree-status.sh
+
+echo "Worktree Status for $(whoami)"
+echo "================================"
+
+git worktree list | while read path commit branch; do
+  cd "$path"
+  status=$(git status --porcelain | wc -l)
+  behind=$(git rev-list --count HEAD..origin/main 2>/dev/null || echo "N/A")
+
+  echo "$branch:"
+  echo "  Changes: $status"
+  echo "  Behind main: $behind"
+  echo "  Path: $path"
+  echo ""
+done
+```
+
+---
+
+## Performance Optimization
+
+### Git Operations
+
+**Fetch Once, Use Everywhere:**
+```bash
+# In main worktree
+git fetch --all
+
+# All worktrees automatically have access
+# No need to fetch in each worktree
+```
+
+**Shallow Clones for Reviews:**
+```bash
+# For temporary review worktrees
+git worktree add --detach ../review-pr HEAD
+cd ../review-pr
+git fetch origin pull/123/head:pr-123
+git checkout pr-123
+```
+
+### Build Performance
+
+**Share Build Caches:**
+```bash
+# In main repo
+export TURBO_CACHE_DIR=/shared/turbo-cache
+
+# All worktrees use same cache
+# Builds are faster after first run
+```
+
+**Incremental Builds:**
+```bash
+# Don't clean between branches
+npm run build  # Uses previous cache
+
+# Only clean when needed
+npm run clean && npm run build
+```
+
+### Dependency Management
+
+**pnpm (Recommended for Worktrees):**
+```bash
+# Global store, minimal duplication
+pnpm install
+
+# All worktrees reference same packages
+# Saves ~80% disk space
+```
+
+**npm/yarn (Standard):**
+```bash
+# Each worktree has full node_modules
+# More disk space, complete isolation
+npm install
+```
+
+---
+
+## Security Considerations
+
+### Environment Variables
+
+**Never commit .env:**
+```bash
+# Each worktree needs own .env
+cp ../.env .env
+
+# Add to .gitignore (should already be there)
+echo ".env" >> .gitignore
+```
+
+**Worktree-specific configs:**
+```bash
+# Different API endpoints per worktree
+# main: production API
+# feature-x: staging API
+# experiment: local API
+
+# .env in each worktree
+API_URL=https://staging.api.example.com
+```
+
+### Credentials
+
+**Don't share credentials between worktrees:**
+- Separate SSH keys if needed
+- Different tokens per environment
+- Revoke credentials in removed worktrees
+
+**Clean credentials before removal:**
+```bash
+# Before removing worktree
+cd worktree-path
+rm -f .env .env.local
+rm -f config/credentials.json
+
+# Then remove
+git worktree remove $(pwd)
+```
+
+### Access Control
+
+**Workspace Permissions:**
+```bash
+# Ensure proper permissions
+chmod 700 ~/projects/myapp-*
+
+# No group/other access to sensitive worktrees
+```
+
+---
+
+## Advanced Tips
+
+### Worktree Templates
+
+**Quick setup script:**
+```bash
+#!/bin/bash
+# new-worktree.sh
+
+BRANCH=$1
+PATH=../myapp-$BRANCH
+
+git worktree add $PATH -b $BRANCH
+cd $PATH
+cp ../.env .
+pnpm install
+code .  # Open in editor
+
+echo "Worktree ready: $PATH"
+```
+
+### Automation
+
+**Auto-sync worktrees:**
+```bash
+# cron job: daily sync
+0 9 * * * cd ~/projects/myapp && git fetch && \
+  for wt in $(git worktree list | awk '{print $1}'); do \
+    cd $wt && git pull --rebase 2>/dev/null; \
+  done
+```
+
+### Monitoring
+
+**Disk space alerts:**
+```bash
+# Alert when worktrees exceed threshold
+TOTAL=$(du -sm ~/projects/myapp-* | awk '{sum+=$1} END {print sum}')
+
+if [ $TOTAL -gt 10000 ]; then
+  echo "Warning: Worktrees using ${TOTAL}MB"
+fi
+```
+
+---
+
+## Quick Reference
+
+### Commands
+
+```bash
+# Create
+git worktree add ../myapp-branch -b branch
+
+# List
+git worktree list
+
+# Remove
+git worktree remove ../myapp-branch
+
+# Prune orphaned
+git worktree prune
+
+# Repair if corrupted
+git worktree repair
+
+# Move worktree
+git worktree move old-path new-path
+
+# Lock (prevent removal)
+git worktree lock path
+
+# Unlock
+git worktree unlock path
+```
+
+### Aliases
+
+```bash
+# Add to ~/.gitconfig
+[alias]
+  wt = worktree
+  wtl = worktree list
+  wta = "!f() { git worktree add ../$(basename $(pwd))-$1 -b $1; }; f"
+  wtr = worktree remove
+  wtp = worktree prune
+```
+
+**Usage:**
+```bash
+git wta feature-x          # Creates ../myapp-feature-x
+git wtl                    # Lists all worktrees
+git wtr ../myapp-feature-x # Removes worktree
+```
+
+---
+
+## Summary
+
+**Key Takeaways:**
+
+1. **Use descriptive branch names** - Future you will thank you
+2. **Keep worktrees organized** - Consistent location pattern
+3. **Monitor disk space** - Limit active worktrees
+4. **Clean up regularly** - Don't hoard merged branches
+5. **Document team conventions** - Everyone follows same patterns
+6. **Optimize for performance** - Use pnpm, shared caches
+7. **Secure sensitive data** - Clean .env before removal
+8. **Automate repetitive tasks** - Scripts for common operations
+
+**Remember:** Git worktrees are powerful tools for parallel development. Used well, they enhance productivity. Used poorly, they create chaos. Follow these best practices for worktree success!