Carpetas de funcionalidades para múltiples repositorios con Git Worktrees y Claude Code

Estás trabajando en una funcionalidad que abarca tres repositorios: una biblioteca compartida, un servicio de backend y una aplicación de frontend. Clonas el primer repo, empiezas a hacer cambios y luego te das cuenta de que el backend también necesita una actualización de API. Así que abres otra terminal, clonas otro repo y empiezas a alternar entre ambos.

Ahora multiplica eso por un equipo de agentes de programación con IA, cada uno capaz de trabajar de forma independiente. La pregunta pasa a ser: ¿cómo le das a cada agente su propio espacio de trabajo aislado en varios repos, les permites trabajar en paralelo y desmontas todo cuando se entrega la funcionalidad?

La respuesta es un patrón que llamo carpetas de funcionalidades: un directorio que agrupa git worktrees de varios repositorios bajo el nombre de una misma funcionalidad, combinado con los equipos de agentes de Claude Code para orquestar el trabajo en paralelo en todos ellos.

El problema del desarrollo en polyrepo

La mayoría de las organizaciones que superan cierto tamaño usan una arquitectura polyrepo. Cada servicio, biblioteca y aplicación vive en su propio repositorio, con su propio pipeline de CI, su propio ciclo de releases y su propio equipo.

Esto funciona bien para la autonomía. Funciona mal para los cambios transversales.

Cuando una funcionalidad requiere modificaciones coordinadas en tres repositorios, tienes tres ramas separadas, tres PRs separados y un orden de merge que debes cuidar para no romper la cadena de dependencias. La guía Well-Architected de GitHub reconoce esta fricción y recomienda patrones como conjuntos de cambios, composición basada en manifiestos y repos de integración para gestionarla.

Los datos de benchmark de Faros AI, recopilados de 320 equipos scrum, muestran que los entornos polyrepo alcanzan una mediana de tiempo de ciclo de PR de 2 horas, frente a 19 horas en los monorepos. Pero esa ventaja de velocidad desaparece cuando una misma funcionalidad afecta varios repos al mismo tiempo. El costo de coordinación consume las ganancias.

El truco de los enlaces simbólicos —clonar repos uno al lado del otro y enlazarlos a un mismo proyecto— resuelve parcialmente el problema de visibilidad. Tu editor puede ver todo el código. Pero no resuelve el aislamiento. Sigues trabajando en una rama por repo y solo puedes avanzar con una funcionalidad a la vez.

Git Worktrees: la base

Los git worktrees te permiten tener varias ramas del mismo repositorio disponibles simultáneamente, cada una en su propio directorio, compartiendo una sola base de datos de objetos .git. En lugar de guardar tu trabajo en un stash, cambiar de rama y rogar para recordar a qué corresponde cada stash, simplemente abres un directorio nuevo.

git worktree add ../my-repo-feature-x -b feature-x

Esto crea un nuevo directorio de trabajo en ../my-repo-feature-x, con una rama nueva llamada feature-x. El repo original y este worktree comparten historial, remotos y objetos. Basta con hacer fetch una vez para que ambos vean la actualización.

Las principales ventajas frente a múltiples clones:

• Una sola carpeta .git: no hay bases de datos de objetos duplicadas que consuman espacio en disco
• Fetch compartido: git fetch en un worktree actualiza todos los demás
• Aislamiento de ramas: cada worktree queda asociado a su propia rama, lo que evita la contaminación accidental entre ramas
• Limpieza instantánea: git worktree remove elimina el directorio y libera la rama

Los worktrees son estables desde Git 2.5 (2015). No tienen nada de experimental.

El patrón de carpetas de funcionalidades

La idea central es esta: para cada funcionalidad que abarque varios repos, crea un directorio principal que contenga un worktree de cada repositorio involucrado.

~/features/
  PROJ-123-user-auth/
    shared-lib/          ← worktree of github.com/org/shared-lib, branch feature/PROJ-123
    api-service/         ← worktree of github.com/org/api-service, branch feature/PROJ-123
    web-app/             ← worktree of github.com/org/web-app, branch feature/PROJ-123
    CLAUDE.md            ← project context for Claude Code agents

Cada subdirectorio es un git worktree completamente funcional, con su propia rama, sus propios archivos de trabajo y su propio historial de commits. Pero todos están agrupados bajo el nombre de una misma funcionalidad, lo que facilita abrirla completa en una sola ventana del editor o entregársela a un agente de IA que pueda ver todas las piezas.

Crear una carpeta de funcionalidad

La configuración se hace con un script de shell. Así funciona:

#!/bin/bash
FEATURE_NAME="$1"
FEATURE_DIR="$HOME/features/$FEATURE_NAME"
REPOS_DIR="$HOME/repos"

REPOS=(
  "shared-lib"
  "api-service"
  "web-app"
)

mkdir -p "$FEATURE_DIR"

for repo in "${REPOS[@]}"; do
  if [ ! -d "$REPOS_DIR/$repo/.git" ]; then
    echo "Cloning $repo..."
    git clone "git@github.com:org/$repo.git" "$REPOS_DIR/$repo"
  fi

  echo "Creating worktree for $repo..."
  cd "$REPOS_DIR/$repo"
  git fetch origin
  git worktree add "$FEATURE_DIR/$repo" -b "feature/$FEATURE_NAME"
  cd -
done

echo "Feature folder ready at $FEATURE_DIR"

Este script hace tres cosas:

1. Verifica que existan los repos bare: los clona si no existen
2. Crea un worktree por repo: cada uno obtiene su propia rama para la funcionalidad
3. Los agrupa en un directorio: la carpeta de la funcionalidad

Lo ejecutas una vez: ./feature-setup.sh PROJ-123-user-auth. Ahora tienes un espacio de trabajo aislado para esta funcionalidad en los tres repos.

Desmontar el entorno

Cuando la funcionalidad está terminada y se han hecho merge de todos los PRs:

#!/bin/bash
FEATURE_NAME="$1"
FEATURE_DIR="$HOME/features/$FEATURE_NAME"
REPOS_DIR="$HOME/repos"

REPOS=(
  "shared-lib"
  "api-service"
  "web-app"
)

for repo in "${REPOS[@]}"; do
  echo "Removing worktree for $repo..."
  cd "$REPOS_DIR/$repo"
  git worktree remove "$FEATURE_DIR/$repo" --force
  git branch -d "feature/$FEATURE_NAME" 2>/dev/null
  cd -
done

rm -rf "$FEATURE_DIR"
echo "Feature folder cleaned up."

Una eliminación limpia. Los directorios de los worktrees desaparecen, las ramas de la funcionalidad se eliminan y los repos base permanecen intactos. Sin ramas huérfanas ni directorios sobrantes.

Incorporar Claude Code

Una carpeta de funcionalidad es útil por sí sola. Se vuelve aún más potente cuando la combinas con la capacidad de Claude Code para ejecutar sesiones en paralelo.

Enfoque con un solo agente: flag Worktree

Claude Code tiene un flag integrado, --worktree, que crea sesiones aisladas en worktrees:

claude --worktree feature-auth

Esto crea un worktree en .claude/worktrees/feature-auth/ con su propia rama. Pero funciona dentro de un solo repositorio. Para trabajar con varios repos, puedes usar cd para entrar en cada worktree dentro de la carpeta de la funcionalidad e iniciar una sesión de Claude separada:

# Terminal 1
cd ~/features/PROJ-123-user-auth/shared-lib
claude

# Terminal 2
cd ~/features/PROJ-123-user-auth/api-service
claude

# Terminal 3
cd ~/features/PROJ-123-user-auth/web-app
claude

Tres sesiones independientes de Claude, cada una con el contexto completo de su propio repo, trabajando todas en la misma funcionalidad. Puedes darle instrucciones específicas a cada una y no interferirán entre sí.

Enfoque con múltiples agentes: equipos de agentes

Los equipos de agentes de Claude Code (experimentales, a marzo de 2026) van un paso más allá. En lugar de gestionar manualmente tres terminales, puedes hacer que un solo agente principal coordine a los integrantes del equipo en los tres repos.

Primero, habilita los equipos de agentes:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Luego inicia Claude desde la raíz de la carpeta de la funcionalidad con un CLAUDE.md que describa la estructura del proyecto:

# Feature: PROJ-123 User Auth

## Repositories

- `shared-lib/` — Shared TypeScript library with auth types and validation
- `api-service/` — Go backend service, handles JWT issuance and verification
- `web-app/` — React frontend, login/signup flows

## Task

Implement OAuth2 PKCE flow across all three repos.
The shared lib defines the types, the API service implements the
token exchange, and the web app handles the redirect callback.

Pídele a Claude que cree un equipo:

Create an agent team with three teammates. One for each repository
in this feature folder. Each teammate should work in its own
repository directory. Coordinate the implementation order:
shared-lib first, then api-service, then web-app.

El agente principal crea una lista de tareas compartida, inicia a los integrantes del equipo y coordina el orden de las dependencias. Cada integrante opera en su propia ventana de contexto con acceso completo a su repo.

Generar PRs

Una vez que cada agente ha hecho commit de sus cambios, generar los PRs es sencillo. Cada worktree es un repositorio git estándar con su propia rama. Puedes:

1. Pedirle a cada agente que cree un PR usando la CLI gh:

cd ~/features/PROJ-123-user-auth/shared-lib
gh pr create --title "feat: add OAuth2 PKCE types" \
  --body "Part of PROJ-123. Adds TypeScript types for PKCE flow."

2. Dejar que Claude se encargue: Claude Code puede ejecutar gh pr create como parte de su flujo de trabajo. Dile al agente principal “crea PRs para todos los repositorios” y delegará la tarea a cada integrante del equipo.

3. Usar --remote para crear PRs de forma asíncrona: inicia sesiones remotas para cada repo y déjalas trabajar:

claude --remote "Create a PR for the changes in shared-lib. Title: feat: add OAuth2 PKCE types"
claude --remote "Create a PR for the changes in api-service. Title: feat: implement PKCE token exchange"
claude --remote "Create a PR for the changes in web-app. Title: feat: add PKCE login flow"

Las tres se ejecutan simultáneamente. Supervísalas desde tu teléfono o terminal con /tasks.

El ciclo de vida completo

Este es el flujo de trabajo completo, desde el inicio de la funcionalidad hasta el desmontaje:

1. Crear la carpeta de la funcionalidad

./feature-setup.sh PROJ-123-user-auth

2. Agregar contexto del proyecto

Crea un CLAUDE.md en la raíz de la carpeta de la funcionalidad que describa los repos, la funcionalidad y el plan de implementación.

3. Iniciar los agentes de Claude

Hazlo manualmente (tres terminales) o mediante equipos de agentes desde la raíz de la carpeta de la funcionalidad.

4. Implementar, hacer commits e iterar

Cada agente trabaja en su propio worktree. Los cambios están aislados. Los commits están en las ramas de la funcionalidad. No hay interferencia entre repos.

5. Generar PRs

Cada agente crea un PR en su propio repo usando gh pr create. Los PRs pueden referenciarse entre sí en sus descripciones para que quienes los revisen entiendan la cadena de dependencias.

6. Revisar y hacer merge

Revisa los PRs en orden de dependencia: primero shared-lib, luego api-service y finalmente web-app. Haz merge de cada uno cuando se apruebe.

7. Desmontar el entorno

./feature-teardown.sh PROJ-123-user-auth

Worktrees eliminados. Ramas de la funcionalidad eliminadas. Entorno limpio.

Consideraciones prácticas

Conflictos de puertos. Si varios agentes necesitan ejecutar servidores de desarrollo, cada uno necesita su propio puerto. Configura PORT=3001, PORT=3002, etc. en el entorno de cada worktree.

Instalación de dependencias. Cada worktree necesita su propio node_modules (o equivalente). Incluye npm install / go mod download en tu script de configuración o en las instrucciones de CLAUDE.md para Claude.

Costos de tokens. Los equipos de agentes usan entre 3-7x más tokens que una sola sesión. Para una funcionalidad que abarca tres repos y un equipo de tres integrantes, espera aproximadamente 3x el consumo normal de tokens. Las tareas de investigación y revisión son buenos puntos de partida antes de comprometerte con una implementación completamente en paralelo.

Prevención de conflictos de archivos. La ventaja de este patrón es que cada agente se encarga de un repo separado, por lo que los conflictos de archivos entre agentes son imposibles. Dentro de un mismo repo, si usas worktrees para subagentes, Claude gestiona el aislamiento automáticamente con isolation: worktree.

Hooks para automatización. Claude Code admite los hooks WorktreeCreate y WorktreeRemove. Úsalos para instalar dependencias automáticamente, copiar archivos .env o ejecutar scripts de configuración cuando se crean o eliminan worktrees.

Herramientas existentes. Varias herramientas de código abierto automatizan la gestión de worktrees con hooks de ciclo de vida: wt-cli admite variables de plantilla y hooks de configuración y desmontaje, wtree (Rust) ofrece configuración mediante hooks.toml y worktree-make está diseñado específicamente para organizar ramas en múltiples repos. Cualquiera de estas herramientas puede reemplazar los scripts de shell anteriores si necesitas más funciones.

Cuándo tiene sentido este patrón

Esto no es para todos los proyectos. Destaca cuando:

• Una funcionalidad realmente abarca 2+ repositorios que no se pueden fusionar fácilmente en un monorepo
• Usas agentes de programación con IA que se benefician de espacios de trabajo aislados y paralelos
• Tu equipo ya sigue una arquitectura polyrepo y no tiene planes de cambiarla
• El costo de coordinar cambios entre repos es un cuello de botella recurrente

Si todos tus repos están en un monorepo, no necesitas carpetas de funcionalidades: simplemente usa ramas. Si los cambios entre repos son casos aislados y poco frecuentes, el esfuerzo de configuración no vale la pena. Pero si entregas regularmente funcionalidades que afectan una biblioteca compartida y dos o tres consumidores, este patrón se amortiza rápidamente.

La combinación de git worktrees y equipos de agentes de IA transforma el desarrollo en polyrepo: de un dolor de cabeza de coordinación a un flujo de trabajo que se puede ejecutar en paralelo. Los worktrees proporcionan aislamiento. La carpeta de la funcionalidad proporciona estructura. Claude Code proporciona los agentes. Y el script de desmontaje se asegura de que no quede nada atrás.

El futuro del desarrollo en múltiples repositorios no consiste en volver a los monorepos. Consiste en hacer que los flujos de trabajo polyrepo se sientan tan atómicos como los de un monorepo, con agentes de IA encargándose del trabajo pesado entre repositorios.

Fuentes:

• Git Worktrees: la guía completa — DevToolbox
• Cómo usar Git Worktrees correctamente — Ahmed El Gabri
• Git Worktrees para desarrollo en paralelo — DEV Community
• Orquestar equipos de sesiones de Claude Code — Claude Code Docs
• Flujos de trabajo comunes: Git Worktrees — Claude Code Docs
• Referencia de la CLI de Claude Code — Anthropic Docs
• Implementar Polyrepo en GitHub — GitHub Well-Architected
• Monorepo vs Polyrepo: qué muestran los datos de benchmark de PRs — Faros AI
• worktree-make — GitHub
• wt-cli — GitHub
• wtree — GitHub
• Documentación oficial de Git Worktree — git-scm.com