Cursor 내장 Worktree: 고급 사용

06-cursor-cli-with-worktree는 수동 worktree + CLI 병렬 사용을 다뤘습니다. 이번 글은 Cursor가 자동 생성하는 worktree(병렬 Agent / Apply)의 고급 사용에 초점을 둡니다: 여러 태스크 넣기, Apply에서 Merge와 Full Overwrite 선택, 충돌 해결, git worktree list로 일상 관리. 입문은 생략하고 실무로 직행합니다.

고급 시나리오 1: 여러 태스크 병렬 → 검토 후 Apply

한 기능을 여러 "서브태스크"로 나누고, 각각 Agent가 자기 worktree에서 실행. Apply는 원하는 것만 하고, 한 번에 전부가 아님.

예: "utils 리팩터", "유닛 테스트 추가", "API 문서 생성"을 동시에 하고 싶을 때:

• 서로 다른 프롬프트로 병렬 Agent 3개 시작(또는 하나씩, 각각 worktree에서)
• 끝나면 결과 3개: "리팩터"는 괜찮고, "테스트"는 손보고, "문서"는 버린다
• "리팩터" 카드만 Apply; 나머지는 Apply 안 하면 main에 머지되는 건 리팩터뿐 — 나머지 둘은 메인 디렉터리를 건드리지 않음

고급 포인트: 한 번에 전부 커밋할 필요 없음. "태스크별·카드별 Apply"가 가능하고, main에는 승인한 것만 들어감.

고급 시나리오 2: Apply에서 Merge vs Full Overwrite

Apply 시 Cursor는 깔끔하게 머지하려 합니다. 같은 Best-of-N이나 여러 번 Apply로 충돌이 나면 선택을 묻습니다:

실무에서는: 단일 태스크·단일 Agent·소수 파일 → Merge로 충분한 경우가 많음. 같은 요청을 여러 모델(Best-of-N)로 돌리고 카드 A 일부 + 카드 B 일부를 Apply → 충돌 가능성 큼; 그럴 땐 카드 한 장만 Apply하거나 Merge로 파일 단위 해결. 여러 카드에서 같은 파일 집합에 Full Overwrite를 반복하는 건 피하기 — 서로 덮어씀.

고급 시나리오 3: main에 미커밋 변경이 있을 때 동작

worktree 생성 시 Cursor는 메인 디렉터리의 추적된 변경과 새 파일을 worktree로 가져갑니다(Git에서 무시되는 파일은 안 가져감). 따라서:

• main에서 뭔가 바꾸고 커밋 안 한 상태에서 worktree Agent 시작 → Agent는 "현재 상태" 위에서 작업; Apply하면 "미커밋 변경 + Agent 변경"을 머지하게 됨
• 병렬 태스크를 깨끗한 main에서 시작하려면 먼저 git stash 또는 commit 후 worktree 생성해서 "WIP + Agent 변경"이 섞여 Apply에서 충돌 난무하는 걸 막기

반대로 쓸 수도 있음: 의도적으로 main에 WIP를 남겨 두고, 실험용 worktree를 만들고, Apply에서는 Merge로 마음에 드는 부분만 가져오기; 나머지는 worktree에 두고 Apply 안 함.

고급 시나리오 4: git worktree list로 확인·정리

Cursor가 만든 worktree는 git worktree list에 나옵니다. 경로는 보통 .cursor/worktrees/<repo>/<id> 아래:

git worktree list

습관으로 두면 좋은 것:

• Apply 후 main이 괜찮아 보이면 Cursor가 개수를 자동 관리; 목록에 worktree가 많고 디스크가 빡빡하면 Cursor 설정(예: cursor.worktreeMaxCount, 정리 간격)을 보거나, 쓰지 않는 Cursor 프로젝트 창을 닫아 오래된 worktree가 정리되게 하기
• 디버깅 시: 목록으로 "샌드박스"가 몇 개인지, 각 worktree가 어느 브랜치인지 알 수 있어 main과 Agent worktree를 혼동하지 않음

Cursor가 만든 경로에 대해서는 해당 Agent가 끝났다고 확실할 때가 아니면 git worktree remove를 수동으로 실행하지 않는 게 좋음. 그렇지 않으면 Cursor 내부 상태가 어긋날 수 있음.

고급 시나리오 5: 병렬 Agent가 같은 파일을 건드릴 때

Agent 두 개를, 하나는 src/auth/, 다른 하나는 src/api/를 수정하도록 돌리면 보통 충돌하지 않음 — 하나 Apply한 다음 다른 하나(순서는 크게 상관없음; Merge로 자동 해결되는 경우가 많음).

두 Agent가 같은 파일을 수정한 경우(예: 둘 다 package.json이나 같은 config.ts 수정):

• 첫 번째 Apply → main에 그 변경이 들어감
• 두 번째 Apply → 머지 플로우에 들어가고 충돌이 나올 수 있음
• Cursor 충돌 UI에서 "main의 이 부분, worktree의 이 부분"을 선택하거나, 두 번째 worktree 버전을 통째로 쓰려면 Full Overwrite

전략: 병렬 태스크를 설계할 때 Agent별로 파일 집합이 겹치지 않게 하기(예: 하나는 frontend 디렉터리, 하나는 backend); 그러면 손으로 충돌 해결할 일이 거의 없음.

요약

• 여러 태스크 병렬: worktree로 서브태스크 나누고, 검토한 뒤 원하는 카드만 Apply; main에는 승인한 것만 들어감
• Apply 선택: main 일부를 남기려면 Merge; worktree 파일을 채택하려면 Full Overwrite; 여러 카드에서 같은 파일에 대한 Full Overwrite 중복은 피하기
• 메인 디렉터리 상태: 미커밋 변경은 worktree로 들어감; 깨끗한 베이스로 하려면 먼저 stash/commit; 또는 의도적으로 WIP를 남겨 "실험용 worktree + 선택적 Merge"에 활용
• 관리: git worktree list로 확인하고 Cursor 정리와 맞추기; 태스크별 파일 집합을 겹치지 않게 하면 충돌이 줄어듦

다음: 09-worktree-advanced — Best-of-N 다중 모델 비교, worktrees.json, 정리 설정.