git-worktree-manager

Descripción general de la skill git-worktree-manager

Qué hace git-worktree-manager

git-worktree-manager es una skill de ingeniería para trabajar con varios Git worktrees locales sin conflictos de ramas, puertos, entornos ni limpieza. Combina orientación operativa con scripts auxiliares en Python que crean worktrees preparados, asignan puertos deterministas, copian archivos de entorno locales, instalan dependencias de forma opcional y revisan worktrees obsoletos antes de eliminarlos.

Usa esta skill cuando los comandos habituales de git worktree no bastan porque cada rama necesita comportarse como una aplicación ejecutable independiente.

Mejor encaje para flujos Git en paralelo

El usuario ideal es un desarrollador, tech lead u operador de agentes de código que mantiene dos o más ramas abiertas al mismo tiempo: desarrollo de funcionalidades, hotfixes, revisión de PR, pruebas de migraciones o implementación con varios agentes. git-worktree-manager for Git Workflows es especialmente útil cuando cada agente o sesión de terminal debe ser dueño de una rama y de un runtime aislado, en lugar de compartir un único checkout.

Aporta menos valor si solo cambias de rama de vez en cuando, no ejecutas servicios locales o ya tienes un wrapper interno maduro para worktrees.

Diferenciadores clave antes de instalar

El valor práctico no se limita a “crear un worktree”. La skill añade convenciones repetibles para:

• nombres de worktrees y creación de ramas de forma determinista
• asignación de puertos sin solapamientos para app, base de datos y Redis
• sincronización de .env, .env.local, .env.development y .envrc
• detección de instalación de dependencias a partir de lockfiles comunes
• comprobaciones de limpieza para worktrees obsoletos, con cambios sin commitear o con ramas ya fusionadas
• patrones de Docker Compose para aislar servicios por worktree

Eso hace que la git-worktree-manager skill sea más operativa que un prompt genérico sobre Git worktrees.

Cómo usar la skill git-worktree-manager

Opciones de instalación de git-worktree-manager

Para una configuración de skills al estilo Claude, instala desde el repositorio con tu gestor de skills si está disponible:

npx skills add alirezarezvani/claude-skills --skill git-worktree-manager

Si la instalación es manual, copia el directorio de la skill desde:

engineering/skills/git-worktree-manager

a tu carpeta local de skills, por ejemplo ~/.claude/skills/git-worktree-manager, ~/.codex/skills/git-worktree-manager u otro directorio compatible para skills de agentes. Después de instalar, verifica que estén presentes estos archivos: SKILL.md, README.md, scripts/worktree_manager.py, scripts/worktree_cleanup.py y los dos archivos dentro de references/.

Lee primero estos archivos

Para adoptarla rápido, lee en este orden:

1. README.md para entender la forma de los comandos y la lista de herramientas.
2. SKILL.md para el flujo de trabajo previsto y la orientación sobre cuándo usarla.
3. references/port-allocation-strategy.md antes de cambiar puertos de servicios.
4. references/docker-compose-patterns.md si tu aplicación usa Compose.
5. scripts/worktree_manager.py y scripts/worktree_cleanup.py antes de confiar la automatización a un repositorio de producción.

Esto importa porque los scripts modifican checkouts reales, copian archivos de entorno y pueden instalar dependencias. Revisa los valores por defecto antes de ejecutarlos en un monorepo grande o en un repositorio con configuración local sensible.

Uso práctico de git-worktree-manager

Un flujo típico de creación y preparación es:

python scripts/worktree_manager.py \
  --repo . \
  --branch feature/api-hardening \
  --name wt-api-hardening \
  --base-branch main \
  --install-deps \
  --format text

Un flujo de revisión para limpieza es:

python scripts/worktree_cleanup.py \
  --repo . \
  --stale-days 14 \
  --format text

Ambas herramientas admiten entrada JSON mediante --input <json-file> o stdin, lo que resulta útil para automatización. Pide primero al agente que genere un plan de comandos y ejecuta el script solo después de confirmar la ruta del repositorio, el nombre de la rama, la rama base, el comportamiento de instalación de dependencias y la política de limpieza.

Patrón de prompt para obtener mejores resultados

Prompt débil:

Set up a worktree for my feature.

Prompt más sólido:

Use git-worktree-manager to prepare a new worktree for branch feature/billing-webhooks from main in repo /Users/me/app. Name it wt-billing-webhooks. I run app, Postgres, and Redis locally, so allocate non-conflicting ports and write the resulting mapping. Copy env files but do not install dependencies until I approve the command. Show the exact script command and any Docker Compose override I may need.

Esto le da a la skill información suficiente para elegir la estrategia de ramas, evitar colisiones de puertos, mantener precauciones con los archivos .env* y separar la planificación de la ejecución.

FAQ de la skill git-worktree-manager

¿git-worktree-manager es solo para agentes de IA?

No. La skill está optimizada para trabajo multiagente, pero los scripts y las convenciones también son útiles para desarrolladores humanos. El principal beneficio es la repetibilidad: cada worktree recibe una rama, un directorio, puertos, archivos de entorno copiados y una revisión de limpieza previsibles, en lugar de depender de historial de shell improvisado.

¿En qué se diferencia de git worktree sin más?

git worktree add crea otro checkout. No resuelve conflictos de aplicaciones locales. git-worktree-manager añade el flujo de trabajo que lo rodea: bloques de puertos, .worktree-ports.json, copia de archivos de entorno, instalación opcional de dependencias, recomendaciones para aislamiento con Docker Compose y comprobaciones de limpieza para ramas obsoletas o ya fusionadas.

¿Pueden usarlo principiantes de forma segura?

Sí, si lo tratan como un flujo guiado y no como un ejecutor ciego de comandos. Quienes empiezan deberían ejecutar primero operaciones de listado/revisión, usar --format text, evitar la eliminación automática e inspeccionar los comandos generados antes de ejecutarlos. El script de limpieza comprueba worktrees con cambios sin commitear, pero aun así debes entender qué ramas se pueden borrar con seguridad.

¿Cuándo no debería usar esta skill?

No la uses tal cual si tu repositorio tiene un manejo inusual de entornos, secretos que nunca deben copiarse, instalación de dependencias no estándar o puertos de servicios gestionados por una plataforma interna. En esos casos, usa la git-worktree-manager guide como patrón inicial y personaliza los scripts o los prompts antes de adoptarla.

Cómo mejorar la skill git-worktree-manager

Dale a git-worktree-manager más contexto del repositorio

Mejores entradas producen planes de worktree más seguros. Incluye:

• ruta absoluta del repositorio
• rama de destino y rama base
• nombre deseado del directorio del worktree
• gestor de paquetes o expectativas sobre lockfiles
• servicios que necesitan puertos
• si se pueden copiar archivos .env*
• si se permite instalar dependencias
• umbral de antigüedad para limpieza y rama base para comprobaciones de merge

Esto reduce las suposiciones y evita que el agente use valores por defecto que no encajan con tu aplicación.

Ajusta las convenciones de puertos y Docker Compose

La estrategia de referencia usa bases por defecto como app 3000, Postgres 5432, Redis 6379, con un incremento de 10 por worktree. Si tu stack tiene más servicios, reserva un bloque contiguo más grande. Si ejecutas infraestructura local fuera de los worktrees, desplaza los puertos base para evitar colisiones globales.

Para Docker Compose, prioriza overrides por worktree, puertos controlados por .env y nombres de proyecto únicos, por ejemplo:

docker compose -p myapp_wt_auth up -d

Esto evita colisiones de contenedores, redes, volúmenes y bases de datos entre ramas.

Vigila los modos de fallo habituales

Los problemas más comunes son secretos copiados, reutilización de puertos de base de datos por defecto, volúmenes de Docker compartidos entre migraciones incompatibles, instalación de dependencias en el runtime equivocado y eliminación de un worktree que todavía contiene trabajo sin commitear. Pide al agente que informe del estado dirty, los archivos de entorno copiados, los puertos seleccionados y las acciones de instalación después de cada ejecución.

Para la limpieza, empieza con salida solo de revisión. Activa la eliminación únicamente después de confirmar que un worktree está obsoleto, limpio y fusionado en la rama base esperada.

Itera después del primer resultado

Después del primer plan o comando, pide una revisión específica en lugar de empezar de nuevo:

Revise the git-worktree-manager command to skip dependency installation, use base branch develop, reserve ports for app, Postgres, Redis, and Mailhog, and output JSON for automation.

Así la skill se mantiene anclada a las restricciones reales del repositorio mientras mejoras la seguridad y la reproducibilidad.