같은 저장소에서 프로필 화면과 결제 재시도 버그를 동시에 고쳐야 한다고 해봅시다. 브랜치만 두 개 만들고 한 디렉터리에서 오가면 빌드 산출물과 미커밋 파일이 섞입니다. Worktree는 각 브랜치에 별도 작업 폴더와 인덱스를 주지만, 두 작업이 같은 포트와 개발 DB를 잡는 문제까지 해결하지는 않습니다.
핵심 두 작업의 수정 파일과 실행 자원이 겹치지 않을 때 Worktree가 시간을 줄입니다. 기준 커밋을 고정하고, 작업별 포트와 데이터베이스를 나누고, 통합 담당자가 공통 파일을 소유해야 합니다. 이 셋 중 하나라도 정할 수 없다면 병렬화보다 순차 작업이 안전합니다.
Claude Code 세션은 작업 공간마다 따로 엽니다. 아래 경로와 포트는 예시입니다. 실제 저장소 규칙을 먼저 확인합니다.
git worktree add ../app-profile -b issue/profile origin/main
cd ../app-profile
claude --permission-mode plan
읽기: CLAUDE.md, 프로필 소스·테스트, 실행 스크립트
허용: Read, Grep, 프로필 테스트
금지: lockfile, 공용 라우터, DB 스키마, commit·push
반환: 소유 파일 / 포트·DB 충돌 / 검증 명령 / 통합 제안
중단: 다른 Worktree와 공유 파일이 겹칠 때통합 담당자가 계획을 승인한 뒤 구현을 재개합니다. 후속 프롬프트는 승인된 소유 파일만 수정하게 하고 결과를 변경 파일, 테스트, 미검증 순서로 받습니다. `git status --short`, 관련 테스트, `git diff`, `git diff --check`를 각 작업 공간과 통합 상태에서 확인합니다.
미커밋 파일, 미병합 커밋, 공유 자원 충돌이 있으면 제거하지 않습니다. 재개 메모에는 Worktree 경로, 기준 커밋, 포트·DB와 남은 통합 순서를 남깁니다.
예시 작업에서는 포트와 DB도 따로 정합니다. 예시 계약에서는 프로필 작업에 `src/profile/**`, 결제 작업에 `src/payment/**`를 맡기고 서로 다른 포트와 테스트 DB를 지정합니다. 같은 포트를 쓰면 한 서버가 시작되지 않을 수 있고, 같은 DB를 초기화하면 서로의 픽스처를 지울 수 있기 때문입니다.
Worktree의 격리 대상은 작업 트리와 인덱스입니다. 외부 프로세스, 환경 변수, 컨테이너 이름, 캐시와 DB는 별도 설계가 필요합니다. 이 차이를 모르면 디렉터리는 둘인데 결과는 하나의 공유 환경에서 흔들립니다.
기준점과 소유 영역을 먼저 고정합니다. 원격 최신 상태를 받은 뒤 같은 커밋에서 두 브랜치를 만듭니다. `git worktree list --porcelain`은 스크립트가 읽기 좋은 안정 형식입니다. Git은 이미 다른 Worktree에서 체크아웃한 브랜치를 다시 연결하지 못하게 막으므로 이 보호 장치를 강제로 우회하지 않습니다.
git fetch origin
git status --short
git worktree add ../app-profile -b issue/184 origin/main
git worktree add ../app-payment -b issue/191 origin/main
git worktree list --porcelain에이전트 둘에게 같은 지시를 주지 않습니다. 프로필 작업에는 화면과 해당 테스트만, 결제 작업에는 재시도 서비스와 단위 테스트만 허용합니다. `package-lock.json`, 공통 라우터와 DB 스키마는 통합 담당자가 맡고, 각 작업에는 전용 포트와 테스트 DB를 배정합니다.
실행 전 파일 소유 표에서 겹침이 발견되면 한쪽 작업을 조사 전용으로 바꾸거나 순서를 정합니다. 두 에이전트가 공통 계약을 각자 바꾸게 두고 나중에 충돌을 푸는 방식은 병렬화가 아니라 재작업을 미루는 일입니다.
개별 성공 뒤 통합 상태에서 다시 실패할 수 있습니다. 프로필과 결제 브랜치의 관련 테스트가 각각 통과해도 통합 브랜치에서는 전체 회귀를 다시 실행합니다. 두 작업이 각기 다른 방식으로 공통 오류 타입을 가져오면 개별 테스트는 통과하지만 전체 타입 검사가 실패할 수 있습니다. 통합 담당자는 변경 파일 목록과 기준 커밋을 대조한 뒤 한 브랜치씩 반영하고 첫 실패 지점에서 멈춥니다.
병합 결과가 성공이라는 말은 개별 에이전트가 아니라 통합 상태의 테스트와 실제 화면이 결정합니다. 잠금 파일 변경이 필요해졌거나 API 계약이 달라졌다면 기존 작업 계약을 넘은 것이므로 자동 통합을 중단합니다.
삭제 명령은 깨끗한 작업 공간만 받아들입니다. Git의 `worktree remove`는 추적 변경이나 미추적 파일이 남은 Worktree를 기본적으로 거부합니다. 이것은 방해가 아니라 작업 손실을 막는 장치입니다. `--force`로 밀기 전에 커밋, 패치 보관 또는 폐기 여부를 사람이 결정합니다. 폴더를 파일 탐색기에서 먼저 지웠다면 `prune --dry-run`으로 정리 대상을 확인합니다.
git -C ../app-profile status --short
git -C ../app-profile log origin/main..HEAD --oneline
git worktree remove ../app-profile
git worktree prune --dry-run
git worktree prune
git worktree listWorktree를 쓰지 말아야 하는 경우. 두 작업이 같은 마이그레이션, 같은 잠금 파일, 같은 핵심 라우터를 바꾸거나 하나의 결과가 다음 작업의 전제가 되면 순차 작업이 낫습니다. 운영 DB와 하나뿐인 외부 샌드박스를 공유할 때도 디렉터리 분리는 안전 경계를 만들지 못합니다.
2026년 7월 29일 Git 공식 문서를 기준으로 `add`, `list`, `remove`, `prune`, `repair`, `lock`의 동작을 확인했습니다. 작업 폴더를 수동 이동해 연결이 깨졌을 때는 내부 `.git` 파일을 직접 고치기보다 `git worktree repair`를 사용합니다.