Worktree — 병렬 AI 코딩10-3
자주 쓰는 명령어와 문제 해결
Worktree 관련 필수 명령어를 정리하고, 자주 발생하는 오류와 해결 방법을 배웁니다. 터미널 출력 읽는 법도 함께 익힙니다.
명령어 모음 — 이것만 알면 됩니다
Worktree와 관련하여 실무에서 쓰는 명령어는 사실 몇 개 되지 않습니다. 아래 표를 참고하세요.
claude --worktree 이름 (또는 claude -w 이름): 새 워크트리를 만들면서 Claude Code를 바로 실행합니다. 가장 많이 쓰는 명령어입니다.
git worktree list: 현재 만들어져 있는 워크트리 목록을 보여줍니다. "지금 몇 개의 책상이 펼쳐져 있지?" 확인할 때 씁니다.
git worktree remove 이름: 특정 워크트리를 삭제합니다. "이 책상은 다 썼으니 치워주세요" 하는 것입니다.
git worktree prune: 이미 삭제된 폴더와 연결된 워크트리 기록을 정리합니다. "사무실 대청소" 같은 명령어입니다.
일상적으로는 claude -w 이름과 git worktree list 두 가지만 기억하시면 충분합니다.
# 새 워크트리 만들기 + Claude Code 실행
claude --worktree feature-name
claude -w feature-name # 짧은 버전 (동일한 기능)
# 현재 워크트리 목록 확인
git worktree list
# 출력 예시:
# /Users/silro/project abc1234 [main]
# /Users/silro/project/.claude/worktrees/unfair-dismissal def5678 [unfair-dismissal]
# /Users/silro/project/.claude/worktrees/wage-claim ghi9012 [wage-claim]
# 특정 워크트리 삭제
git worktree remove .claude/worktrees/wage-claim
# 연결 끊어진 워크트리 기록 정리
git worktree prune터미널 출력 읽는 법
터미널에 표시되는 메시지가 처음에는 낯설 수 있습니다. 자주 보게 되는 메시지와 그 의미를 정리했습니다.
$ 기호: 이 뒤에 명령어를 입력하라는 표시입니다. "여기에 말씀하세요"라는 안내와 같습니다. $ 기호 자체를 입력하는 것이 아닙니다.
"Switched to branch 'unfair-dismissal'": 새 브랜치로 전환되었다는 안내입니다. "부당해고 책상으로 이동했습니다"라는 뜻입니다.
"Created worktree at ...": 워크트리가 성공적으로 만들어졌다는 안내입니다. "새 책상이 준비되었습니다"와 같습니다.
"error:" 또는 "fatal:": 뭔가 잘못되었다는 표시입니다. 당황하지 마세요. 대부분 간단히 해결됩니다. 다음 섹션에서 해결법을 알려드립니다.
"(END)": 표시할 내용이 많을 때 나타납니다. q 키를 누르면 빠져나올 수 있습니다. 엔터를 계속 쳐도 빠져나오지 않으니, 반드시 q를 누르세요.
TIP: 터미널 메시지가 영어여서 겁이 날 수 있지만, 실제로 중요한 단어는 몇 개 되지 않습니다. error, success, created, switched 정도만 알면 대부분의 상황을 파악할 수 있습니다.
3가지 원칙 — 안전하게 사용하기
Worktree를 사용할 때 지켜야 할 3가지 원칙이 있습니다.
원칙 1: 3~4개까지만 동시에 운영하세요.
워크트리를 너무 많이 열면 컴퓨터 성능이 느려지고, 어떤 워크트리에서 무슨 작업을 하는지 관리가 어려워집니다. 사무실에서도 책상을 10개 펼쳐놓으면 오히려 혼란스러운 것과 같습니다. 초보자는 2개, 익숙해지면 3~4개가 적절합니다.
원칙 2: 끝난 작업은 바로 정리하세요.
완료된 워크트리를 그대로 두면 쌓이면서 혼란을 유발합니다. claude --worktree로 만든 워크트리는 자동 정리 기능이 있지만, 수동으로 만든 것은 직접 정리해야 합니다. 마치 사용한 서류는 바로 정리해서 캐비닛에 넣어야 사무실이 깔끔한 것과 같습니다.
원칙 3: 같은 브랜치를 두 개의 워크트리에서 동시에 열지 마세요.
같은 서류를 두 책상에서 동시에 수정하면 "어느 쪽이 최종본이지?" 하는 혼란이 생깁니다. Git도 마찬가지로, 같은 브랜치를 두 워크트리에서 동시에 열면 충돌이 발생합니다. 하나의 브랜치는 하나의 워크트리에서만 작업하세요.
TIP: git worktree list 명령으로 수시로 현재 열려있는 워크트리를 확인하는 습관을 들이세요. 정리되지 않은 워크트리가 쌓이면 나중에 혼란스러워집니다.
자주 발생하는 문제와 해결법
Worktree를 사용하다 보면 몇 가지 오류를 만날 수 있습니다. 미리 알아두면 당황하지 않습니다.
문제 1: "fatal: 'branch-name' is already checked out"
같은 브랜치를 다른 워크트리에서 이미 사용 중일 때 나타납니다. 해결: 다른 이름으로 워크트리를 만드세요. claude -w wage-claim-2 처럼 숫자를 붙이면 됩니다.
문제 2: 워크트리 폴더가 남아있음
자동 정리가 되지 않아 .claude/worktrees/ 아래에 폴더가 남아있는 경우입니다. 해결: git worktree remove 폴더이름 으로 삭제하거나, git worktree prune 으로 일괄 정리합니다.
문제 3: API 비용이 걱정됩니다
워크트리를 여러 개 돌리면 각각 AI를 사용하므로 비용이 늘어날 수 있습니다. 해결: Claude Pro/Max 요금제를 사용하시면 월정액이므로 워크트리 수에 관계없이 비용이 일정합니다. 또는 꼭 필요한 작업만 병렬로 돌리세요.
문제 4: 컴퓨터가 느려집니다
워크트리를 4개 이상 동시에 돌리면 메모리 사용량이 늘어 느려질 수 있습니다. 해결: 완료된 워크트리를 정리하고, 동시 실행 수를 줄이세요.
# 문제 1 해결: 이미 사용 중인 브랜치 → 다른 이름 사용
claude -w wage-claim-2
# 문제 2 해결: 남아있는 워크트리 정리
git worktree list # 먼저 목록 확인
git worktree remove .claude/worktrees/old-work # 특정 항목 삭제
git worktree prune # 일괄 정리
# 현재 상태 점검 (추천: 하루에 한 번)
git worktree list최적 병렬 수 — 단계별 가이드
동시에 몇 개의 워크트리를 운영하는 것이 좋을까요? 경험 수준에 따라 다릅니다.
초보 단계 (지금): 2개까지.
처음 Worktree를 사용하실 때는 2개만 열어서 연습하세요. 하나의 터미널에서 AI가 작업하는 동안 다른 터미널의 결과를 확인하는 흐름에 익숙해지는 것이 먼저입니다.
중급 단계 (2~3주 후): 3~4개.
2개가 편해지면 3~4개로 늘려봅니다. 이 정도면 오전에 밀린 사건 3~4건을 동시에 AI에게 맡기고, 완료되는 순서대로 검토할 수 있습니다.
숙련 단계 (1개월 이후): 5개 이상.
Claude Code의 --remote 기능(이전 레슨 참조)과 결합하면 5개 이상도 가능합니다. 다만 로컬 컴퓨터에서는 메모리 한계가 있으므로, 클라우드 실행과 병행하는 것이 좋습니다.
핵심은 "내가 관리할 수 있는 만큼만" 열어두는 것입니다. 10개를 열어놓고 3개만 확인하면 나머지 7개는 낭비입니다. 사무실에서 책상을 10개 펼쳐놓고 3개만 쓰면 나머지 7개는 공간만 차지하는 것과 같습니다.
TIP: 처음에는 2개부터 시작하세요. '아, 이제 2개는 편하다' 싶을 때 3개로 늘리면 됩니다. 절대 서두르지 마세요.
핵심 정리
- ✓일상적으로 claude -w 이름과 git worktree list 두 가지 명령어만 기억하면 충분합니다
- ✓터미널의 error, success, created 등 핵심 단어만 알면 상황을 파악할 수 있습니다
- ✓워크트리는 3~4개까지, 끝나면 바로 정리, 같은 브랜치 동시 사용 금지가 3가지 원칙입니다
- ✓초보자는 2개부터 시작하여 점차 늘려가는 것이 안전합니다