Capítulo 2: Sesiones Paralelas con Git Worktrees

18 de enero de 2025 Por: Artiko

claude-codegitworktreesparaleloproductividaddesarrolloai

Capítulo 2: Sesiones Paralelas con Git Worktrees

Domina la técnica más poderosa para trabajar con Claude Code: ejecutar múltiples sesiones en paralelo usando Git Worktrees. Esta metodología te permite desarrollar features, corregir bugs y experimentar simultáneamente sin conflictos.

🎯 ¿Qué son los Git Worktrees?

Git Worktrees es una característica que permite tener múltiples copias de trabajo del mismo repositorio en diferentes directorios, cada una con su propia rama activa, mientras comparten el mismo historial Git.

Ventajas Clave

Aislamiento Total:
  - Cada worktree es independiente
  - Cambios aislados entre sesiones
  - Sin conflictos entre branches

Paralelización:
  - Múltiples Claude Code simultáneos
  - Desarrollo de features en paralelo
  - Testing mientras desarrollas

Eficiencia:
  - Comparten el mismo .git
  - No duplican el historial
  - Cambio instantáneo entre contextos

Comparación: Clonar vs Worktrees

// ❌ Método Tradicional: Múltiples Clones
const tradicionalMethod = {
  proyecto1: "git clone repo proyecto-feature-a",  // Clone completo
  proyecto2: "git clone repo proyecto-bugfix",      // Otro clone completo
  problemas: [
    "Duplicación del historial Git",
    "Mayor uso de disco",
    "Remotos independientes",
    "Sincronización manual"
  ]
};

// ✅ Método Moderno: Worktrees
const worktreeMethod = {
  main: "repositorio principal",
  worktree1: "git worktree add ../feature-a",  // Comparte .git
  worktree2: "git worktree add ../bugfix",      // Mismo historial
  ventajas: [
    "Un solo .git compartido",
    "Menor uso de disco",
    "Remotos compartidos",
    "Sincronización automática"
  ]
};

🚀 Configuración Inicial

Preparar el Repositorio Principal

# 1. Clonar o usar repositorio existente
git clone https://github.com/usuario/proyecto.git
cd proyecto

# 2. Verificar estado limpio
git status
# Si hay cambios, commit o stash
git stash push -m "Guardando cambios antes de worktrees"

# 3. Actualizar todas las ramas
git fetch --all

# 4. Ver estructura actual
tree -L 1
# proyecto/
# ├── src/
# ├── tests/
# ├── package.json
# └── README.md

Crear Tu Primer Worktree

# Sintaxis básica
git worktree add <ruta> <rama>

# Ejemplo 1: Crear worktree con nueva rama
git worktree add ../proyecto-feature-auth -b feature/authentication

# Ejemplo 2: Usar rama existente
git worktree add ../proyecto-bugfix-api bugfix/api-error

# Ejemplo 3: Desde un commit específico
git worktree add ../proyecto-experimento -b experimental HEAD~5

# Verificar worktrees creados
git worktree list
# /home/user/proyecto              abc123 [main]
# /home/user/proyecto-feature-auth def456 [feature/authentication]
# /home/user/proyecto-bugfix-api   ghi789 [bugfix/api-error]

💻 Workflow con Claude Code

Sesión 1: Desarrollo de Feature

# Terminal 1: Feature de autenticación
cd ../proyecto-feature-auth

# Inicializar entorno (si es necesario)
npm install  # o yarn, pip install, etc.

# Iniciar Claude Code
claude

# Prompt ejemplo:
# "Implementa un sistema de autenticación JWT con login, 
#  registro y refresh tokens. Usa bcrypt para passwords"

Sesión 2: Corrección de Bug (Paralela)

# Terminal 2: Mientras Claude trabaja en auth, abrir otra sesión
cd ../proyecto-bugfix-api

# Iniciar segunda instancia de Claude Code
claude

# Prompt ejemplo:
# "Hay un bug en el endpoint /api/users que devuelve 500.
#  Debuggea y corrige el error de validación"

Sesión 3: Experimentación (Paralela)

# Terminal 3: Experimentar con nueva librería
cd ../proyecto-experimento

# Tercera instancia de Claude Code
claude

# Prompt ejemplo:
# "Refactoriza el sistema de caché usando Redis en lugar 
#  de memoria. Compara rendimiento"

📂 Organización de Worktrees

Estructura Recomendada

workspace/
├── proyecto/                 # Repositorio principal (main)
├── proyecto-feature-auth/    # Worktree: autenticación
├── proyecto-feature-ui/      # Worktree: nuevo UI
├── proyecto-bugfix-api/      # Worktree: fix API
├── proyecto-hotfix-prod/     # Worktree: hotfix urgente
└── proyecto-experiment/      # Worktree: experimentos

# Script para crear estructura
#!/bin/bash
create_worktree_structure() {
    local base_name="proyecto"
    local features=("auth" "ui" "payments")
    local bugs=("api" "database" "cache")
    
    for feature in "${features[@]}"; do
        git worktree add "../${base_name}-feature-${feature}" -b "feature/${feature}"
    done
    
    for bug in "${bugs[@]}"; do
        git worktree add "../${base_name}-bugfix-${bug}" -b "bugfix/${bug}"
    done
}

Naming Conventions

// Convenciones de nombres para worktrees
const namingConventions = {
  feature: "proyecto-feature-{nombre}",     // Nueva funcionalidad
  bugfix: "proyecto-bugfix-{ticket}",       // Corrección de bug
  hotfix: "proyecto-hotfix-{version}",      // Fix urgente
  release: "proyecto-release-{version}",    // Preparación release
  experiment: "proyecto-exp-{concepto}",    // Experimentación
  refactor: "proyecto-refactor-{modulo}"    // Refactorización
};

// Ejemplos reales
const examples = {
  feature: "proyecto-feature-oauth2",
  bugfix: "proyecto-bugfix-JIRA-1234",
  hotfix: "proyecto-hotfix-v2.1.1",
  release: "proyecto-release-v3.0.0",
  experiment: "proyecto-exp-graphql",
  refactor: "proyecto-refactor-database"
};

🔄 Gestión de Worktrees

Comandos Esenciales

# Listar todos los worktrees
git worktree list
git worktree list --verbose  # Más detalles

# Información de un worktree específico
cd ../proyecto-feature-auth
git status
git branch

# Limpiar worktrees obsoletos
git worktree prune

# Bloquear worktree (evitar eliminación accidental)
git worktree lock ../proyecto-feature-auth

# Desbloquear
git worktree unlock ../proyecto-feature-auth

# Mover worktree a otra ubicación
git worktree move ../proyecto-feature-auth ../auth-development

# Eliminar worktree
git worktree remove ../proyecto-feature-auth
# O forzar eliminación
git worktree remove --force ../proyecto-feature-auth

Sincronización entre Worktrees

# En worktree principal
cd ~/workspace/proyecto
git pull origin main

# Los cambios están disponibles en todos los worktrees
cd ../proyecto-feature-auth
git fetch
git rebase main  # O merge según tu workflow

# Script de sincronización masiva
#!/bin/bash
sync_all_worktrees() {
    # Actualizar principal
    cd ~/workspace/proyecto
    git pull origin main
    
    # Sincronizar cada worktree
    for worktree in $(git worktree list --porcelain | grep "worktree" | cut -d' ' -f2); do
        echo "Sincronizando: $worktree"
        cd "$worktree"
        git fetch
        
        # Obtener rama actual
        branch=$(git branch --show-current)
        
        # Si no es main, rebase
        if [ "$branch" != "main" ]; then
            git rebase main || echo "Conflicto en $worktree"
        fi
    done
}

🎯 Casos de Uso Prácticos

Caso 1: Desarrollo Full-Stack Paralelo

# Frontend con Claude
git worktree add ../proyecto-frontend -b feature/react-ui
cd ../proyecto-frontend
claude
# "Crea componentes React para el dashboard con TypeScript y Tailwind"

# Backend con Claude (simultáneo)
git worktree add ../proyecto-backend -b feature/api-rest
cd ../proyecto-backend
claude
# "Implementa API REST con Node.js, Express y MongoDB"

# Base de datos con Claude (simultáneo)
git worktree add ../proyecto-database -b feature/migrations
cd ../proyecto-database
claude
# "Crea migraciones y seeds para PostgreSQL con Prisma"

Caso 2: Testing Mientras Desarrollas

# Desarrollo principal
cd ~/proyecto
claude
# "Implementa servicio de notificaciones con WebSockets"

# Testing en paralelo
git worktree add ../proyecto-testing -b testing/e2e
cd ../proyecto-testing
claude
# "Escribe tests E2E con Playwright para el servicio de notificaciones"

# Performance testing paralelo
git worktree add ../proyecto-performance -b testing/load
cd ../proyecto-performance
claude
# "Crea tests de carga con k6 para WebSockets"

Caso 3: Hotfix en Producción

# Mientras trabajas en features...
cd ~/proyecto-feature-nueva

# ¡Alerta! Bug crítico en producción
# Sin interrumpir tu trabajo actual:
git worktree add ../proyecto-hotfix -b hotfix/critical-bug origin/production

cd ../proyecto-hotfix
claude
# "URGENTE: El endpoint /api/payments está devolviendo null. 
#  Encuentra y corrige el bug inmediatamente"

# Después del fix
git push origin hotfix/critical-bug
# Crear PR para producción

# Volver a tu feature sin perder contexto
cd ../proyecto-feature-nueva
# Continuar donde lo dejaste

Caso 4: Experimentación con Tecnologías

# Versión actual con Express
cd ~/proyecto

# Experimento 1: Migrar a Fastify
git worktree add ../proyecto-exp-fastify -b experiment/fastify
cd ../proyecto-exp-fastify
claude
# "Migra el servidor de Express a Fastify manteniendo la misma API"

# Experimento 2: Probar Bun
git worktree add ../proyecto-exp-bun -b experiment/bun
cd ../proyecto-exp-bun
claude
# "Adapta el proyecto para usar Bun en lugar de Node.js"

# Comparar rendimiento
./benchmark.sh ../proyecto ../proyecto-exp-fastify ../proyecto-exp-bun

🛠️ Scripts de Automatización

Script: Gestor de Worktrees

#!/bin/bash
# worktree-manager.sh

# Colores para output
RED='\033[0;31m'
GREEN='\033[0;32m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color

# Función para crear worktree con setup
create_worktree() {
    local name=$1
    local branch=$2
    local type=${3:-feature}  # feature, bugfix, hotfix, etc.
    
    # Crear directorio según tipo
    local dir="../proyecto-${type}-${name}"
    
    echo -e "${BLUE}Creando worktree: $dir${NC}"
    git worktree add "$dir" -b "${type}/${branch}"
    
    # Setup inicial
    cd "$dir"
    
    # Instalar dependencias según el proyecto
    if [ -f "package.json" ]; then
        echo -e "${GREEN}Instalando dependencias npm...${NC}"
        npm install
    elif [ -f "requirements.txt" ]; then
        echo -e "${GREEN}Creando venv Python...${NC}"
        python -m venv venv
        source venv/bin/activate
        pip install -r requirements.txt
    elif [ -f "Gemfile" ]; then
        echo -e "${GREEN}Instalando gems...${NC}"
        bundle install
    fi
    
    # Copiar archivos de configuración local si existen
    if [ -f "../proyecto/.env.local" ]; then
        cp ../proyecto/.env.local .env.local
    fi
    
    echo -e "${GREEN}✓ Worktree creado y configurado${NC}"
    echo -e "${BLUE}Para comenzar:${NC}"
    echo "  cd $dir"
    echo "  claude"
}

# Función para listar worktrees con estado
list_worktrees() {
    echo -e "${BLUE}=== Worktrees Activos ===${NC}"
    git worktree list | while read -r line; do
        dir=$(echo "$line" | cut -d' ' -f1)
        branch=$(echo "$line" | grep -o '\[.*\]')
        
        # Verificar si hay Claude Code ejecutándose
        if pgrep -f "claude.*$dir" > /dev/null; then
            echo -e "$dir $branch ${GREEN}[Claude activo]${NC}"
        else
            echo "$dir $branch"
        fi
    done
}

# Función para limpiar worktrees terminados
cleanup_worktrees() {
    echo -e "${BLUE}Limpiando worktrees...${NC}"
    
    # Primero, prune
    git worktree prune
    
    # Buscar y eliminar directorios huérfanos
    for dir in ../proyecto-*/; do
        if [ -d "$dir/.git" ]; then
            if ! git worktree list | grep -q "$dir"; then
                echo -e "${RED}Eliminando directorio huérfano: $dir${NC}"
                rm -rf "$dir"
            fi
        fi
    done
    
    echo -e "${GREEN}✓ Limpieza completada${NC}"
}

# Función para sincronizar todos los worktrees
sync_all() {
    echo -e "${BLUE}Sincronizando todos los worktrees...${NC}"
    
    # Primero actualizar main
    original_dir=$(pwd)
    cd ~/workspace/proyecto
    git fetch --all
    git pull origin main
    
    # Luego cada worktree
    git worktree list --porcelain | grep "worktree" | cut -d' ' -f2 | while read -r worktree; do
        echo -e "${BLUE}Sincronizando: $worktree${NC}"
        cd "$worktree"
        
        branch=$(git branch --show-current)
        if [ "$branch" != "main" ]; then
            git fetch
            git rebase main || echo -e "${RED}⚠ Conflicto en $worktree${NC}"
        fi
    done
    
    cd "$original_dir"
    echo -e "${GREEN}✓ Sincronización completada${NC}"
}

# Menú principal
case "$1" in
    create)
        create_worktree "$2" "$3" "$4"
        ;;
    list)
        list_worktrees
        ;;
    cleanup)
        cleanup_worktrees
        ;;
    sync)
        sync_all
        ;;
    *)
        echo "Uso: $0 {create|list|cleanup|sync}"
        echo "  create <nombre> <rama> [tipo]  - Crear nuevo worktree"
        echo "  list                            - Listar worktrees activos"
        echo "  cleanup                         - Limpiar worktrees obsoletos"
        echo "  sync                            - Sincronizar todos los worktrees"
        ;;
esac

Script: Monitor de Sesiones Claude

#!/bin/bash
# claude-monitor.sh

# Monitorear todas las sesiones de Claude Code activas
monitor_claude_sessions() {
    clear
    echo "=== Monitor de Sesiones Claude Code ==="
    echo "Actualizado: $(date)"
    echo ""
    
    # Buscar procesos Claude
    ps aux | grep -E "[c]laude" | while read -r line; do
        pid=$(echo "$line" | awk '{print $2}')
        dir=$(pwdx "$pid" 2>/dev/null | cut -d: -f2 | xargs)
        
        if [[ $dir == *"proyecto"* ]]; then
            # Obtener branch del worktree
            branch=$(cd "$dir" 2>/dev/null && git branch --show-current)
            
            # Estado del proceso
            cpu=$(echo "$line" | awk '{print $3}')
            mem=$(echo "$line" | awk '{print $4}')
            time=$(echo "$line" | awk '{print $10}')
            
            echo "📍 Worktree: $(basename "$dir")"
            echo "   Branch: $branch"
            echo "   PID: $pid | CPU: ${cpu}% | MEM: ${mem}% | Tiempo: $time"
            echo "   Path: $dir"
            echo ""
        fi
    done
    
    # Estadísticas
    total=$(pgrep -c claude)
    echo "---"
    echo "Total sesiones Claude: $total"
}

# Actualizar cada 5 segundos
while true; do
    monitor_claude_sessions
    sleep 5
done

⚡ Tips y Mejores Prácticas

Organización Eficiente

DO:
  - Usar nombres descriptivos para worktrees
  - Mantener worktree principal en 'main' limpio
  - Crear worktree para cada feature/bug
  - Limpiar worktrees completados regularmente
  - Documentar propósito de cada worktree

DON'T:
  - No crear worktrees dentro de worktrees
  - No modificar el mismo archivo en múltiples worktrees
  - No olvidar hacer push antes de eliminar worktree
  - No acumular worktrees sin usar

Workflow Recomendado

graph LR
    A[Main Branch] --> B[Worktree Feature A]
    A --> C[Worktree Feature B]
    A --> D[Worktree Bugfix]
    
    B --> E[Claude Session 1]
    C --> F[Claude Session 2]
    D --> G[Claude Session 3]
    
    E --> H[Commit & Push]
    F --> I[Commit & Push]
    G --> J[Commit & Push]
    
    H --> K[PR/Merge]
    I --> K
    J --> K
    
    K --> A

Configuración de VS Code

// .vscode/settings.json para cada worktree
{
  "window.title": "${rootName} - ${activeEditorShort}",
  "workbench.colorCustomizations": {
    "activityBar.background": "#1a5490",  // Color único por worktree
    "titleBar.activeBackground": "#1a5490"
  },
  "terminal.integrated.cwd": "${workspaceFolder}",
  "git.enableSmartCommit": true,
  "git.postCommitCommand": "sync"
}

🚨 Troubleshooting

Problema: “fatal: branch already checked out”

# Causa: La rama ya está en uso en otro worktree
# Solución 1: Usar otra rama
git worktree add ../proyecto-nuevo -b feature/nueva-rama

# Solución 2: Encontrar dónde está la rama
git worktree list | grep "nombre-rama"

# Solución 3: Forzar (peligroso)
git worktree add --force ../proyecto-nuevo existing-branch

Problema: Worktree corrupto

# Síntomas: Error al acceder al worktree
# Solución:
git worktree prune  # Limpia referencias rotas

# Si persiste, eliminar manualmente
rm -rf ../proyecto-problemático
git worktree prune

Problema: Cambios perdidos al eliminar worktree

# Prevención: Siempre commit o stash antes de eliminar
cd ../worktree-a-eliminar
git stash push -m "Guardando antes de eliminar worktree"

# Recuperación si ya se eliminó:
# Los stashes se comparten entre worktrees
git stash list  # Ver todos los stashes
git stash apply stash@{n}  # Aplicar el stash necesario

🎯 Ejercicios Prácticos

Ejercicio 1: Setup Inicial

# 1. Crear estructura de worktrees para un proyecto
mkdir workspace && cd workspace
git clone https://github.com/tu-usuario/tu-proyecto.git proyecto
cd proyecto

# 2. Crear 3 worktrees
git worktree add ../proyecto-frontend -b feature/ui
git worktree add ../proyecto-backend -b feature/api
git worktree add ../proyecto-docs -b docs/update

# 3. Iniciar Claude en cada uno (en terminales separadas)
# Terminal 1: cd ../proyecto-frontend && claude
# Terminal 2: cd ../proyecto-backend && claude
# Terminal 3: cd ../proyecto-docs && claude

Ejercicio 2: Flujo de Hotfix

# Simular bug en producción mientras desarrollas
# 1. En tu feature worktree
cd ~/workspace/proyecto-feature
# Trabajando normalmente...

# 2. Crear hotfix worktree sin interrumpir
git worktree add ../proyecto-hotfix -b hotfix/critical origin/production

# 3. Fix rápido
cd ../proyecto-hotfix
claude
# "Corrige el error 500 en /api/users"

# 4. Push y volver a feature
git add . && git commit -m "fix: critical error in users API"
git push origin hotfix/critical
cd ../proyecto-feature
# Continuar donde lo dejaste

Ejercicio 3: Experimentación Paralela

# Probar 3 enfoques diferentes para el mismo problema
git worktree add ../proyecto-approach-1 -b exp/approach-1
git worktree add ../proyecto-approach-2 -b exp/approach-2
git worktree add ../proyecto-approach-3 -b exp/approach-3

# En cada worktree, con Claude:
# Approach 1: "Implementa caché con Redis"
# Approach 2: "Implementa caché con Memcached"
# Approach 3: "Implementa caché en memoria con Node.js"

# Comparar resultados
./benchmark-all.sh

📚 Resumen

Has aprendido a usar Git Worktrees con Claude Code para:

✅ Ejecutar múltiples sesiones de Claude en paralelo
✅ Desarrollar features simultáneamente sin conflictos
✅ Gestionar worktrees eficientemente
✅ Automatizar flujos de trabajo con scripts
✅ Resolver problemas comunes
✅ Maximizar productividad con desarrollo paralelo

🚀 Próximo Paso

Con el dominio de worktrees, puedes explorar técnicas avanzadas como:

Integración con CI/CD
Automatización con GitHub Actions
Workspaces compartidos en equipo

👉 Volver al índice del tutorial

Pro Tip: Combina worktrees con tmux o screen para mantener todas tus sesiones de Claude organizadas en una sola ventana de terminal con múltiples paneles.