Cursor Worktree avanzado: Best-of-N y worktrees.json

El post anterior 08-worktree-merge cubrió el worktree automático de Cursor y Apply. Este profundiza en dos cosas: Best-of-N (mismo prompt, varios modelos en paralelo, luego eliges uno para Apply) y worktrees.json (instalar deps automáticamente, ejecutar migraciones, copiar .env al crear un worktree).

Best-of-N: Un prompt, varios modelos a la vez

Best-of-N significa: envías una tarea, Cursor ejecuta varios modelos en worktrees separados y obtienes varias "tarjetas", cada una con los cambios de un modelo — elige una y pulsa Apply.

¿Cuándo usar Best-of-N?

Situación	Por qué ayuda
No sabes qué modelo encaja mejor con tu código	Ejecuta una vez, compara salidas, pequeño benchmark
Problema difícil, te preocupa que un modelo pierda edge cases	Modelos distintos, enfoques distintos, más cobertura
Comparar calidad de código	Mismo request, estilo y estructura distintos lado a lado
Tarea difícil, quieres más éxito "al primer intento"	Varios modelos intentan una vez cada uno, Apply el mejor

En resumen: varios modelos hacen la misma tarea, tú eliges uno — sobre todo para tareas difíciles o cuando te importa la calidad.

Cómo usarlo

En Cursor, al iniciar un Agent elige "varios modelos" o la opción Best-of-N (según la UI actual). Tras enviar el prompt verás varias tarjetas; cambia entre ellas para comparar y Apply la que quieras a main.

Si aplicas más de una tarjeta del mismo run Best-of-N (p. ej. Apply A y luego B), Cursor puede preguntar: merge con resolución de conflictos o Full Overwrite (reemplazar el archivo entero).

worktrees.json: Preparar el entorno al crear un worktree

Cuando Cursor crea un worktree, copia por defecto los archivos rastreados del directorio principal, pero no instala deps, no copia .env ni ejecuta migraciones de BD.
Con .cursor/worktrees.json puedes indicar comandos a ejecutar tras cada worktree nuevo, p. ej. npm ci, cp .env, npm run db:migrate.

¿Dónde va la config?

Cursor busca en este orden:

Raíz del proyecto: .cursor/worktrees.json
Ruta del worktree

Suele ponerse en la raíz del proyecto: .cursor/worktrees.json.

Tres claves de config

Clave	Descripción
`setup-worktree`	Genérico; se usa en todos los OS si no hay clave por OS
`setup-worktree-windows`	Solo Windows; sobrescribe `setup-worktree`
`setup-worktree-unix`	Solo macOS / Linux; sobrescribe `setup-worktree`

Cada clave puede ser:

String: ruta a un script (relativa al directorio que contiene .cursor/worktrees.json)
Array: lista de comandos shell, ejecutados en orden

Ejemplo: proyecto Node

{
  "setup-worktree": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ]
}

$ROOT_WORKTREE_PATH lo proporciona Cursor y apunta al directorio de trabajo principal, p. ej. para copiar .env.
En Windows puede hacer falta copy o PowerShell; puedes separar por OS:

{
  "setup-worktree-unix": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ],
  "setup-worktree-windows": [
    "npm ci",
    "copy %ROOT_WORKTREE_PATH%\\.env .env"
  ]
}

Ejemplo: ejecutar migraciones de BD

{
  "setup-worktree": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env",
    "npm run db:migrate"
  ]
}

Más complejo: usar archivos de script

Para muchos comandos o lógica, usa un script y referéncialo en worktrees.json:

{
  "setup-worktree-unix": "setup-worktree-unix.sh",
  "setup-worktree-windows": "setup-worktree-windows.ps1",
  "setup-worktree": ["echo 'Using generic fallback'"]
}

Pon los scripts bajo .cursor/, p. ej. .cursor/setup-worktree-unix.sh, con npm ci, copiar .env, chmod, migraciones, etc.
En Windows usa .ps1 y en el script usa $env:ROOT_WORKTREE_PATH para la ruta del directorio principal.

Tip: evita enlazar deps con symlink en el worktree — puede chocar con el worktree principal; usa npm ci, pnpm, bun, uv, etc. para instalar fresco.

Limpieza y límites de worktree

Cursor limita el número de worktrees para no llenar el disco:

Cada workspace tiene un máximo de worktrees (p. ej. 20)
Al superar el límite se eliminan los menos usados recientemente
La limpieza es por workspace; repos distintos no se afectan

Para ajustar (si tu versión de Cursor lo permite), busca opciones como:

cursor.worktreeMaxCount: máximo de worktrees a mantener
cursor.worktreeCleanupIntervalHours: cada cuánto ejecutar limpieza

Los nombres exactos dependen de la configuración actual de Cursor.

Depurar el setup del worktree

Si tras crear un worktree no se instalaron deps o no se ejecutaron migraciones, abre el panel Output de Cursor, elige "Worktrees Setup" en el desplegable y revisa los comandos y errores ejecutados al crear — ayuda a depurar worktrees.json o problemas de scripts.

Resumen

Best-of-N: Mismo prompt, varios modelos en paralelo en worktrees separados; compara y Apply una tarjeta; útil para benchmarks, tareas difíciles y calidad
worktrees.json: En .cursor/worktrees.json usa setup-worktree / setup-worktree-windows / setup-worktree-unix para ejecutar comandos o scripts tras la creación
Usa $ROOT_WORKTREE_PATH (Unix) o %ROOT_WORKTREE_PATH% / $env:ROOT_WORKTREE_PATH (Windows) para copiar .env etc. desde main
Los worktrees tienen límite y limpieza automática; depura con Output → Worktrees Setup

Siguiente: 10-headless-scripts — Modo headless con --print, --force y scripts que realmente modifican archivos.