Phase 10 · Worktree — 병렬 AI 코딩10-2

Worktree 실전 — claude --worktree로 시작하기

Claude Code의 내장 Worktree 기능을 사용하여 실제로 여러 작업을 동시에 실행하는 방법을 단계별로 배웁니다.

Execution Kit

실습 중 막히지 않기 위한 진행표

준비

강의 전 현재 폴더, 계정, 설치 상태를 확인합니다.

실행

claude --worktree 이름은 .claude/worktrees/이름/에 worktree-이름 브랜치로 별도 작업공간을 열고 그 안에서 시작합니다.

검증

명령 결과, 파일 변화, 브라우저 화면 중 하나로 성공 여부를 확인합니다.

기록

잘 된 명령과 막힌 지점을 다음 실습을 위한 로그로 남깁니다.

막혔을 때 Claude Code에 붙여넣을 양식

나는 코딩 경험이 많지 않은 실무자입니다. "Worktree 실전 — claude --worktree로 시작하기" 강의를 따라 하고 있습니다.

현재 상태:
- 사용하는 컴퓨터:
- 방금 실행한 명령:
- 화면에 나온 결과 또는 오류:
- 내가 만들고 싶은 업무 결과물:

요청:
1. 지금 상황을 초보자 기준으로 진단해줘.
2. 다음에 실행할 명령을 한 줄씩 제시해줘.
3. 각 명령이 무엇을 하는지 쉬운 말로 설명해줘.
4. 성공 여부를 확인할 체크 포인트를 정리해줘.
5. 실패하면 다시 붙여넣을 오류 보고 양식을 만들어줘.

방법 A: claude --worktree (가장 쉬운 방법)

클로드 코드는 --worktree(줄여서 -w) 옵션 하나로 작업트리를 만들고 그 안에서 바로 시작합니다. 깃 저장소에 커밋이 최소 하나 있어야 하고, 처음 여는 폴더라면 작업공간 신뢰(trust) 확인을 먼저 거칩니다. 만들어지는 곳: 저장소 맨 위 폴더 아래 .claude/worktrees/<이름>/, 브랜치 이름은 worktree-<이름>입니다. 이름을 비워 두면 클로드가 임의의 이름을 붙입니다. claude --worktree "#1234"처럼 PR 번호를 주면 그 PR 내용을 받아 pr-1234 작업트리를 만듭니다. 끝낼 때: 대화형 세션을 종료하면서 변경·새 파일·새 커밋이 하나도 없으면 이름 없이 만든 작업트리는 자동으로 지워지고, 이름을 붙인 작업트리는 지울지 먼저 묻습니다. 변경이 있으면 남길지 지울지 묻고, 남기면 화면에 나오는 claude --worktree <이름> --resume으로 다시 들어옵니다. -p(한 번 실행) 방식은 종료 질문이 없어 자동 정리되지 않습니다. (2026-11-06 Claude Code 공식 문서 확인 기준. 버전에 따라 달라질 수 있으니 실습 전 claude --version과 공식 문서를 함께 확인합니다.)
# 이름을 붙여 시작
claude --worktree feature-login
# 줄임 옵션
claude -w bugfix-payment
# 만들어지는 곳: .claude/worktrees/feature-login/  (브랜치 worktree-feature-login)
# 나중에 이어서 하기
claude --worktree feature-login --resume
TIP: 종료할 때 '삭제할까요?'가 나오면 바로 누르지 말고, 결과를 합쳤는지 먼저 확인하세요. 남겨 두면 언제든 --resume으로 돌아올 수 있습니다.

작업트리에 빠지는 파일 — .worktreeinclude

새 작업트리는 깃에 기록된 파일만 가지고 시작합니다. .env 같은 설정 파일이나 깃에서 제외한 파일은 따라오지 않아서 '여기선 왜 안 되지?'가 자주 생깁니다. 저장소 맨 위에 .worktreeinclude 파일을 두고 .gitignore와 같은 형식으로 패턴을 적으면, 깃에서 제외된 파일 중 그 패턴에 맞는 것만 새 작업트리로 복사됩니다. claude --worktree와 서브에이전트 작업트리 모두에 적용됩니다.
# .worktreeinclude (예시)
.env.local
config/practice-settings.json
TIP: 비밀번호·API 키가 든 파일을 복사 대상에 넣으면 작업트리 수만큼 사본이 생깁니다. 실습은 가짜 값으로 하세요.

Step by Step: 두 개의 작업 동시에 열기

가상 예제 저장소에서 별도 터미널 두 개를 엽니다. 두 터미널이 같은 기준 프로젝트를 가리키는지 확인한 뒤 서로 다른 이름의 작업트리를 만듭니다. 각 창에서 실제 경로와 작업 내용을 확인하고 한쪽에 작성, 다른 쪽에 별도 검토를 맡깁니다. 두 작업을 합치기 전에 각 변경 내용을 살펴보고, 검수자가 작성자의 실제 결과를 볼 수 있도록 전달합니다. 같은 계정과 외부 사이트는 여전히 공유될 수 있습니다.
# 가상 연습 저장소에서 각기 다른 이름으로 실행
claude --worktree practice-a
claude --worktree practice-b
# 실행 후 각 터미널의 경로와 변경 내용을 확인합니다.

방법 B: 수동 설정 (git worktree add)

깃의 작업트리 명령을 사용하면 특정 기준과 폴더를 직접 지정할 수 있습니다. 기존 작업을 덮어쓰지 않도록 먼저 저장소의 현재 상태와 브랜치 사용 여부를 확인하세요. 삭제나 강제 정리는 미반영 변경과 다른 사람의 작업을 확인하기 전에는 실행하지 않습니다.
# 현재 작업공간을 읽기 전용으로 확인
git worktree list
# 작업트리 생성과 정리는 현재 Git 공식 안내와 프로젝트 지침을 따릅니다.
TIP: 처음에는 방법 A(claude --worktree)만 사용하세요. 방법 B는 나중에 익숙해진 후에 필요할 때 쓰면 됩니다.

노무사 시나리오: 독립 업무를 나누고 결과를 검수하기

세 가지 비식별 가상 업무를 준비합니다. A는 사건 사실 목록, B는 임금 자료의 누락 점검, C는 취업규칙 목차를 정리합니다. 실제 사건을 투입하기 전에 자료 접근과 전송 조건을 확인하세요. 독립적으로 수행 가능한 일은 병렬로 맡기되 한 담당자가 전체 결과를 회수합니다. 초안 완성은 법률 검증이나 사건 제출 완료를 의미하지 않습니다. 처리 시간은 자료와 검수량에 따라 달라지므로 근거 없는 단축률을 제시하지 않습니다.
A: 비식별 사실 목록과 미확인 사항
B: 자료 누락·계산 입력값 점검
C: 규정 목차와 검토 필요 사항
총괄: 실제 산출물·근거를 확인하고 노무사 판단에 전달
TIP: 화면 분할은 보이는 방식입니다. 각 창의 폴더가 같은지 다른지 따로 확인하세요.

핵심 정리

  • ✓claude --worktree 이름은 .claude/worktrees/이름/에 worktree-이름 브랜치로 별도 작업공간을 열고 그 안에서 시작합니다.
  • ✓변경이 없으면 종료 시 정리되고, 변경이 있으면 남길지 묻습니다. 남긴 작업은 --resume으로 다시 엽니다.
  • ✓깃에서 제외한 설정 파일은 .worktreeinclude에 적어야 새 작업트리로 복사됩니다.
  • ✓같은 화면의 분할 탭과 별도 작업트리는 다른 개념입니다.
  • ✓정리 전 미반영 결과와 작업 경로를 확인하고 타인의 작업을 보존합니다.
  • ✓가상 업무로 연습하고 성과는 검수 시간까지 포함해 직접 확인합니다.

이 강의가 어떠셨나요?