Cursor와 Git Worktree로 멀티 에이전트 병렬 개발하기

여러분, AI 코딩 에이전트를 한 개만 띄워서 쓰는 경우는 생각보다 드뭅니다. 저도 보통 두세 개를 띄워두고 작업을 병렬로 시키는 편인데요. 그런데 이렇게 여러 에이전트를 동시에 돌리기 시작하면 가장 먼저 부딪히는 문제가 충돌입니다. 한 에이전트가 기능 개발을 하고 있는데 다른 에이전트에게 급한 버그 수정을 맡기고 싶을 때가 있죠. 그런데 같은 작업 디렉토리에서 여러 브랜치를 오가면 변경 사항이 섞이고, git stash와 브랜치 전환을 반복해야 합니다.

결론부터 말하면, 이 문제를 깔끔하게 풀어주는 게 Git Worktree입니다. 하나의 Git 저장소에서 여러 작업 디렉토리를 만들어 각 디렉토리가 서로 다른 브랜치를 바라보게 할 수 있습니다. Cursor가 2025년 10월 기준 베타 기능으로 Worktree를 지원하기 시작한 이유도 여기에 있다고 봅니다. 멀티 에이전트 시대에는 작업 공간 자체를 분리하는 능력이 그만큼 중요해졌습니다.

핵심 요약

• Git Worktree는 하나의 저장소에서 여러 작업 디렉토리와 브랜치를 동시에 운영하는 기능입니다.
• AI 에이전트를 여러 개 병렬로 사용할 때 파일 변경 충돌과 브랜치 전환 비용을 줄일 수 있습니다.
• 기존에는 git stash로 임시 저장 후 브랜치를 바꿔야 했지만, Worktree를 쓰면 별도 디렉토리에서 바로 새 작업을 시작할 수 있습니다.
• Cursor의 Worktree 기능은 에이전트 채팅이 새 Worktree에서 개발되도록 만들어 병렬 작업에 유리합니다.
• Worktree는 폴더 복사가 아니라 Git이 관리하는 정식 작업 트리이므로 브랜치와 커밋 흐름이 유지됩니다.

왜 Worktree가 필요한가

하나의 작업 디렉토리로는 병렬 개발이 어렵다

일반적인 Git 작업에서는 하나의 저장소 폴더에서 하나의 브랜치만 체크아웃합니다. 기능 개발 중 급한 수정이 생기면 현재 변경 사항을 커밋하거나 git stash로 임시 저장한 뒤 다른 브랜치로 이동해야 하죠. 작업이 끝나면 다시 원래 브랜치로 돌아와 stash를 복구합니다.

이 방식은 혼자 작업할 때도 꽤 번거롭습니다. AI 에이전트를 여러 개 동시에 돌리는 환경에서는 더 큰 문제가 됩니다. 한 에이전트가 파일을 수정하는 동안 다른 에이전트가 같은 작업 디렉토리에서 브랜치를 바꾸면 작업 상태가 꼬일 수 있거든요.

Worktree는 작업 공간을 분리한다

Git Worktree를 사용하면 현재 저장소를 기준으로 별도의 디렉토리를 만들고, 그 디렉토리에서 다른 브랜치를 체크아웃할 수 있습니다. 여기서 중요한 건 단순 복사본이 아니라 Git이 관리하는 작업 트리라는 점입니다.

git worktree add ../my-feature feature/my-feature
git worktree list

이렇게 만들면 원래 디렉토리에서는 기존 작업을 계속하고, 새 Worktree에서는 별도 브랜치 작업을 진행할 수 있습니다. 각 에이전트에게 서로 다른 Worktree를 맡기면 파일 변경이 섞일 가능성이 줄어듭니다.

Cursor Worktree 기능의 의미

에이전트별 작업 공간을 만든다

Cursor의 Worktree 기능은 에이전트 채팅에서 발생하는 작업을 새 Worktree에서 수행하도록 돕습니다. 즉, 하나의 Cursor 환경에서 여러 에이전트를 병렬로 실행하더라도 각 작업을 분리된 브랜치와 디렉토리에 배치할 수 있습니다.

이 구조는 멀티 에이전트 개발에 매우 잘 맞습니다. 예를 들어 한 에이전트는 로그인 버그를 수정하고, 다른 에이전트는 대시보드 UI를 개선하고, 또 다른 에이전트는 테스트를 작성하게 할 수 있습니다. 각 작업이 Worktree로 분리되어 있으면 변경 충돌을 더 쉽게 관리할 수 있습니다.

stash 중심 워크플로우를 줄인다

Worktree를 쓰면 급한 작업이 생길 때마다 현재 변경 사항을 억지로 정리할 필요가 줄어듭니다. 원래 작업 디렉토리는 그대로 두고, 새 디렉토리에서 hotfix나 실험 작업을 시작할 수 있습니다.

이건 AI 에이전트에게 특히 중요합니다. 에이전트 작업은 중간 상태가 길게 이어질 수 있고, 여러 파일을 동시에 수정하기도 하죠. 이 상태에서 브랜치를 바꾸는 것보다 새 Worktree를 만들어 별도로 맡기는 편이 훨씬 안전합니다.

실무 운영 팁

작업 범위를 명확히 나눈다

Worktree가 충돌을 줄여주지만 모든 문제를 해결하지는 않습니다. 두 에이전트가 같은 파일을 동시에 고치면 결국 병합 충돌은 발생할 수 있습니다. 따라서 각 Worktree를 만들 때 작업 범위를 명확히 지정해야 합니다.

예를 들어 “인증 모듈만 수정”, “문서만 업데이트”, “테스트 파일만 작성”처럼 책임 범위를 분리하면 병합이 한결 쉬워집니다. 에이전트에게도 다른 Worktree에서 동시에 작업 중인 세션이 있다는 걸 알려주면 더 좋습니다.

정리 명령을 습관화한다

Worktree는 편리하지만 많이 만들고 정리하지 않으면 디렉토리가 쌓입니다. 작업이 끝나면 병합 여부를 확인하고 필요 없는 Worktree를 제거해야 합니다.

git worktree list
git worktree remove ../my-feature

정리되지 않은 Worktree는 나중에 어떤 브랜치가 어디에서 작업 중인지 혼란을 만듭니다. 멀티 에이전트 작업일수록 목록 관리가 중요합니다.

stash 방식과 Worktree 방식 비교

피처 브랜치에서 작업하던 중 갑자기 핫픽스가 필요해진 상황을 떠올려 보겠습니다. 기존 방식과 Worktree 방식은 이렇게 차이가 납니다.

구분	stash 또는 급한 커밋 후 브랜치 전환	Git Worktree
기존 작업 처리	변경 사항을 stash하거나 서둘러 커밋해야 함	원래 디렉토리에 그대로 둠
새 작업 시작	브랜치 전환 후 작업, 끝나면 복귀해 stash pop	새 디렉토리에서 바로 시작
작업 흐름	흐름이 끊기고 컨텍스트 스위칭 비용 발생	두 작업이 동시에 유지됨
관리 부담	stash 목록 관리가 복잡해짐	worktree list로 목록 확인
멀티 에이전트	같은 디렉토리를 공유해 서로 간섭	에이전트별 공간이 분리되어 간섭 없음

핵심은 Worktree가 앞의 과정을 통째로 생략하게 해준다는 점입니다. 기존 작업은 손대지 않은 채로 두고, 새 작업은 깨끗한 상태의 별도 디렉토리에서 시작하면 되니까요.

Git Worktree 기본 사용 흐름

명령어로 쓰는 흐름은 생각보다 단순합니다. 순서대로 정리해 보겠습니다.

1. git worktree add에 Worktree를 만들 폴더 경로와 브랜치 이름을 넣어 생성합니다. 보통 현재 프로젝트보다 한 단계 위 경로에 만들면 관리하기 편합니다.
2. git worktree list로 새 Worktree가 목록에 추가되고 새 브랜치가 만들어졌는지 확인합니다.
3. 새 경로에 들어가 보면 저장소를 새로 clone한 것처럼 프로젝트 구조가 그대로 세팅되어 있습니다. 원래 디렉토리에서 수정 중이던 변경 사항은 없는 깨끗한 상태라 추가 작업을 이어가기 좋습니다.
4. 작업이 끝나면 해당 브랜치를 main에 병합하거나, 그 브랜치로 PR을 만들어 합칩니다.
5. 더 이상 필요 없으면 원래 저장소에서 git worktree remove에 경로를 넣어 제거하고, 다시 목록을 확인합니다.

폴더를 직접 지워도 되지만, Worktree는 Git으로 연결된 구조라 git worktree remove로 정리하는 편이 깔끔합니다.

Worktree가 특히 유용한 상황

제가 보기에 Worktree가 빛나는 상황은 크게 네 가지입니다.

• 긴급 버그 수정: 진행 중인 기능 개발을 그대로 두고 별도 Worktree에서 핫픽스를 처리합니다.
• 코드 리뷰와 테스트: 하던 작업은 잠시 두고, 새 Worktree에서 리뷰 대상 브랜치를 받아 테스트까지 마친 뒤 PR에 리뷰를 남깁니다.
• 멀티 에이전트 병렬 작업: 에이전트마다 자기 Worktree를 할당하면 A 에이전트의 작업 공간에 B 에이전트가 간섭할 수 없는 구조가 됩니다.
• 여러 버전 동시 확인: 서로 다른 브랜치의 코드를 각각의 Worktree에 띄워두고 개발 서버를 동시에 올려 비교할 수 있습니다.

Cursor에서 Worktree 기능 사용하기

활성화와 에이전트 생성

Cursor의 Worktree 기능은 2025년 10월 기준 베타라서 먼저 켜줘야 합니다. Cursor 설정의 Beta 탭에서 Worktree 항목을 활성화하면 됩니다. 그리고 이 기능은 에이전트 창(Agent 뷰)에서만 쓸 수 있기 때문에, 에이전트 창으로 전환한 뒤 새 에이전트를 만들면 채팅 입력 영역에서 Worktree를 켜고 끌 수 있습니다. 명령어를 직접 입력하지 않아도 Worktree를 쓸 수 있다는 게 IDE 통합의 장점이죠.

두 에이전트로 병렬 작업해 보기

예를 들어 에이전트 두 개를 띄우고, 첫 번째에는 “프로젝트 테마를 레트로 느낌으로 바꿔줘”, 두 번째에는 “LLM API 연동을 Gemini에서 OpenAI로 바꿔줘”라고 동시에 요청해 볼 수 있습니다. 두 채팅 모두 Worktree를 켜두면 각자 별도의 Worktree에서 작업이 진행됩니다.

터미널에서 git worktree list를 확인하면 main 외에 Worktree 두 개가 생긴 걸 볼 수 있습니다. 한 가지 알아둘 점은 Cursor가 만드는 Worktree는 새 브랜치를 만들지 않고 detached 상태로 생성된다는 겁니다. 작업은 원래 프로젝트 경로가 아니라 Cursor가 관리하는 Worktree 경로에서 독립적으로 진행되고, main 브랜치에는 아무 영향도 주지 않습니다.

각 Worktree에서 개발 서버를 따로 띄우면 결과도 나란히 비교할 수 있습니다. API 연동만 바꾼 Worktree는 기존 UI 그대로, 테마를 바꾼 Worktree는 레트로 테마로 서로 다른 포트에서 실행되죠. 에이전트끼리 영향을 주지 않으면서 버전 비교까지 할 수 있는 셈입니다.

Apply로 main에 반영하기

작업이 끝난 에이전트 채팅에는 Apply 버튼이 나타납니다. 버튼을 누르면 어느 브랜치에 적용할지 고를 수 있고, main을 선택한 뒤 확인하면 변경 사항이 main에 들어갑니다. 이렇게 반영된 Worktree는 목록에서 제거되기 때문에, 다시 git worktree list를 보면 Worktree가 하나 줄어든 걸 확인할 수 있습니다.

worktrees.json으로 초기 세팅 자동화하기

주의할 점이 하나 있습니다. Worktree는 Git이 관리하는 파일을 기준으로 만들어지기 때문에, Git에 올리지 않은 파일은 새 Worktree로 따라오지 않습니다. 대표적인 게 .env.local 같은 환경 변수 파일이죠. 이 상태로 개발 서버를 띄우면 설정이 비어 있어 제대로 동작하지 않을 수 있습니다.

Cursor에서는 .cursor 폴더 안에 worktrees.json 파일을 만들고 setup-worktree 항목에 Worktree 생성 시 실행할 명령들을 적어 이 문제를 해결할 수 있습니다. 예를 들어 다음과 같은 작업을 넣어둘 수 있습니다.

• Node 버전 관리 도구로 프로젝트의 Node 버전 맞추기
• npm으로 패키지 설치하기
• 루트 Worktree에 있는 .env.local을 새 Worktree로 복사하기

이렇게 해두면 Worktree가 생길 때마다 파일을 손으로 복사하지 않아도 기본 세팅이 자동으로 끝납니다. 멀티 에이전트를 자주 돌린다면 가장 먼저 챙겨볼 설정이라고 봅니다.

마무리

제가 말하고 싶은 건 결국 이겁니다. 에이전트를 여러 개 띄우는 것만으로는 생산성이 오르지 않습니다. 각 에이전트가 서로 간섭하지 않고 안전하게 작업할 공간이 있어야 하고, 그 공간을 만들어주는 현실적인 기반 기술이 Git Worktree라고 봅니다.

Cursor의 Worktree 기능은 이 흐름을 IDE 안으로 가져오려는 시도죠. 멀티 에이전트 개발을 자주 한다면 Git Worktree의 기본 개념과 명령부터 익혀보면 좋겠습니다. 그 위에 Cursor의 통합 기능을 얹으면 병렬 작업이 훨씬 수월해집니다. 더 좋은 활용 방식이 있다면 댓글로 많이 공유해주세요.

---

관련 영상

이 글과 연결된 영상은 개발동생 유튜브 채널에서 보기에서 확인할 수 있습니다.