Worktrees en Claude Code: Trabajo Paralelo sin Conflictos

Los git worktrees son la tecnología subyacente que permite que múltiples agentes de Claude Code trabajen en paralelo sin pisar los cambios unos de otros. Son como tener múltiples copias de tu repositorio git en el mismo directorio padre, cada una en su propia rama. En esta guía, aprenderás cómo funcionan los worktrees y cómo Claude Code los utiliza para resolver el caos del paralelismo.

¿Qué son los Git Worktrees?

Un git worktree es una copia adicional de tu repositorio git que puede apuntar a una rama diferente. Normalmente, un repositorio git tiene un solo worktree (la carpeta principal). Con el comando git worktree add, puedes crear copias adicionales que apunten a ramas diferentes.

Beneficio clave: Puedes editar la rama A en la carpeta principal mientras simultáneamente editas la rama B en un worktree secundario. Sin cambiar de rama. Sin perder estado. Perfectamente aislado.

Antes de worktrees, si querías trabajar en dos ramas simultáneamente, tenías que:

1. Hacer stash de tus cambios en rama A
2. Cambiar a rama B
3. Trabajar
4. Cambiar de vuelta a rama A
5. Recuperar tu stash

Con worktrees, simplemente abres otra terminal y trabajas. Mucho más limpio.

Claude Code Isolation Mode

Claude Code usa worktrees internamente cuando trabajas con Agent Teams. Cuando invocas un agente con --isolation, Claude Code automáticamente:

• •Crea una rama nueva específica para ese agente
• •Genera un worktree para esa rama
• •Dirige al agente a trabajar en ese worktree
• •Cuando termina, limpia el worktree automáticamente

Para usar isolation mode manualmente, invocas Claude Code así:

claude-code --isolation feature/new-ui "Refactor the Button component"

Esto crea automáticamente:

# En tu repositorio, git crea:
.git/worktrees/
├── feature/new-ui/  <- Copia aislada en rama feature/new-ui
├── feature/api/      <- Otro agente trabajando en otra rama
└── feature/docs/     <- Tercero agente en otra rama

# La carpeta principal sigue siendo main/develop sin tocar

Crear Worktrees Manualmente

Aunque Claude Code automatiza esto, es útil entender los comandos git subyacentes:

# Crear un worktree nuevo en una rama existente
git worktree add ../my-project-feature-a feature/a

# Crear un worktree en una rama nueva
git worktree add -b feature/b ../my-project-feature-b main

# Listar todos los worktrees
git worktree list

# Trabajar en el worktree
cd ../my-project-feature-b
# ... hacer cambios ...
git add .
git commit -m "feat: new changes"

# Terminar y limpiar
cd ..
git worktree remove my-project-feature-b
# o
git worktree remove ../my-project-feature-b --force

Ventajas Arquitectónicas

Los worktrees son la razón por la cual Claude Code puede escalar a múltiples agentes paralelos sin volverte loco:

• •Sin conflictos de git: Cada agente está en su propia rama
• •Aislamiento total: Los cambios de un agente no afectan a otros hasta que haces merge
• •Merge ordenado: Cuando todos terminen, merges secuencialmente sin interferencias
• •Rollback seguro: Si un agente falla, su rama se descarta sin afectar al resto

En el módulo Worktrees Avanzado, aprenderás estrategias de merge complejas, cómo resolver conflictos cuando múltiples agentes tocan el mismo archivo, y patrones para coordinar trabajo distribuido. Los worktrees son la tecnología fundamental que hace posible el paralelismo real en Claude Code.

Dominar worktrees significa entender la arquitectura fundamental de cómo Claude Code escala. Sin ellos, trabajar con múltiples agentes sería caótico. Con ellos, es elegante, ordenado, y confiable.