Git Worktrees: desarrollo en paralelo

Módulo: 9. Funciones avanzadas | Tiempo: ~25 min de teoría + 30 min de práctica

Lo esencial

Imagina que tienes dos escritorios para un mismo proyecto: en el primero escribes el código principal y en el segundo experimentas. No se estorban entre sí, y los dos agentes trabajan al mismo tiempo. Eso son los Worktrees de Git (copias de trabajo paralelas de un repositorio).

Términos de la lección: git (sistema de control de versiones), worktree (copia de trabajo paralela de un repositorio), CI/CD (Continuous Integration/Delivery, integración y entrega continuas), GitHub Actions (sistema de automatización de GitHub), workflow (flujo de trabajo), agent (agente, un ejecutor autónomo).

Conceptos clave

Git y GitHub: lo local frente a la nube
Worktree = copias de trabajo paralelas de un mismo repositorio
Dos agentes en dos ramas = desarrollo en paralelo sin conflictos
Soporte integrado en Claude Code: claude --worktree <nombre>
GitHub Actions y la automatización CI/CD (integración y entrega continuas)

Teoría

Git y GitHub: cuál es la diferencia

🎨 Imagínalo así: Git es un diario personal con el historial de cada cambio. GitHub es la caja fuerte del banco donde guardas una copia del diario. Si el diario se quema, la copia de la caja fuerte sigue ahí.

Git es un programa que vive en tu computadora. Registra todos los cambios en los archivos del proyecto y te permite:

Volver a cualquier versión anterior
Trabajar en varias ramas en paralelo
Ver quién cambió qué y cuándo

GitHub es una plataforma en la nube donde se guardan repositorios de Git. Además de guardarlos, te da:

Respaldo en la nube (si tu computadora se muere, el código se salva)
Trabajo en equipo
Pull Requests para revisar código
GitHub Actions para automatizar

En resumen: Git es tu diario personal; GitHub es la caja fuerte del banco donde guardas una copia.

Ramas y Pull Requests

🎨 Imagínalo así: una rama es como un borrador en un cuaderno aparte. Tus apuntes principales quedan intactos y en el borrador pruebas una estructura nueva. Si funciona, la pasas a los apuntes principales (merge). Si no, el borrador va a la basura.

Una rama (branch) es una línea de desarrollo paralela. Creas una rama para trabajar en una función sin romper el código principal:

bash

git checkout -b feature/payment-integration
# Ahora todos los cambios van a la rama feature/payment-integration
# La rama principal (main) queda intacta

Un Pull Request (PR) es una propuesta para fusionar los cambios de una rama en la principal. Si trabajas solo, sirve como historial de decisiones. En un equipo, es el paso obligatorio de revisión de código.

Qué son los Git Worktrees

🎨 Imagínalo así: un worktree son dos escritorios para un mismo proyecto. En uno escribes el código principal y en el otro arreglas un error. Los cajones son compartidos, pero las superficies de trabajo están separadas y no se estorban.

Normalmente tienes una sola copia de trabajo del repositorio. Los worktrees te permiten tener varias copias de trabajo a la vez, cada una en su propia rama.

Sin worktrees:

Código

my-project/          ← una carpeta, una rama
  src/
  tests/

¿Quieres cambiar a otra rama? Tienes que hacer git stash o git checkout, y pierdes el contexto de lo que estabas haciendo.

Con worktrees:

Código

my-project/              ← rama principal (main)
  src/
  tests/

my-project-feature-A/   ← rama feature-A
  src/
  tests/

my-project-hotfix/       ← rama hotfix
  src/
  tests/

Tres carpetas separadas, tres estados distintos del código, un solo repositorio por dentro.

Por qué importa con Claude Code

🎨 Imagínalo así: dos agentes en dos worktrees son como dos cirujanos en dos quirófanos. Uno hace una operación programada (la función principal) y el otro una urgente (el hotfix). Un mismo anestesiólogo atiende a los dos sin que uno sepa del otro.

Cada instancia de Claude Code trabaja con los archivos de su propia carpeta. Abre Claude Code en my-project/ y trabaja con main. Ábrelo en my-project-feature-A/ y trabaja con feature-A.

Escenario de desarrollo en paralelo:

Código

Agente 1 (en my-project/):
→ Escribe el flujo principal de procesamiento de pedidos
→ Integra la base de datos
→ Escribe las pruebas

Agente 2 (en my-project-feature-A/):
→ Al mismo tiempo desarrolla la interfaz para ver los pedidos
→ Crea los endpoints de la API
→ Documenta

Los dos trabajan AL MISMO TIEMPO, sin estorbarse

En lugar de "primero una cosa y luego la otra", trabajas en paralelo. En la práctica esto puede acortar bastante el tiempo de un proyecto.

Cómo crear y usar Worktrees

El camino más corto: la opción integrada de Claude Code. En las versiones actuales ya no hace falta crear el worktree a mano:

bash

claude --worktree feature-auth

El comando (en corto, -w) crea un worktree aislado en la carpeta .claude/worktrees/feature-auth/ sobre una rama nueva worktree-feature-auth y abre Claude ahí de inmediato. Ejecuta el mismo comando con otro nombre en otra terminal y tendrás una segunda sesión aislada. Otras cosas útiles:

Agrega .claude/worktrees/ a .gitignore para que las carpetas de worktree no aparezcan en el repositorio principal.
Un worktree es una copia limpia: los archivos secretos como .env no se copian. Para que se copien solos, pon en la raíz del proyecto un archivo .worktreeinclude (con la misma sintaxis que .gitignore).
También puedes pedirle a Claude dentro de la sesión: "trabaja en un worktree". Un subagente también se puede aislar: en su archivo agrega isolation: worktree (ver la lección Subagentes).
Al salir, Claude revisa si en el worktree hay trabajo sin guardar y te pregunta si lo conservas o lo borras.
Necesitas un repositorio de git. Documentación: code.claude.com/docs/en/worktrees.

Abajo está lo mismo hecho a mano, con el propio git. Conviene saberlo para entender qué pasa por dentro.

Paso 1: crear el worktree

bash

# En la carpeta principal del proyecto:
git worktree add ../my-project-feature-A feature-A

# Qué pasa:
# - Se crea la carpeta my-project-feature-A junto a la principal
# - Queda en la rama feature-A
# - Si la rama no existe, agrega -b: git worktree add -b feature-A ../my-project-feature-A

Paso 2: abrir Claude Code en cada carpeta

bash

# Terminal 1:
cd my-project
claude

# Terminal 2 (ventana nueva):
cd my-project-feature-A
claude

Paso 3: ver todos los worktrees activos

bash

git worktree list
# Muestra:
# /path/to/my-project          abc1234 [main]
# /path/to/my-project-feature-A  def5678 [feature-A]

Paso 4: borrar el worktree al terminar

bash

git worktree remove my-project-feature-A

GitHub Actions: automatización CI/CD

🎨 Imagínalo así: GitHub Actions es el control de calidad de una fábrica. Cada pieza (cada commit) se prueba automáticamente en el banco de pruebas (los tests). Si no pasa el control, no va al ensamblaje (el merge a main). El inspector de calidad nunca duerme.

CI/CD (Continuous Integration / Continuous Deployment) es la ejecución automática de pruebas y del despliegue cada vez que cambia el código.

GitHub Actions te permite configurarlo sin servicios adicionales:

yaml

# .github/workflows/test.yml
name: Run Tests

on:
  push:
    branches: [main, feature-*]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      # las versiones de las acciones (@v4, @v5) se actualizan de vez en cuando: revisa la página de la acción en GitHub
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Install dependencies
        run: pip install -r requirements.txt
      - name: Run tests
        run: pytest

Ahora, cada vez que haces push, GitHub ejecuta las pruebas automáticamente. Si las pruebas fallan, GitHub no deja fusionar los cambios en main (si activas la regla de protección de rama correspondiente).

Para Claude Code esto significa: el agente escribe el código, hace push a una rama, GitHub Actions ejecuta las pruebas y tú ves el resultado directo en el Pull Request, sin abrir la terminal.

Integración con Trigger.dev

Si tu proyecto usa Trigger.dev para sus flujos de trabajo, puedes configurar un despliegue automático (revisado con la documentación de Trigger.dev en octubre de 2026):

yaml

# .github/workflows/deploy.yml
name: Deploy to Trigger.dev

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy workflows
        run: npx trigger.dev@latest deploy
        env:
          TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}

Push a main → despliegue automático de los flujos en Trigger.dev. Nada de desplegar a mano.

Práctica

Tarea: poner a trabajar a dos agentes en paralelo con worktrees

Crea un repositorio nuevo o usa uno que ya tengas:

bash

mkdir parallel-demo && cd parallel-demo
git init
echo "# Parallel Demo" > README.md
git add . && git commit -m "Initial commit"

Crea un worktree para la segunda rama:

bash

git worktree add -b feature-backend ../parallel-demo-backend

Abre dos terminales:
- Terminal 1: cd parallel-demo && claude
- Terminal 2: cd parallel-demo-backend && claude
Dale a cada agente una tarea distinta:
- Agente 1: "Crea un README con la descripción del proyecto y las instrucciones de instalación"
- Agente 2: "Crea un script básico de Python main.py con una función hello_world"
Observa cómo los dos trabajan al mismo tiempo

Al terminar, fusiona los cambios:

bash

cd parallel-demo
git merge feature-backend
git worktree remove ../parallel-demo-backend

Errores comunes

1. Olvidar borrar el worktree después del merge Los worktrees acumulan carpetas en el disco. Después de fusionar la rama, bórralo siempre:

bash

git worktree remove ../my-project-feature-A
# Revisa que no queden worktrees "colgados":
git worktree list

2. Intentar abrir la misma rama en dos worktrees Git no permite tener la misma rama abierta en dos worktrees a la vez. Cada worktree = una rama distinta.

3. Editar archivos del worktree desde otro editor Si abriste el worktree en Claude Code, no edites los mismos archivos desde VS Code al mismo tiempo. Los conflictos están garantizados.

4. No crear la rama antes del worktree Si la rama todavía no existe, usa la opción -b:

bash

git worktree add -b feature-new ../my-project-new

5. Hacer merge sin revisar las pruebas Antes de fusionar desde un worktree, ejecuta las pruebas en las dos ramas. GitHub Actions lo automatiza con CI.

Herramientas y recursos

Git Worktree: documentación oficial: git-scm.com/docs/git-worktree
GitHub Actions: automatización CI/CD: docs.github.com/en/actions (gratis para repositorios públicos; para los privados hay un límite mensual gratuito de minutos; revisa los límites vigentes en la página de precios de GitHub)
Claude Code y worktrees: code.claude.com/docs/en/worktrees
GitHub CLI (gh): manejo de Pull Requests y Actions desde la terminal: cli.github.com
Skill: superpowers:using-git-worktrees: una guía más amplia de patrones con worktrees

Conclusiones clave

Un worktree no es magia. Son solo varias carpetas sobre un mismo repositorio. La fuerza está en que cada agente trabaja en su propia carpeta aislada, al mismo tiempo. GitHub Actions es tu departamento de control de calidad gratuito. Lo configuras una vez y las pruebas corren solas en cada push. El desarrollo en paralelo con agentes no es el futuro: lo tienes disponible hoy con git worktree add.

Lecciones relacionadas

Equipos de agentes: worktrees + subagentes = cada agente trabaja en su propio worktree en paralelo
Headless y CI/CD: GitHub Actions ejecuta las pruebas automáticamente con cada push desde cualquier worktree

Qué sigue

→ Headless y CI/CD: cómo ejecutar Claude Code en escenarios automáticos, sin una persona