Claude Code 워크트리 병렬 작업 — 기본은 main에서 갈라지고, 확인 못 하는 명령은 그냥 거부합니다

AI 세션을 두세 개 동시에 띄워본 분이라면 아실 겁니다 — 하나가 기능을 만드는 동안 다른 하나가 같은 파일을 고쳐서 엉키는 상황요. 공식 문서에 세션마다 별도의 작업 폴더를 주는 방법이 정리돼 있어서 읽어봤습니다. 명령 한 줄이면 되는데, 예상과 달랐던 게 둘 있었습니다 — 새 작업방은 내 현재 작업이 아니라 원격 기본 브랜치에서 갈라지고, 안전한지 확인할 수 없는 명령은 git과 아무 상관없어도 거부됩니다.

📌 30초 요약

• 명령에 옵션 하나만 붙이면 격리된 작업 폴더와 새 브랜치가 생깁니다. 이름은 생략해도 됩니다.
• 기본 분기점은 원격 기본 브랜치입니다. 내 미푸시 커밋을 가져가려면 설정을 바꿔야 합니다.
• 확인할 수 없는 셸 구문은 거부됩니다. git을 쓰지 않는 명령도요. 이 검사는 끌 수 없습니다.
• 환경변수 파일은 자동으로 안 따라옵니다. 따로 목록을 만들어두면 복사됩니다.
• "다시 묻지 않기" 승인은 본체 쪽에 저장됩니다. 작업방을 지워도 남고 다른 방에도 적용됩니다.
• 내가 직접 만든 작업방은 자동 청소가 절대 안 지웁니다. 대신 비대화형 실행은 정리도 안 합니다.

명령 한 줄이면 작업방이 생깁니다

원리는 간단합니다. 같은 저장소 이력과 원격을 공유하면서 파일과 브랜치만 따로 갖는 작업 폴더를 만드는 겁니다. 그래서 한쪽 세션의 수정이 다른 쪽 파일에 절대 닿지 않습니다. 에이전트 도구들이 왜 전부 이 방식을 쓰는지 정리했을 때의 그 구조가, 이제 옵션 하나로 들어왔습니다.

# 이름을 주면 그 이름으로 폴더와 브랜치가 생김
claude --worktree feature-auth

# 다른 터미널에서 다른 이름으로 하나 더
claude --worktree fix-login

# 이름을 빼면 알아서 지어줌 (bright-running-fox 같은 식)
claude --worktree

만들어지는 위치는 저장소 루트의 설정 폴더 아래이고, 브랜치 이름은 접두어 + 내가 준 이름입니다. 문서가 팁으로 하나 붙여뒀는데 — 그 폴더를 무시 목록에 넣어두라는 것입니다. 안 그러면 본체에서 추적 안 되는 파일 더미로 보입니다. 그리고 대화형으로 쓰려면 그 폴더를 한 번 신뢰해둔 상태여야 합니다. 처음이면 그냥 한 번 실행해 신뢰 대화상자를 통과시키라고 안내합니다.

내 작업이 아니라 main에서 갈라집니다

여기서 한 번 놀랄 수 있습니다. 새 작업방은 내가 지금 작업 중인 브랜치가 아니라 원격의 기본 브랜치에서 시작합니다. 아직 안 올린 커밋이 있다면 새 방에는 그게 없습니다. 의도된 기본값인데, 모르면 "만들었더니 내 작업이 사라졌다"로 읽힙니다.

설정값	어디서 갈라지나	언제 쓰나
기본값	원격의 기본 브랜치. 깨끗한 상태에서 출발	독립적인 새 기능·버그 수정
현재 기준	내 로컬 최신 커밋. 미푸시 작업까지 따라옴	진행 중인 작업 위에서 일을 나눌 때

기본값 쪽에는 보이지 않는 동작이 하나 더 있습니다. 저장소를 24시간 안에 가져온 적이 없으면 기본 브랜치를 새로 받아오는데, 5초를 넘기면 포기하고 로컬에 캐시된 걸 씁니다. 원격이 아예 없거나 캐시도 없으면 내 현재 위치로 되돌아갑니다. 즉 같은 명령이 네트워크 상태에 따라 다른 지점에서 갈라질 수 있습니다. 참고로 이 설정에는 브랜치 이름을 직접 적을 수 없습니다 — 특정 브랜치에서 시작하려면 git으로 직접 만들라고 안내합니다.

확인 못 하는 명령은 그냥 거부합니다

격리가 말뿐이 아니라 실제로 막는다는 게 이 문서에서 제일 인상적이었습니다. 작업방 안에 있는 동안 네 가지 검사가 돌고, 걸리면 도구 호출 자체가 차단됩니다. 세션이 띄운 모든 하위 에이전트에도 똑같이 적용됩니다.

검사	무엇을 막나
파일 편집	본체 쪽 경로를 대상으로 한 수정·생성
작업 디렉터리	본체에서 도는 명령, 또는 밖에 머무는지 확인 안 되는 명령
git 우회	옵션·환경변수·본체로 이동 후 실행 등 git을 본체로 돌리는 모든 경로
명령 모양	안에 머문다고 정적으로 추적할 수 없는 셸 구문 전부

넷째 줄이 핵심입니다. git이 전혀 없는 명령이라도 차단됩니다. 중괄호 확장이나 따옴표 없는 여러 줄 입력처럼 어디로 튈지 정적으로 못 읽는 구문이면 거부하고, "평범한 명령 여러 개로 쪼개라"고 Claude에게 알려줍니다. 그리고 문서가 한 문장을 덧붙입니다 — 이 검사는 끌 수 없습니다. 명령이 이유 없이 거부되는 것처럼 보였다면 이걸 의심해 볼 만합니다.

🔑 환경변수 파일은 자동으로 안 따라옵니다

새 작업방은 깨끗한 체크아웃이라, 무시 목록에 들어 있는 환경변수 파일이나 로컬 설정은 그대로 없습니다. 그래서 실행하자마자 안 돌아가는 일이 생기죠. 해결책이 있는데, 프로젝트 루트에 복사할 파일 목록을 담은 파일을 하나 두면 새 작업방을 만들 때마다 자동으로 옮겨줍니다. 문법은 무시 목록 파일과 같고요. 안전장치도 걸려 있습니다 — 패턴에 맞으면서 동시에 무시 목록에 들어 있는 파일만 복사돼서, 이미 추적 중인 파일이 중복될 일은 없습니다. 다만 git이 아닌 버전관리를 훅으로 대체해 쓰는 경우엔 이 목록이 처리되지 않으니 훅 스크립트 안에서 직접 복사해야 합니다.

작업방끼리 공유하는 것이 셋 있습니다

파일과 브랜치는 따로지만 전부 따로인 건 아닙니다. 문서가 공유되는 셋을 명시하는데, 세 번째가 실무에서 제일 반가운 변화였습니다.

공유되는 것	그래서 좋은 점
저장소 메타데이터	샌드박스를 켜둬도 작업방 안에서 커밋이 됩니다
프로젝트 플러그인	방마다 다시 설치할 필요가 없습니다
권한 승인	한 번 허용하면 본체와 다른 모든 방에 적용됩니다

세 번째를 풀어보면 — 작업방에서 "다시 묻지 않기"를 누르면 그 규칙이 본체 쪽 로컬 설정 파일에 저장됩니다. 그래서 본체에서도, 다른 작업방에서도 적용되고 그 방을 지워도 살아남습니다. 예전에는 방 안에 저장돼서 다른 데선 안 먹고 방을 지우면 같이 사라졌습니다. 병렬로 여러 방을 굴리면서 같은 승인을 계속 눌러야 했다면, 그게 이 이유였습니다. 설정이 어디에 저장되는지가 이렇게 자주 문제가 됩니다.

🧹 정리는 알아서 되지만, 안 되는 경우가 있습니다

세션을 끝낼 때 지우면 사라질 작업이 있는지 먼저 확인합니다 — 수정·미추적 파일과 새 커밋을요. 깨끗하면 자동으로 지우고(이름을 붙인 세션은 물어봅니다), 작업이 남아 있으면 지울지 말지 묻습니다. 하위 에이전트가 쓰던 방은 변경이 없으면 끝나는 즉시 제거되고, 있으면 주기적 청소가 안전할 때만 치웁니다. 여기서 중요한 두 가지 — 내가 옵션으로 직접 만든 방은 자동 청소가 절대 건드리지 않습니다. 반대로 비대화형으로 돌린 세션은 종료 질문이 없어서 정리도 안 됩니다 — 방도 잠금도 남습니다. 그리고 윈도우에서는 방을 지울 때 폴더처럼 보이는 링크는 링크만 지우고 원본은 남깁니다.

🧾 정직하게 — 이 글의 한계

• 직접 여러 개를 굴려보고 쓴 글이 아닙니다. 공식 문서를 정리한 것이라, 실제로 몇 개까지 쾌적한지, 디스크가 얼마나 드는지는 제가 잰 범위에 없습니다.
• 버전 경계가 유난히 많은 문서입니다. 승인 저장 위치, 재사용 시 리셋, 잠금 해제, 윈도우 링크 처리가 전부 특정 버전부터라 옛 버전에서는 동작이 다릅니다.
• 오류 메시지 대응표는 옮기지 않았습니다. 거부·복구 메시지가 여러 갈래인데, 실제로 만났을 때 원문과 대조하는 편이 정확합니다.
• git 저장소가 전제입니다. 다른 버전관리는 훅으로 대체할 수 있다고 안내하지만, 그 경로는 제가 확인하지 못했습니다.

🗺️ AI 지출 전체 지도

세션을 여러 개 굴리면 토큰도 그만큼 병렬로 나갑니다. 격리는 충돌을 막아주지만 청구서를 막아주진 않고요. 구독과 종량제 선택부터 캐시, 모델 조합, 상한 걸기까지 지금까지 확인한 것들을 일곱 단계 지도 한 장으로 묶어뒀습니다.

자주 묻는 것

Q. 하위 에이전트마다 방을 따로 줄 수 있나요?

됩니다. 그때그때 "에이전트들은 작업방을 써라"라고 말해도 되고, 직접 만든 서브에이전트라면 머리말에 격리 항목 한 줄을 추가해 영구히 고정할 수 있습니다. 각자 임시 방을 받고, 변경 없이 끝나면 즉시 정리됩니다. 주의할 점은 분기점인데 — 에이전트 방도 기본은 원격 기본 브랜치라, 진행 중인 작업 위에서 일을 시키려면 앞에서 본 설정을 바꿔둬야 합니다.

Q. 남의 PR을 받아서 보려면요?

옵션에 번호 앞에 우물 정 기호를 붙이거나 PR 주소를 그대로 넘기면 됩니다. 깃허브와 깃랩 주소를 모두 받고, 재미있는 건 주소에서 번호만 읽는다는 점입니다 — 받아오는 경로는 내 저장소 원격의 호스트를 보고 결정합니다. 자체 호스팅이라 판단이 안 되면 두 가지 경로를 순서대로 시도합니다. 참고로 셸에서 우물 정 기호는 주석 시작으로 읽히니 따옴표로 감싸라고 문서가 짚어줍니다.

Q. 같은 이름을 다시 쓰면 어떻게 되나요?

이미 있으면 새로 만들지 않고 그 방을 엽니다. 그런데 조건이 맞으면 기본 브랜치 최신 상태로 초기화됩니다 — 변경 사항이 없고, 원래 브랜치 그대로이며, 자체 커밋이 없거나 PR이 병합되어 원격 브랜치가 사라진 경우입니다. 마지막 조건이 흥미로운데, 병합 여부를 git 상태만으로 판정합니다 — 밀어둔 원격 브랜치가 없어졌고 모든 커밋이 기본 브랜치에 이미 들어가 있으면 병합된 걸로 봅니다. 하나라도 안 맞거나 판단이 안 서면 예전 상태 그대로 엽니다.

📦 큰 저장소라면 워크트리를 통째로 만들지 않아도 됩니다 (8월 18일 추가)

이 글은 워크트리를 어떻게 갈라 쓰는가를 다뤘는데, 기본값이 저장소 전체 체크아웃이라는 점은 짚지 않았습니다. 큰 코드베이스 공식 가이드에 이걸 줄이는 설정 둘이 있습니다 — 필요한 폴더만 체크아웃하는 설정과 무거운 폴더를 원본으로 심링크하는 설정입니다. 워크트리마다 의존성 폴더를 복제하지 않게 되죠. 그런데 여기에 조용한 함정이 하나 있습니다 — 문서가 루트 레벨 파일은 항상 같이 체크아웃되지만 루트 레벨 디렉터리는 아니라고 적어놨습니다. 즉 잠금 파일 같은 건 알아서 딸려오는데 설정 폴더는 목록에 직접 적지 않으면 안 들어옵니다. 그러면 워크트리 안에서 루트의 설정·규칙·스킬이 전부 없는 상태가 됩니다. 여기에 하나 더 붙는데, 워크트리가 만들어지면 작업 폴더가 워크트리 루트로 바뀌어서 하위 패키지에 적어둔 프로젝트 설정은 워크트리 안에서 로드되지 않습니다. 문서가 같은 규칙을 두 곳에 적어두라고 예시를 드는 이유가 이것입니다. 자세한 내용은 큰 코드베이스 설정을 정리한 글에 적었습니다.

✨ 오늘 확인한 것 정리

옵션 하나면 세션마다 격리된 작업 폴더가 생기고, 파일 충돌이 원천적으로 사라집니다. 다만 기본 분기점이 내 작업이 아니라 원격 기본 브랜치라는 것과, 환경변수 파일이 자동으로 안 따라온다는 것부터 알고 시작하세요. 격리는 말뿐이 아니라서 밖으로 나가는지 확인할 수 없는 명령은 git과 무관해도 거부되고, 그 검사는 끌 수 없습니다.

※ 확인 경로(2026년 8월 17일 기준): code.claude.com/docs/en/worktrees. 우리말 표현은 제가 옮긴 것입니다.

※ 이 문서는 버전별 동작 차이가 많습니다. 승인 저장 위치·이름 재사용·잠금 해제·윈도우 링크 처리는 특정 버전 이상에서만 위와 같이 동작합니다.