Cursor Worktree 고급: Best-of-N과 worktrees.json

이전 글 08-worktree-merge에서는 Cursor의 자동 worktree와 Apply를 다뤘다. 이번에는 Best-of-N(같은 프롬프트를 여러 모델로 병렬 실행한 뒤 하나를 골라 Apply)과 worktrees.json(worktree 생성 시 deps 설치·마이그레이션 실행·.env 복사) 두 가지를 다룬다.

Best-of-N: 한 프롬프트, 여러 모델 동시에

Best-of-N이란: 작업 하나를 보내면 Cursor가 여러 모델을 각각 다른 worktree에서 실행하고, 모델별 변경이 “카드”로 여러 개 나옴 — 하나를 골라 Apply하는 방식.

언제 쓰나

상황	이점
어떤 모델이 코드베이스에 맞는지 모르겠음	한 번 돌려서 출력 비교, 간단 벤치마크
난제라 한 모델이 엣지 케이스를 놓칠까 봄	모델이 다르면 접근도 달라서 커버리지 확대
코드 품질 비교	같은 요청으로 스타일·구조를 나란히 비교
난이도 높아 “한 방” 성공률을 올리고 싶음	여러 모델이 각각 한 번씩 시도하고, 최선을 Apply

요약: 여러 모델이 같은 작업을 하고, 그중 하나를 고른다 — 난이도 높은 작업이나 품질을 중시할 때 유리.

사용법

Cursor에서 Agent를 시작할 때 “여러 모델” 또는 Best-of-N 옵션(현재 UI에 따름)을 선택한다. 프롬프트를 보낸 뒤 카드가 여러 개 나오면 전환해서 비교한 다음, main에 Apply할 한 장을 고른다.

같은 Best-of-N 실행에서 두 장 이상 Apply하면(예: A Apply 후 B), Cursor가 머지(충돌 해결) 또는 Full Overwrite(파일 전체 교체)를 물을 수 있다.

worktrees.json: worktree 생성 시 환경 준비

Cursor가 worktree를 만들 때 기본적으로 추적된 파일만 메인 디렉터리에서 복사하고, deps 설치·.env 복사·DB 마이그레이션은 하지 않는다.
**.cursor/worktrees.json**으로 새 worktree 생성 후 실행할 명령을 지정할 수 있다(예: npm ci, cp .env, npm run db:migrate).

설정 위치

Cursor는 다음 순서로 찾는다:

프로젝트 루트: .cursor/worktrees.json
worktree 경로

보통 프로젝트 루트에 둔다: .cursor/worktrees.json.

설정 키 3개

키	설명
`setup-worktree`	공통；OS별 키가 없으면 모든 OS에서 사용
`setup-worktree-windows`	Windows 전용；`setup-worktree` 덮어씀
`setup-worktree-unix`	macOS / Linux 전용；`setup-worktree` 덮어씀

각 키는 다음 중 하나:

문자열: 스크립트 경로(.cursor/worktrees.json이 있는 디렉터리 기준 상대)
배열: 셸 명령 목록. 순서대로 실행

예: Node 프로젝트

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

$ROOT_WORKTREE_PATH는 Cursor가 넘겨 주는 변수로 메인 작업 디렉터리를 가리킨다(예: .env 복사용).
Windows에서는 copy나 PowerShell이 필요할 수 있으니 OS별로 나눌 수 있다:

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

예: DB 마이그레이션 실행

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

복잡한 경우: 스크립트 파일 참조

명령이나 로직이 많으면 스크립트를 만들고 worktrees.json에서 참조한다:

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

스크립트는 .cursor/ 아래에 둔다(예: .cursor/setup-worktree-unix.sh). 내용은 npm ci, .env 복사, chmod, 마이그레이션 등.
Windows에서는 .ps1을 쓰고, 스크립트 안에서 메인 디렉터리 경로는 $env:ROOT_WORKTREE_PATH를 쓴다.

팁: worktree에 deps를 심링크로 넣는 건 피하기 — 메인 worktree와 충돌할 수 있음. npm ci, pnpm, bun, uv 등으로 새로 설치.

worktree 정리와 한도

Cursor는 worktree 개수를 관리해 디스크가 부풀지 않게 한다:

워크스페이스마다 최대 worktree 수(예: 20)가 있음
한도를 넘으면 가장 최근에 쓰지 않은 것부터 제거됨
정리는 워크스페이스 단위；다른 리포지토리끼리는 영향 없음

조정하려면(Cursor 버전이 지원하면) 다음 같은 설정을 찾는다:

cursor.worktreeMaxCount: 유지할 worktree 최대 개수
cursor.worktreeCleanupIntervalHours: 정리 실행 간격

정확한 키 이름은 Cursor 현재 설정에 따름.

worktree 셋업 디버깅

worktree 생성 후 deps가 안 깔렸거나 마이그레이션이 안 돌아가면, Cursor Output 패널을 열고 드롭다운에서 **「Worktrees Setup」**을 선택한다. 생성 시 실행된 명령과 에러를 볼 수 있어 worktrees.json이나 스크립트 문제 디버깅에 쓴다.

요약

Best-of-N: 같은 프롬프트를 여러 모델로 병렬 실행하고, 카드 한 장을 골라 Apply. 벤치마크·난제·품질 중시에 유리
worktrees.json: .cursor/worktrees.json에서 setup-worktree / setup-worktree-windows / setup-worktree-unix로 생성 후 명령·스크립트 실행
main에서 .env 등을 복사할 때는 $ROOT_WORKTREE_PATH(Unix) 또는 %ROOT_WORKTREE_PATH% / $env:ROOT_WORKTREE_PATH(Windows) 사용
worktree에는 한도와 자동 정리가 있음；디버깅은 Output → Worktrees Setup

다음: 10-headless-scripts — --print·--force 헤드리스 모드와 실제로 파일을 바꾸는 스크립트