워크트리 뜻: 한 줄 정의#
워크트리는 Git 저장소에 연결된 작업 디렉터리입니다. 각 디렉터리에서 다른 브랜치를 체크아웃해 작업할 수 있지만 저장소의 이력과 브랜치 등은 공유합니다. Git 공식 매뉴얼(2026-11-02 확인)을 기준으로 차이를 정리했습니다.
| 구분 | 브랜치 | 워크트리 |
|---|---|---|
| 역할 | 커밋 이력을 가리키는 이름 | 파일을 체크아웃해 작업하는 디렉터리 |
| 동시 작업 | 브랜치만 추가하면 작업 폴더가 생기지는 않음 | 별도 폴더에서 다른 브랜치를 작업 가능 |
| 주의 | 나중에 변경을 합칠 때 충돌 가능 | 같은 브랜치는 일반적으로 여러 워크트리에 동시에 체크아웃할 수 없음 |
- 병렬로 수행할 과제와 각 에이전트의 파일 범위를 먼저 나눕니다.
- 현재 변경 사항과 브랜치, 사용할 새 경로를 확인하고 작업별 워크트리를 만듭니다.
- 각 결과의 diff와 테스트를 확인한 뒤 순서대로 합치고 충돌을 해결합니다.
- 제거하기 전에 미커밋·추적되지 않는 파일을 보존하고 정확한 경로를 확인합니다.
Git 매뉴얼에 따르면 연결된 워크트리는 저장소를 공유하되 HEAD와 인덱스 같은 파일별 상태만 따로 가집니다. refs/ 아래의 브랜치와 태그는 모든 워크트리가 함께 보고, 설정 파일도 기본으로 공유됩니다. 워크트리마다 다른 설정이 필요하면 extensions.worktreeConfig를 켠 뒤 워크트리별 설정 파일을 씁니다. bare 저장소가 아닌 경우 원래 저장소 폴더가 메인 워크트리이며, 메인 워크트리는 제거할 수 없습니다.
브랜치 이름 없이 git worktree add <경로>만 쓰면 경로의 마지막 이름과 같은 새 브랜치가 만들어져 체크아웃됩니다. 브랜치를 남기지 않는 실험이라면 --detach 옵션으로 현재 커밋의 분리된 HEAD에서 시작합니다(Git 매뉴얼, 2026-11-03 확인).
왜 중요한가: 한국 개발자 기준#
별도 폴더는 동시에 같은 작업 파일을 덮어쓰는 위험을 줄입니다. 다만 같은 파일을 서로 다르게 고치면 병합할 때 충돌할 수 있고, 데이터베이스·포트·환경 변수 같은 공유 자원도 분리되지 않습니다. 워크트리는 보안 샌드박스가 아니므로 에이전트에 허용할 파일과 명령도 따로 정하세요.
Claude Code 워크트리 문서는 병렬 세션을 워크트리로 나누는 방식을 기본 예로 듭니다. claude --worktree <이름>을 실행하면 저장소 루트의 .claude/worktrees/<이름>/에 워크트리가 만들어지고, 기본 브랜치에서 갈라진 worktree-<이름> 브랜치에서 작업합니다(Claude Code 워크트리 문서, 2026-11-03 확인).
같은 문서에 따르면 워크트리는 깨끗한 체크아웃이라 .env 같은 비추적 파일이 없습니다. .worktreeinclude 파일에 .gitignore 문법으로 패턴을 적어 두면, 패턴에 맞고 gitignore에도 있는 파일만 새 워크트리로 복사됩니다. 예를 들어 .env, .env.local, config/secrets.json을 적을 수 있습니다.
워크트리 문서와 권한 문서에 따르면 권한 승인도 워크트리 경계를 넘습니다. 워크트리 세션에서 Bash 명령에 '다시 묻지 않음'을 고르면 규칙이 메인 체크아웃의 .claude/settings.local.json에 저장되어 같은 저장소의 다른 워크트리에도 적용되고, 워크트리를 지워도 남습니다. 파일 수정 승인은 세션이 끝나면 사라지므로 이와 다릅니다.
워크트리 문서에 따르면 Claude Code의 격리 검사도 범위가 좁습니다. 검사는 편집 대상 경로, 명령의 작업 디렉터리, git 리디렉션, 명령 형태만 봅니다. cp나 셸 리디렉션처럼 git을 거치지 않고 메인 체크아웃에 쓰는 명령은 이 검사로 막히지 않고, 일반 권한과 샌드박스 설정을 따릅니다.
워크트리 문서에 따르면 Claude가 세션 안에서 워크트리를 만들거나 다른 워크트리로 옮길 때는 EnterWorktree 도구를 씁니다. 옮기는 경로가 .claude/worktrees/ 밖이면 Claude Code가 먼저 승인을 묻고, 권한 규칙에 '다시 묻지 않음'을 저장해 두어도 이 질문은 생략되지 않습니다. bypassPermissions 모드에서만 질문이 건너뛰어집니다. 세션에 해당 도구가 있으면 ExitWorktree로 원래 작업 디렉터리로 돌아갈 수 있습니다.
예제: 코드나 터미널로 보기#
다음은 빈 합성 저장소에서 실행한 기록입니다. repo와 topic은 이 실험 전용이며 실제 프로젝트가 아닙니다. 경로와 커밋 ID는 실행마다 달라집니다.
$ git init -q -b main repo
$ git -C repo -c user.name=Example -c user.email=example@example.invalid commit --allow-empty -q -m initial
$ git -C repo worktree add -b topic ../topic
Preparing worktree (new branch 'topic')
HEAD is now at 6c7b365 initial
$ git -C repo worktree list
$ git -C repo worktree remove ../topic
$ git -C repo worktree list
remove는 연결된 작업 디렉터리를 제거합니다. 이 예제는 깨끗한 실험용 워크트리만 제거했으며, 브랜치 자체를 지우지는 않았습니다. 실제 작업에서 --force로 확인을 우회하지 마세요. 폴더 트리 스크린샷과 병합 충돌 실험은 수행하지 않았습니다.
git worktree list는 메인 워크트리를 맨 앞에 두고 연결된 워크트리를 이어서 보여 줍니다. 각 줄에는 경로, 체크아웃된 커밋의 짧은 해시, 브랜치 이름 또는 '(detached HEAD)'가 나옵니다. 잠긴 항목에는 locked, 정리 대상에는 prunable이 붙고, --verbose를 쓰면 잠금 사유를 다음 줄에 보여 줍니다. 스크립트로 읽을 때는 --porcelain을 쓰고, 경로에 줄바꿈이 있을 수 있으면 -z를 함께 씁니다. 위 기록에서 두 번째 list에는 제거한 topic이 빠지고 main만 남습니다.
매뉴얼은 진행 중인 리팩터링을 두고 긴급 수정을 해야 할 때 일회성 워크트리를 쓰는 예를 듭니다. 새 브랜치로 워크트리를 만들어 수정하고 커밋한 뒤 워크트리를 제거하면, 원래 리팩터링 세션으로 돌아갈 수 있습니다.
관련 용어#
| 상황 | 확인할 것 | 대응 원칙 |
|---|---|---|
| 브랜치를 이미 사용 중 | git worktree list의 경로와 브랜치 | 다른 작업을 빼앗지 말고 별도 브랜치 선택 |
| 제거가 거부됨 | 미커밋·추적되지 않은 파일과 대상 경로 | 필요한 내용을 보관한 뒤 정상 제거 |
| 병렬 테스트가 충돌 | 같은 DB·포트·캐시 사용 여부 | 테스트 자원도 별도로 배정 |
Git 명령은 위 공식 매뉴얼을 따르며 공유 자원 행은 병렬 작업의 검토 기준입니다. 이 문제들을 재현한 로그는 아닙니다.
서브에이전트는 일을 나누는 방식이고 워크트리는 작업 파일을 나누는 Git 기능입니다. 에이전트 하네스는 모델과 도구를 연결하는 실행 환경을 다룹니다.
잠금(lock)은 워크트리 경로가 항상 마운트되지 않는 장치에 있을 때 쓰는 기능입니다. git worktree lock으로 잠근 워크트리는 자동 정리 대상에서 빠지고, 이동이나 삭제도 막힙니다. 정리(prune)는 작업 디렉터리를 파일 관리자로 지운 뒤 남은 관리 정보를 치우는 작업입니다. 복구(repair)는 메인 저장소나 워크트리 폴더를 직접 옮긴 뒤 두 쪽의 연결을 다시 맞추는 명령입니다. git worktree add --lock은 생성과 잠금을 한 번에 해서 그 사이의 경쟁 조건을 없앱니다. 메인 워크트리와 서브모듈이 있는 워크트리는 git worktree move로 옮길 수 없습니다.
명령을 실행하기 전에 읽을 현재 상태#
독자가 자신의 저장소에서 확인할 수 있는 조회 예시는 git status --short, git branch --show-current, git worktree list --porcelain입니다. 여기서 새로 실행한 transcript를 보고하는 것은 아닙니다. 현재 수정 목록, 브랜치와 연결 경로를 확인한 다음 사용할 새 경로와 브랜치 이름이 다른 작업과 겹치지 않는지 검토하세요. 기존 브랜치가 사용 중이라는 오류를 무시하고 강제로 체크아웃하지 않습니다.
list --porcelain은 경로, HEAD와 브랜치 같은 항목을 분리해 보여 주는 형식입니다. 결과를 자동 처리한다면 경로에 공백이나 특수 문자가 있을 수 있다는 점도 고려해야 합니다. Git 공식 문서는 기계 처리를 위해 이 형식과 -z를 안내합니다. 조회 출력에 있는 경로가 실제로 어떤 작업인지 확인하지 않고 제거 대상으로 사용하면 안 됩니다.
Claude Code 공통 작업 흐름 문서는 커밋이 하나도 없는 저장소에서 claude --worktree가 Failed to resolve base branch "HEAD" 오류로 실패한다고 적습니다. 워크트리는 기존 커밋에서 갈라지므로 먼저 첫 커밋을 만들어야 합니다.
Claude Code 워크트리 문서는 Git LFS 설정에 따라 결과가 달라질 수 있다고 적습니다. git lfs install --local로 LFS 필터를 저장소의 .git/config에 쓴 경우, Claude Code가 만든 워크트리에는 실제 파일 대신 LFS 포인터 파일이 생깁니다. Claude Code는 저장소 설정의 필터 드라이버를 실행하지 않으므로, 그 워크트리 안에서 git lfs pull을 실행해야 실제 파일을 받습니다.
워크트리 문서에 따르면 부분 복제(partial clone) 저장소는 워크트리의 시작 커밋에 필요한 객체를 모두 받지 못하면 생성이 실패합니다. .claude, .claude/worktrees, 워크트리 디렉터리 가운데 하나가 심볼릭 링크이면 Claude Code는 생성을 거부합니다. 워크트리 폴더의 .git 파일이 메인 저장소를 가리키는 경우도 거부됩니다. 그 폴더에서 git reset --hard 같은 명령을 실행하면 워크트리가 아니라 메인 체크아웃이 바뀔 수 있기 때문입니다.
제거 거부는 강제 삭제하라는 안내가 아니다#
깨끗하지 않은 워크트리의 제거가 거부되면 남은 수정과 비추적 파일을 조사합니다. Git 매뉴얼의 제거 조건은 추적되지 않는 파일과 추적 파일의 수정을 기준으로 합니다. 무시된 파일은 이 조건에 걸리지 않으므로, 필요한 자료가 있다면 제거 전에 직접 보관하세요. 커밋했다는 말만으로 모든 파일이 보존됐다고 가정하지 마세요. 보관한 자료를 확인한 뒤 정확한 대상에 정상적인 제거 절차를 적용합니다. --force로 이 점검을 우회할 필요는 없습니다.
워크트리를 제거해도 브랜치 정리와 원격 반영은 별도 작업입니다. 작업 폴더가 없어졌다고 변경이 주 브랜치에 들어갔다거나 원격에 저장됐다고 볼 수 없습니다. Git worktree 공식 문서는 2026-11-02에 다시 확인했습니다. 위의 운영 판단은 독자용 안내이며 기존 합성 transcript 외에 새 병합·삭제 실험이나 실제 프로젝트 작업을 수행한 기록은 아닙니다.
워크트리 문서에 따르면 Claude Code가 만든 워크트리는 세션을 나갈 때 정리 규칙을 따릅니다. 변경 파일, 추적되지 않는 파일, 체크아웃된 서브모듈의 미커밋 작업, 새 커밋이 하나도 없으면 이름 없는 세션의 워크트리와 브랜치를 자동으로 지웁니다. 이름 붙인 세션은 깨끗해도 먼저 묻습니다. 작업이 남아 있으면 보관할지 제거할지 묻고, 제거를 고르면 작업 디렉터리와 브랜치, 그 안의 작업이 모두 지워진다고 문서는 설명합니다.
같은 문서에 따르면 -p로 실행한 세션에는 종료 질문이 없어서 워크트리가 정리되지 않습니다. 만들 때 걸린 잠금도 그대로 남았다가 나중 세션의 정리 과정에서 풀립니다. 직접 지울 때는 git worktree remove를 쓰고, git이 잠금 때문에 거부하면 git worktree unlock으로 먼저 풀어야 합니다. Git 매뉴얼은 잠긴 워크트리를 제거할 때 --force를 두 번 지정하라고 적습니다. 그 전에 잠금을 누가 걸었는지와 보관할 내용을 먼저 확인하세요.
같은 문서에 따르면 Claude Code는 정기 정리 작업으로 서브에이전트와 백그라운드 세션이 만든 워크트리를 cleanupPeriodDays 설정 기간이 지나면 지웁니다. 다만 변경 파일, 추적되지 않는 파일, 푸시하지 않은 커밋이 남아 있거나 서브모듈 상태를 확인할 수 없으면 남겨 둡니다. 정리 대상은 Claude Code가 Git 메타데이터에 표식을 남긴 워크트리뿐이며, 사람이 git worktree add로 만든 워크트리는 표식이 없어 남습니다.
같은 문서에 따르면 Windows에서는 워크트리 안의 심볼릭 링크나 정션을 지울 때 링크만 지우고, 링크가 가리키는 바깥 폴더는 건드리지 않습니다.
인계할 때 경로만 보내면 부족한 이유#
다른 작업자가 결과를 읽으려면 어느 기준 커밋에서 무엇을 바꿨는지 알아야 합니다. 워크트리 경로와 브랜치, 변경 목적과 실행한 검사를 함께 남기세요. 미커밋 파일이 남아 있다면 그 사실도 적으세요. 브랜치 이름을 받은 사람이 원격에서 같은 상태를 볼 수 있다고 가정하지 않습니다. 커밋과 원격 반영은 별도 승인 작업이며 이 안내가 그 행동을 허가하지는 않습니다.
검토한 결과가 나중에 바뀌었다면 이전 검토가 현재 파일의 승인이라고 할 수 없습니다. 최종 변경을 다시 대조하고 필요한 검사를 확인하세요. 테스트 출력도 어느 경로와 상태에서 실행됐는지 남기세요. 다른 워크트리의 성공 출력을 현재 결과의 증거로 옮기면 실제 차이를 놓칠 수 있습니다. 원본과 결과를 구분한 인계가 중요한 이유입니다.
같은 이름을 다시 여는 것도 기준점이 되지 못합니다. 이미 있는 이름을 --worktree에 넘기면 새 워크트리를 만들지 않고 기존 것을 엽니다. Claude Code 문서에 따르면 기본 설정에서 같은 이름으로 워크트리를 열 때, 변경과 추적되지 않는 파일이 없고 아직 만든 브랜치에 있으며 자체 커밋이 없거나 PR이 병합되어 원격 브랜치가 지워진 경우에만 기본 브랜치 기준으로 다시 맞춰집니다. 그 밖의 경우에는 이전 끝 지점에서 열립니다. 이름만 주고받으면 상대가 어느 시점의 워크트리를 여는지 알 수 없습니다.
새 워크트리가 어느 커밋에서 갈라지는지도 인계 내용에 적으세요. 기본값은 원격의 기본 브랜치에서 갈라지는 것입니다. 워크트리 문서에 따르면 Claude Code는 origin/HEAD를 최신으로 유지하려고, 24시간 넘게 가져오지 않은 저장소에서 기본 브랜치를 최대 5초 동안 가져오며, 실패하면 캐시된 참조를 씁니다. worktree.baseRef를 head로 두면 현재 로컬 HEAD에서 갈라져 아직 푸시하지 않은 커밋까지 가져갑니다.
워크트리로 동시에 작업할 때는, 같은 저장소의 어떤 자원을 공유하고 어떤 자원은 각 워크트리가 따로 가져가는지 구분하세요. 브랜치와 인덱스는 워크트리마다 다르고, 일부 캐시나 설정은 저장소 수준에서 공유될 수 있습니다. 인계할 때 경로만 보내면 부족한 이유를 설명하고, 어떤 상태가 그대로 넘어가고 어떤 상태는 각 환경에서 다시 준비되는지를 함께 적는 편이 충돌을 줄입니다.
다음에 읽을 것#
작업 분할의 조율 비용은 서브에이전트 글에서 이어서 살펴볼 수 있습니다.
관련#
편집 메모 (2026-11-02): 워크트리 제거와 공유 자원 진단을 보충했습니다. 기존 합성 저장소 transcript는 유지했으며 폴더 화면과 병합 충돌 실험은 여전히 없습니다.