Claude Code worktrees: desarrollo aislado

Claude Code integra worktrees de forma nativa. Puede crear un worktree, trabajar en él, hacer commits, y volver al directorio principal, todo sin tocar tu rama actual.

El problema que resuelven

Imagina que estás trabajando en una feature y aparece un bug urgente. Tienes dos opciones clásicas:

• Opción A: hacer stash, cambiar de rama, arreglar el bug, volver. Riesgo de perder cambios, conflictos al volver
• Opción B: clonar el repo en otro directorio. Duplicar todo el historial git, consumir disco

Los worktrees son la opción C: crear un directorio de trabajo ligero en otra rama. Sin stash, sin clonar, sin riesgo. Git comparte el directorio .git entre todos los worktrees.

Git worktree: conceptos básicos

Antes de ver cómo Claude Code usa worktrees, necesitas entender qué son a nivel de git. Si ya dominas git worktree, salta a la siguiente sección.

Qué es un worktree: Normalmente, un repositorio git tiene un solo directorio de trabajo (working tree). Ese es el directorio donde ves tus archivos. Con git worktree, puedes crear directorios de trabajo adicionales, cada uno vinculado a una rama diferente.

Cómo funciona internamente:

• Todos los worktrees comparten el mismo directorio .git (el historial)
• Cada worktree tiene su propio HEAD, index y working tree
• No puedes tener dos worktrees en la misma rama (git lo impide)
• Los commits en un worktree son visibles inmediatamente desde cualquier otro

Analogía: Piensa en tu repositorio como una biblioteca. Normalmente solo puedes tener un libro abierto a la vez (una rama). Los worktrees te permiten tener varios libros abiertos simultáneamente, cada uno en una página diferente, pero todos pertenecen a la misma biblioteca.

# Estructura típica con worktrees
mi-proyecto/              # worktree principal (main)
mi-proyecto-feature/      # worktree en rama feature/dashboard
mi-proyecto-hotfix/       # worktree en rama hotfix/login-bug

# Los tres comparten: mi-proyecto/.git/

Cómo funcionan en Claude Code

Claude Code puede usar worktrees de dos formas:

• Automática: cuando detecta que necesita trabajar en una rama separada sin afectar tu trabajo actual
• Manual: cuando le pides explícitamente que cree un worktree para aislar cambios

Internamente, Claude Code utiliza las herramientas EnterWorktree y ExitWorktree para moverse entre directorios de trabajo. Cuando entra en un worktree:

1. Crea el worktree en un directorio hermano al proyecto
2. Cambia su directorio de trabajo al nuevo worktree
3. Ejecuta todas las operaciones allí (editar, crear, borrar archivos)
4. Hace commit de los cambios en la rama del worktree
5. Sale del worktree y vuelve a tu directorio original

Tu rama principal queda intacta durante todo el proceso. No hay stash, no hay cambios sin guardar, no hay riesgo.

Crear y gestionar worktrees

La creación de worktrees con git es sencilla. Claude Code lo hace por ti, pero es útil entender los comandos:

# Crear un worktree en una nueva rama
git worktree add ../mi-proyecto-fix hotfix/login-bug

# Crear worktree desde una rama remota
git worktree add ../mi-proyecto-pr origin/feature/new-ui

# Listar worktrees activos
git worktree list

# Eliminar un worktree cuando termines
git worktree remove ../mi-proyecto-fix

# Limpiar referencias a worktrees eliminados manualmente
git worktree prune

Cada worktree es un directorio completo con todos los archivos del proyecto en el estado de la rama seleccionada. Puedes abrirlo con cualquier editor, ejecutar tests, y hacer commits independientes.

Worktrees vs branches: cuándo usar cada uno

Crear una rama y cambiar a ella (git checkout -b) vs crear un worktree (git worktree add). Ambos crean una rama, pero la experiencia es diferente:

Usa branches normales cuando:

• Vas a trabajar en una sola cosa a la vez (secuencialmente)
• No tienes cambios sin commitear en tu rama actual
• El cambio es rápido y no necesitas contexto de la rama anterior
• No necesitas comparar el resultado lado a lado

Usa worktrees cuando:

• Tienes trabajo en progreso que no quieres stashear ni commitear
• Necesitas trabajar en dos cosas a la vez (paralelamente)
• Quieres comparar dos implementaciones lado a lado
• El hotfix es complejo y puede tardar, pero no quieres bloquear tu feature
• Usas Claude Code con subagents y cada uno necesita su propio espacio aislado

Regla práctica: si vas a hacer git stash, probablemente un worktree sea mejor opción.

Workflow de desarrollo paralelo

El poder real de los worktrees aparece cuando los usas para desarrollo paralelo. Este es el workflow que uso en proyectos reales:

# Workflow: desarrollo paralelo con Claude Code

# 1. Estás trabajando en feature/dashboard (worktree principal)
# 2. Llega un bug report urgente

# Le dices a Claude Code:
> Crea un worktree para arreglar el bug de login.
 Rama: hotfix/login-fix. No toques mi trabajo actual.

# 3. Claude Code crea el worktree, entra, arregla, commitea, sale
# 4. Tú sigues en feature/dashboard como si nada

# 5. Cuando quieras, haces merge del hotfix
git merge hotfix/login-fix

# 6. Limpias el worktree
git worktree remove ../mi-proyecto-hotfix

Este workflow escala. Puedes tener 3-4 worktrees activos si trabajas en un proyecto con múltiples frentes. Cada uno aislado, cada uno con su contexto.

Ejemplos prácticos

Ejemplo 1: Hotfix sin interrumpir tu trabajo

# Le pides a Claude Code:
"Hay un bug en el login. Arréglalo en un worktree
sin tocar mi rama actual (feature/dashboard)"

# Claude Code:
# 1. Crea worktree en ../proyecto-hotfix desde main
# 2. Entra al worktree
# 3. Arregla el bug, hace commit
# 4. Sale del worktree
# 5. Tu rama feature/dashboard sigue intacta

Ejemplo 2: Probar dos enfoques en paralelo

# Explorar dos soluciones simultáneamente:
"Crea dos worktrees: uno con la solución usando Redis
y otro con la solución usando PostgreSQL.
Implementa ambos y compara rendimiento"

Ejemplo 3: Review de PR en worktree

# Revisar código de un compañero sin cambiar de rama:
"Haz checkout del PR #42 en un worktree,
analiza el código y dame un review"

Ejemplo 4: Migración gradual

# Migrar de una librería a otra sin romper nada:
"Crea un worktree en rama migrate/react-19.
Actualiza todas las dependencias y corrige los
breaking changes. Quiero poder comparar con la
versión actual."

Worktrees + Subagents: combo avanzado

La combinación de worktrees con subagents es la técnica de productividad más potente en Claude Code. Cada subagent trabaja en su propio worktree, con aislamiento total.

# Ejemplo: refactoring paralelo
"Necesito refactorizar 3 módulos independientes.
Crea un worktree por módulo y trabaja en los tres
en paralelo:
- Worktree 1: refactor/auth (módulo de autenticación)
- Worktree 2: refactor/payments (módulo de pagos)
- Worktree 3: refactor/notifications (módulo de notifs)

Cada uno debe pasar tests antes de commitear."

Lo que ocurre internamente:

1. Claude Code crea 3 worktrees
2. Lanza un subagent por worktree
3. Cada subagent trabaja en su módulo sin interferir con los otros
4. Cada uno ejecuta tests en su rama
5. Los tres pueden terminar a tiempos diferentes
6. Tú decides cuándo hacer merge de cada uno

El resultado: 3 PRs independientes, cada una testeable por separado, creadas en paralelo. Lo que tomaría 3 sesiones secuenciales se resuelve en una.

Escenarios del mundo real

Escenario 1: Sprint con múltiples features. Estás en un sprint con 4 tickets asignados. Cada uno es una feature pequeña. En lugar de hacerlos secuencialmente (branch, code, PR, siguiente), creas 4 worktrees y trabajas en todos con Claude Code. Al final del día tienes 4 PRs listas para review.

Escenario 2: Debugging en producción. Un cliente reporta un bug. Necesitas reproducirlo en la versión exacta que tiene (v2.3.1), pero estás trabajando en v2.5. Creas un worktree apuntando al tag v2.3.1, reproduces el bug, encuentras la causa, y aplicas el fix tanto en el worktree de la versión antigua como en main.

Escenario 3: Comparar rendimiento. Estás optimizando una query SQL. Creas un worktree con la implementación A (índice compuesto) y otro con la implementación B (materializar vista). Ejecutas benchmarks en ambos y comparas resultados lado a lado antes de decidir cuál mergear.

Escenario 4: Onboarding de nuevo miembro. Un nuevo desarrollador se une al equipo. Le creas un worktree en una rama de "playground" donde puede experimentar sin riesgo. Claude Code le guía dentro de ese worktree y cualquier desastre se borra sin afectar al equipo.

Limpieza y mantenimiento

Los worktrees acumulan directorios si no los limpias. Mantén tu sistema ordenado:

# Ver todos los worktrees activos
git worktree list
# Output:
# /Users/tu/proyecto       abc1234 [main]
# /Users/tu/proyecto-fix   def5678 [hotfix/login]
# /Users/tu/proyecto-feat  ghi9012 [feature/dashboard]

# Eliminar un worktree que ya no necesitas
git worktree remove ../proyecto-fix

# Si borraste el directorio manualmente (rm -rf),
# limpia las referencias huérfanas
git worktree prune

# Eliminar también la rama si ya la mergeaste
git branch -d hotfix/login

# Script de limpieza rápida (limpia todo lo mergeado)
git worktree list --porcelain | grep "branch" | \
 while read line; do
   branch=$(echo $line | cut -d'/' -f3-)
   if git branch --merged main | grep -q "$branch"; then
     echo "Candidato a limpiar: $branch"
   fi
 done

Una buena práctica: al final de cada día de trabajo, ejecuta git worktree list. Si ves worktrees que ya no necesitas, elimínalos. Un repositorio limpio es un repositorio rápido.

Buenas prácticas

• Limpia worktrees terminados: no acumules directorios. Ejecuta git worktree prune periódicamente
• Nombres descriptivos: usa ../proyecto-hotfix-login en lugar de ../wt1
• No modifiques el mismo archivo: si dos worktrees tocan el mismo archivo y luego haces merge, tendrás conflictos
• Worktree para experimentar: prueba ideas arriesgadas en un worktree. Si no funciona, borra el directorio y listo
• CI/CD: combina worktrees con ejecución headless para pipelines que prueban múltiples configuraciones en paralelo
• Commitea antes de salir: siempre haz commit (o stash) en un worktree antes de dejarlo. Cambios sin guardar en un worktree abandonado son difíciles de recuperar
• Un worktree por tarea: no reutilices worktrees para tareas diferentes. El coste de crear uno nuevo es despreciable

Preguntas frecuentes

¿Qué es un worktree en Claude Code?

Un worktree es un directorio de trabajo adicional de git que permite tener múltiples ramas checked out simultáneamente. Claude Code los usa para trabajar en cambios aislados sin afectar tu rama principal. La integración es nativa: Claude Code crea, entra, trabaja y sale de worktrees automáticamente.

¿Cuál es la diferencia entre subagents y worktrees?

Los subagents son hilos de ejecución paralelos que pueden compartir el mismo directorio. Los worktrees son directorios git separados donde cada uno tiene su propia rama. Puedes combinar ambos: un subagent por worktree para máximo aislamiento y paralelismo.

¿Los worktrees consumen más disco?

Mínimamente. Git worktrees comparten el directorio .git (que contiene todo el historial), así que solo se duplican los archivos de trabajo (el código fuente). Para un proyecto de 100MB de historial y 5MB de código, un worktree extra ocupa solo 5MB.

¿Puedo tener múltiples worktrees activos a la vez?

Sí, puedes tener tantos worktrees como necesites. La única restricción es que cada worktree debe estar en una rama diferente: no puedes tener dos worktrees apuntando a la misma rama simultáneamente.

¿Qué pasa si borro un worktree sin hacer merge?

Los commits que hiciste en ese worktree siguen existiendo en el historial de git (en la rama asociada). Solo desaparece el directorio de trabajo. Puedes recuperar los cambios haciendo checkout de esa rama en cualquier momento, ya sea en un nuevo worktree o con git checkout.

Siguiente paso

Los worktrees son una herramienta fundamental para desarrollo aislado. Combínalos con subagents para máximo paralelismo, configura settings.json para automatizar su creación, y explora modo headless para integrarlos en tus pipelines de CI/CD.

Si eres nuevo en Claude Code, empieza por la guía para principiantes antes de explorar worktrees. Son una técnica intermedia-avanzada que tiene más sentido cuando ya dominas los fundamentos.