Git worktree로 브랜치별 작업 폴더를 나누면 진행 중인 코드를 그대로 둔 채 다른 기능 개발이나 오류 수정에 착수할 수 있다. AI 코딩 세션을 동시에 실행할 때도 각 세션에 별도 폴더를 배정하면 파일 수정이 뒤섞이는 문제를 줄일 수 있다.
핵심 흐름은 간단하다. add -b로 브랜치와 폴더를 만들고, list로 배치를 확인한 뒤, 작업을 마치면 remove로 정리한다. 다만 소스 파일이 분리되어도 실행 환경과 외부 서비스까지 자동으로 격리되지는 않으므로, 생성 명령과 함께 환경 준비·변경 확인 절차를 익혀두는 편이 좋다.
1. Git worktree 구조 이해하기: 브랜치와 작업 폴더의 관계
Git worktree는 하나의 저장소에 여러 작업 디렉터리를 연결하는 기능이다. 각 폴더는 별도의 HEAD와 인덱스를 가지므로, 한쪽에서 파일을 수정하거나 스테이징해도 다른 쪽의 작업 상태와 구분된다. 반면 커밋 객체와 일반적인 브랜치 참조 등은 공유한다.
예를 들어 원래 저장소 폴더에서는 main을 유지하고, 옆에 만든 폴더에서는 feature를 개발할 수 있다. 브랜치를 바꿀 때마다 같은 디렉터리의 파일 구성이 바뀌는 흐름에서 벗어나, 작업별 편집기와 터미널을 계속 열어둘 수 있다는 점이 실용적이다.
다만 브랜치와 폴더는 같은 개념이 아니다. 브랜치는 커밋을 가리키는 참조이고, worktree는 그 내용을 실제 파일로 펼쳐놓는 작업 공간이다. 공유 범위를 정확히 이해해야 한 폴더에서 수행한 브랜치 조작이 다른 작업에 미치는 영향도 판단할 수 있다.
근거: Git 공식 문서의 DESCRIPTION·REFS·DETAILS. 명령 옵션은 설치된 버전의 git worktree -h에서도 확인할 수 있다.
1. Git worktree 구조 이해하기: 브랜치와 작업 폴더의 관계 실시간 확인하기
2. git worktree add -b로 브랜치별 작업 폴더 만들기
다음 예시는 기존 저장소 폴더 이름이 repo이고, 로컬에 main 브랜치가 있는 경우다. 명령은 repo 안에서 실행하며, 새 작업 폴더는 같은 상위 디렉터리 아래의 repo-feature에 생성한다.
- 현재 저장소와 변경 상태를 확인한다.
- 새 브랜치 이름과 작업 폴더 경로를 정한다.
- 기준 브랜치를 지정해 worktree를 생성한다.
- 생성된 폴더에서 브랜치와 파일 상태를 확인한다.
git status --short
git branch --list main
git worktree add -b feature ../repo-feature main
git -C ../repo-feature branch --show-current
git -C ../repo-feature status --short-b feature는 새 브랜치 생성, ../repo-feature는 작업 폴더 경로, 마지막의 main은 출발점을 뜻한다. 현재 폴더에 남아 있는 미커밋 수정 내용이 새 브랜치로 복사되는 것은 아니다. 새 폴더는 지정한 기준 커밋의 파일로 만들어진다.
원격 저장소의 최신 main에서 시작해야 한다면 먼저 원격 정보를 갱신하고 기준점을 명시한다. 아래 명령은 원격 이름이 origin인 경우이며, 앞선 예시와는 별도로 실행하는 대안이다. 같은 feature 브랜치를 이미 만들었다면 다른 이름을 사용해야 한다.
git fetch origin
git worktree add -b feature ../repo-feature origin/main브랜치가 이미 존재하고 다른 worktree에서 사용 중이지 않다면 git worktree add ../repo-feature feature처럼 -b를 생략한다. 새 브랜치 생성과 기존 브랜치 체크아웃을 구분하면 이름 중복 오류를 쉽게 해결할 수 있다.
2. git worktree add -b로 브랜치별 작업 폴더 만들기 바로가기
3. git worktree list로 확인하고 브랜치 중복 오류 해결하기
작업 공간이 늘어나면 폴더 이름만 보고 브랜치를 추측하기 쉽다. git worktree list로 실제 연결 상태를 확인하는 습관이 도움이 된다. Git 공식 문서에 따르면 목록에는 작업 경로·커밋·브랜치와 함께 해당하는 경우 locked, prunable 상태가 표시된다.
git worktree list
git worktree list --porcelain기본 출력은 사람이 빠르게 살펴보기 좋고, --porcelain은 스크립트에서 처리하기 위한 형식이다. 터미널 탭 이름에도 브랜치와 폴더를 함께 적어두면 AI 세션이 어느 작업 공간을 수정하는지 확인하기 편하다.
동일 브랜치가 다른 worktree에 이미 체크아웃되어 있으면 Git은 기본적으로 추가 체크아웃을 거부한다. 이때는 목록에서 해당 폴더를 찾아 계속 작업하거나, 기존 브랜치를 출발점으로 별도 브랜치를 만든다. 오류를 없애기 위해 강제 옵션부터 붙이면 분리한 작업 상태를 관리하기 어려워질 수 있다.
git worktree add -b feature-review ../repo-review feature위 명령은 feature와 같은 커밋에서 feature-review를 시작하는 예시다. 두 브랜치는 이후 독립적으로 진행하므로, 한쪽의 새 커밋을 다른 쪽에 반영하려면 별도의 병합이나 커밋 적용이 필요하다.
또한 list는 각 폴더의 수정 파일 목록을 보여주지 않는다. 변경 여부는 대상 경로를 지정한 git status로 따로 확인해야 한다.
3. git worktree list로 확인하고 브랜치 중복 오류 … 신청하기
4. AI 코딩 병렬 작업: 의존성·환경변수·포트까지 준비하기
2026년 11월 확인한 Anthropic의 「Claude Code power user tips」는 각각 별도 Git worktree를 사용하는 Claude 세션 3~5개의 병렬 실행 방식을 소개한다. claude --worktree my_worktree로 이름을 지정한 격리 작업 세션을 시작하는 방법도 안내한다. 이 수치는 해당 팀의 작업 패턴 소개이며, 생산성 향상률이나 모든 프로젝트의 적정 동시 실행 수를 뜻하지는 않는다.
출처: Anthropic Claude Help Center, 「Claude Code power user tips」의 Working in parallel 항목.
이미 수동으로 만든 worktree를 사용할 때는 해당 폴더에서 AI 코딩 도구를 실행하고 작업 경로를 확인한다. 도구 자체의 worktree 생성 기능을 사용할 때는 도구가 관리하는 경로와 수동으로 만든 경로를 구분해두면 정리할 때 혼동이 적다.
실무에서는 폴더 생성 다음에 실행 환경을 준비하는 과정이 필요하다. Git이 추적하지 않는 node_modules, 가상환경, 로컬 .env 파일은 새 worktree에 자동으로 갖춰지지 않는다. 브랜치별 잠금 파일이나 런타임 요구사항이 다를 수 있으므로 프로젝트의 설치 절차를 각 폴더에서 적용해야 한다.
- 의존성: 브랜치의 잠금 파일과 프로젝트 문서에 맞춰 설치한다. Python 프로젝트라면 폴더별 가상환경을 사용하는 방식도 고려한다.
- 환경변수: 필요한 설정을 별도로 준비하고, 비밀값이 포함된 파일을 실수로 커밋하지 않도록 확인한다.
- 개발 서버: 동시에 실행하는 서버는 서로 다른 포트를 지정한다. 폴더가 달라도 같은 포트에 동시에 바인딩할 수는 없다.
- 데이터 저장소: 같은 데이터베이스·테스트 계정·외부 API를 사용하면 변경이 서로 영향을 줄 수 있다. 필요하면 데이터베이스나 테스트 자원을 나눈다.
병렬 작업의 효율은 세션 개수보다 과제의 독립성에 크게 좌우된다는 것이 운영 관점의 판단이다. 문서 수정과 별도 모듈의 버그 수정처럼 검토 범위가 나뉘는 작업은 배정하기 쉽다. 같은 핵심 함수를 여러 세션이 동시에 바꾸면 파일 충돌을 피하더라도 최종 병합 단계에서 설계와 동작을 다시 맞춰야 한다.
각 세션에 작업 목표·담당 범위·완료 확인 명령을 함께 전달하면 통합 부담을 줄일 수 있다. 개별 브랜치에서 테스트를 통과한 뒤에도 통합 브랜치에서 다시 검증해야 한다. 서로 다른 변경이 만났을 때 생기는 문제는 폴더 분리만으로 확인되지 않기 때문이다.
4. AI 코딩 병렬 작업: 의존성·환경변수·포트까지 준비하기
5. git worktree remove 전 미커밋 변경 사항 확인하기
작업을 마쳤다면 먼저 해당 폴더에서 실행 중인 AI 세션과 개발 서버를 종료한다. 이어 수정 파일·스테이징 내용·미추적 파일을 확인하고 필요한 결과물을 보존한다. AI가 완료했다고 알린 상태와 Git에 변경이 안전하게 기록된 상태는 따로 확인해야 한다.
git -C ../repo-feature status --short
git -C ../repo-feature diff
git -C ../repo-feature diff --cached
git -C ../repo-feature status --short --ignoreddiff는 아직 스테이징하지 않은 추적 파일 변경을, diff --cached는 스테이징된 변경을 확인하는 데 사용한다. status --short의 ??는 미추적 파일을 뜻한다. 무시된 환경설정이나 로컬 결과물은 마지막 명령으로 별도 확인하고, 보관할 필요가 있는지 판단한다.
필요한 코드는 커밋하고 검토·병합 상태를 확인한 다음, 삭제 대상 폴더 밖에 있는 원래 저장소에서 정리한다. 아래 예시는 원래 repo 폴더에서 실행하는 명령이다.
git worktree remove ../repo-feature
git worktree listGit은 미커밋 변경이나 미추적 파일이 있는 worktree의 삭제를 기본적으로 거부한다. 이 거부는 삭제할 내용이 남았는지 다시 확인하라는 신호로 받아들이는 편이 좋다. 특히 무시된 로컬 파일은 별도로 점검해야 하므로, 삭제 성공 여부만으로 보존할 파일이 없었다고 판단하면 안 된다.
worktree 제거와 브랜치 삭제는 별도 작업이다. 작업 폴더를 제거해도 브랜치는 남는다. 병합을 마쳐 더 이상 필요하지 않은 브랜치만 git branch -d feature로 삭제하며, 삭제가 거부되면 미병합 커밋이 남았는지 확인한다.
5. git worktree remove 전 미커밋 변경 사항 확인하기
6. 수동 삭제 후 git worktree prune과 lock 사용 시 주의점
파일 탐색기나 운영체제 명령으로 작업 폴더만 삭제하면 저장소 내부의 연결 관리 정보가 남을 수 있다. 이때 사용하는 명령이 git worktree prune이다. remove가 작업 폴더를 정상적으로 제거하는 절차라면, prune은 사라진 작업 폴더의 오래된 관리 정보를 정리하는 절차다.
git worktree list
git worktree prune --dry-run --verbose먼저 미리보기로 정리 대상을 확인한다. 실제로 삭제된 폴더의 관리 정보만 남아 있다면 git worktree prune을 실행할 수 있다. 기본 만료 조건 때문에 방금 사라진 항목이 남는 경우에는, 영구 삭제된 경로인지 확인한 뒤 아래처럼 만료 기준을 지정한다.
git worktree prune --dry-run --verbose --expire now
git worktree prune --verbose --expire now외장 드라이브나 잠시 끊긴 네트워크 공유는 폴더가 영구 삭제된 상황과 구분해야 한다. Git 공식 문서는 항상 연결되지 않는 장치의 worktree를 lock으로 잠가 관리 정보의 자동 정리를 방지하는 방법을 안내한다. 잠금 사유를 적으면 이후 상태를 해석하기도 쉽다.
git worktree lock --reason "외장 드라이브에 보관한 작업 공간" ../repo-feature
git worktree unlock ../repo-feature잠금은 파일 편집을 막는 기능이 아니다. 또한 잠긴 worktree를 강제로 제거하려면 Git 문서상 --force를 두 번 지정해야 하지만, 일반적인 정리에서는 잠금 사유와 파일 상태를 확인한 뒤 잠금을 해제하고 제거하는 흐름이 명확하다. prune으로 삭제된 소스 파일을 복구할 수 있는 것도 아니다.
처음 적용할 때는 기존 저장소에 작업 폴더 하나를 추가해 생성부터 제거까지 한 번 연결해보면 충분하다. 작업마다 브랜치와 경로를 명확히 배정하고, 실행 환경을 준비한 뒤, 결과를 보존하고 폴더를 정리하는 흐름이 자리 잡으면 AI 병렬 코딩에서도 작업 상태를 추적하기 쉬워진다.
검증 기준: 2026년 11월 확인한 Git 공식 「git-worktree」 문서 및 Anthropic 공식 안내. 병렬 세션 수는 사용 패턴의 예시이며, 생산성 통계로 해석하지 않았다.