Git worktrees con Claude Code para trabajar en paralelo

Hola, bienvenido. En la lección anterior cerramos la sección de subagentes con los 4 agentes de claude-tasks, y con esta lección empezamos la sección de trabajo en paralelo. Vamos a darle a Claude su propia copia del proyecto con claude --worktree, para que implemente una feature sin tocar la carpeta en la que trabajas tú. Prepararemos el proyecto con .gitignore, worktree.baseRef y .worktreeinclude, implementaremos en el worktree un endpoint para actualizar el perfil del usuario, lo verificaremos, integraremos la rama y limpiaremos. Y para terminar veremos cómo crear worktrees a mano con Git.

¿Por qué hace falta? Porque en la lección Retomar y bifurcar sesiones en Claude Code vimos que bifurcar separa las conversaciones, pero las 2 sesiones siguen en la misma carpeta: editan los mismos archivos, sus diffs se mezclan y una puede pisar el trabajo de la otra sin que te des cuenta. Un worktree va un paso más allá y separa también los archivos, así que 2 sesiones pueden trabajar a la vez sin pisarse.

Además, en un proyecto Laravel con Sail un worktree tiene sus particularidades, que la documentación de Claude Code no cubre porque no sabe nada de tu stack. Un worktree no trae vendor/, ni el .env, ni contenedores propios, y eso afecta a lo que Claude puede hacer dentro y a los hooks que montamos en la sección de hooks. Esa parte, la que es propia de Sail, es la que más espacio ocupa en esta lección.

Para seguir esta lección necesitas claude-tasks con los commits de las lecciones de subagentes y sin cambios pendientes, los contenedores de Sail levantados y 2 terminales abiertas en la raíz del proyecto: una para Claude Code y otra para ti. Todo lo que veremos funciona en la 2.1.283, la versión del curso, y te indico la versión mínima cuando la documentación la da.

Un worktree de Git es otra carpeta de trabajo del mismo repositorio, con sus propios archivos y su propia rama, que comparte con tu copia principal el historial y la carpeta .git. Si cada sesión de Claude Code trabaja en su propio worktree, lo que edita una no toca los archivos de la otra, así que una sesión puede construir una feature mientras otra corrige un bug, y tú sigues en tu carpeta de siempre.

Claude Code lo crea por ti con la opción --worktree, o su forma corta -w, seguida de un nombre:

Ese comando crea la carpeta .claude/worktrees/profile/ dentro del repositorio, con una rama nueva que se llama worktree-profile, y abre la sesión de Claude ya dentro de esa carpeta. Si omites el nombre, Claude Code genera uno. Y si lo que quieres es partir de una pull request, puedes pasarle su número con # delante, entre comillas para que tu shell no lo lea como un comentario, como claude --worktree "#1234".

Un worktree, además, es un checkout limpio. Solo contiene lo que está en un commit de la rama de la que parte, así que ni los cambios que tengas sin confirmar en tu carpeta ni los archivos que ignora Git, como vendor/ o el .env, llegan a él. De esas 2 ausencias sale todo lo demás de esta lección.