Worktree integrado de Cursor: uso avanzado

06-cursor-cli-with-worktree cubre worktree + CLI manual en paralelo; este post se centra en el uso avanzado de los worktrees que Cursor crea automáticamente (Agent paralelo / Apply): cómo encolar varias tareas, si fusionar o sobrescribir por completo en Apply, resolver conflictos y usar git worktree list para el día a día. Saltamos la intro y vamos directo a la práctica.

Escenario avanzado 1: Varias tareas en paralelo, revisar y luego Apply

Una funcionalidad puede dividirse en varias "sub-tareas", cada una ejecutada por un Agent en su worktree; solo aplicas las que quieras, no todas a la vez.

Ejemplo: Quieres hacer "refactor utils", "añadir tests unitarios" y "generar docs API" a la vez:

• Arranca tres Agents en paralelo (o uno tras otro, cada uno en un worktree) con prompts distintos
• Al terminar tienes tres resultados: quizá "refactor" está bien, "tests" necesitan retoques, "docs" los descartas
• Aplica solo la tarjeta "refactor"; deja las otras sin aplicar para que solo el refactor se fusione en main — las otras dos no tocan el directorio principal

Punto avanzado: No tienes que commitear todo de golpe; puedes "Apply por tarea, Apply por tarjeta", y main solo recibe lo que has aceptado.

Escenario avanzado 2: ¿Merge o Full Overwrite en Apply?

En Apply, Cursor intenta fusionar limpiamente. Si el mismo Best-of-N o varios Apply generan conflictos, preguntará:

En la práctica: una tarea, un Agent, pocos archivos → merge suele funcionar. El mismo request con varios modelos (Best-of-N) y aplicas parte de la tarjeta A y parte de la B → es fácil que haya conflictos; entonces o aplicas solo una tarjeta o usas merge y resuelves archivo a archivo. Evita Full Overwrite sobre el mismo conjunto de archivos de varias tarjetas — se sobrescribirían entre sí.

Escenario avanzado 3: Comportamiento cuando main tiene cambios sin commit

Al crear un worktree, Cursor lleva cambios rastreados y archivos nuevos del directorio principal al worktree (los ignorados por Git no). Así que:

• Cambias algo en main y no haces commit, luego arrancas un Agent en worktree → el Agent trabaja sobre tu "estado actual"; al Apply de vuelta, fusionas "tus cambios sin commit + cambios del Agent"
• Si quieres que las tareas paralelas partan de un main limpio, ejecuta git stash o haz commit antes, luego crea el worktree, para no mezclar "WIP + cambios del Agent" y tener más conflictos en Apply

Puedes usar esto al revés: adrede deja algo de WIP en main, crea un worktree para cambios experimentales, y en Apply usa merge para traer solo lo que te interesa; deja el resto en el worktree y no apliques.

Escenario avanzado 4: Inspeccionar y limpiar con git worktree list

Los worktrees creados por Cursor aparecen en git worktree list; las rutas suelen estar bajo .cursor/worktrees/<repo>/<id>:

git worktree list

Buenas prácticas:

• Tras Apply y cuando main esté bien, Cursor gestiona el número automáticamente; si la lista tiene muchos worktrees y el disco va justo, revisa la configuración de Cursor (p. ej. cursor.worktreeMaxCount, intervalo de limpieza) o cierra ventanas de proyecto no usadas para que se limpien worktrees viejos
• Al depurar: la lista muestra cuántos "sandboxes" hay y en qué rama está cada uno, para no confundir main con worktrees del Agent

Evita ejecutar git worktree remove a mano en rutas creadas por Cursor salvo que sepas que ese Agent ha terminado; si no, el estado interno de Cursor puede desincronizarse.

Escenario avanzado 5: Cuando Agents paralelos tocan los mismos archivos

Si ejecutas dos Agents, uno cambiando src/auth/ y otro src/api/, normalmente no conflictúan — aplica uno y luego el otro (el orden importa poco; el merge suele resolverse solo).

Si ambos Agents modifican el mismo archivo (p. ej. ambos tocan package.json o el mismo config.ts):

• Aplica el primero → main tiene esos cambios
• Aplica el segundo → entras en el flujo de merge y puede haber conflictos
• Usa la UI de conflictos de Cursor para elegir "quedarse con esta parte de main, esta del worktree", o si quieres la versión entera del segundo worktree, usa Full Overwrite

Estrategia: Al planificar tareas paralelas, intenta que los conjuntos de archivos no se solapen por Agent (p. ej. un dir frontend, un dir backend); así rara vez tendrás que resolver conflictos a mano.

Resumen

• Varias tareas en paralelo: Divide en sub-tareas por worktree, revisa y aplica solo las tarjetas que quieras; main solo recibe lo aceptado
• Elección en Apply: Usa Merge para conservar parte de main; usa Full Overwrite cuando el archivo del worktree debe ganar; evita Full Overwrite repetido sobre los mismos archivos de varias tarjetas
• Estado del directorio principal: Los cambios sin commit se llevan al worktree; para una base limpia, stash/commit antes; o deja WIP a propósito para "worktree experimental + merge selectivo"
• Gestión: Usa git worktree list para inspeccionar y alinearte con la limpieza de Cursor; mantén conjuntos de archivos por tarea no solapados para reducir conflictos

Siguiente: 09-worktree-advanced — Best-of-N multi-modelo, worktrees.json y limpieza.