Worktree 관련 필수 명령어를 정리하고, 자주 발생하는 오류와 해결 방법을 배웁니다. 터미널 출력 읽는 법도 함께 익힙니다.
명령어 모음 — 이것만 알면 됩니다
클로드 코드 작업트리에 필요한 명령은 많지 않습니다. 시작·이어하기·목록 확인 세 가지면 충분하고, 나머지는 클로드에게 말로 시키면 됩니다.
대화 중에도 '이 작업은 작업트리에서 해줘'라고 하면 클로드가 작업트리로 들어가서(EnterWorktree) 일합니다. 하위 담당에게 나눠 맡길 때 '에이전트들은 작업트리를 쓰게 해줘'라고 하면 각자 임시 작업트리에서 일하고, 변경 없이 끝난 임시 작업트리는 자동으로 지워집니다.
작업공간 삭제와 오래된 기록 정리는 결과·소유자·미반영 변경을 확인한 뒤에만 진행합니다. 다른 담당자의 작업을 목록에서 봤다는 이유로 정리하지 않습니다.
(2026-11-06 Claude Code 공식 문서 확인 기준. 버전에 따라 달라질 수 있으니 실습 전 claude --version과 공식 문서를 함께 확인합니다.)
# 시작
claude --worktree practice-review
# 이어서 하기
claude --worktree practice-review --resume
# 지금 있는 작업트리 목록 확인 (읽기 전용)
git worktree list
# 기준을 '현재 위치(HEAD)'로 바꾸고 싶을 때: 설정의 worktree.baseRef 를 "head" 로
터미널 출력 읽는 법
터미널에 표시되는 메시지가 처음에는 낯설 수 있습니다. 자주 보게 되는 메시지와 그 의미를 정리했습니다.
$ 기호: 이 뒤에 명령어를 입력하라는 표시입니다. "여기에 말씀하세요"라는 안내와 같습니다. $ 기호 자체를 입력하는 것이 아닙니다.
"Switched to branch 'unfair-dismissal'": 새 브랜치로 전환되었다는 안내입니다. "부당해고 책상으로 이동했습니다"라는 뜻입니다.
"Created worktree at ...": 워크트리가 성공적으로 만들어졌다는 안내입니다. "새 책상이 준비되었습니다"와 같습니다.
"error:" 또는 "fatal:": 뭔가 잘못되었다는 표시입니다. 당황하지 마세요. 대부분 간단히 해결됩니다. 다음 섹션에서 해결법을 알려드립니다.
"(END)": 표시할 내용이 많을 때 나타납니다. q 키를 누르면 빠져나올 수 있습니다. 엔터를 계속 쳐도 빠져나오지 않으니, 반드시 q를 누르세요.
TIP: 터미널 메시지가 영어여서 겁이 날 수 있지만, 실제로 중요한 단어는 몇 개 되지 않습니다. error, success, created, switched 정도만 알면 대부분의 상황을 파악할 수 있습니다.
안전하게 사용하기 위한 세 가지 원칙
1. 독립적으로 처리할 수 있는 과제만 나누고 각 담당자의 수정 범위를 정합니다.
2. 결과와 미반영 이력을 검토하고 필요한 내용을 보존한 다음에만 정리를 검토합니다.
3. 같은 이력 갈래를 여러 작업트리에서 동시에 사용하려 할 때 깃이 제한할 수 있습니다. 실제 상태와 브랜치를 확인하고 별도 갈래를 사용합니다.
작업공간 수는 컴퓨터 성능·모델 사용량·검수 부담을 보고 조절합니다.
TIP: 목록 확인은 읽기 작업입니다. 삭제·정리는 파일과 이력 보존 확인 후 결정하세요.
자주 발생하는 문제와 해결법
브랜치가 이미 사용 중이라는 오류가 나오면 실제 작업트리 목록과 해당 브랜치를 확인합니다. 다른 작업을 중단하거나 삭제하지 않습니다.
사용량과 비용은 제품·요금제·계정·추가 사용 설정에 따라 달라집니다. 구독료와 별도 사용료, 한도를 현재 안내에서 확인하세요. 기기가 느리면 필요 없는 병렬 실행을 줄이되, 작업 종료와 결과 보존 여부는 먼저 점검합니다.
작업트리에서 '설정 파일이 없다'는 오류가 나면 대부분 깃에서 제외된 파일이 복사되지 않은 경우입니다. .worktreeinclude에 해당 파일 패턴이 있는지 확인합니다.
# 목록을 확인하고 각 작업의 상태를 기록합니다.
git worktree list
# 작업트리에서 .env 등이 없다고 나오면 → .worktreeinclude 확인
# 오류 내용과 프로젝트·경로를 확인한 뒤 해결합니다.
최적 병렬 수 — 단계별 가이드
처음에는 가상 자료를 이용한 작은 두 작업으로 배치와 결과 회수에 익숙해집니다. 늘리기 전에는 각 업무가 독립적인지, 실제 파일과 외부 자원을 함께 쓰는지, 검수할 사람이 있는지 확인합니다.
동시 실행에 적절한 숫자는 환경과 과제에 따라 달라집니다. 비용·속도·검수 부담을 함께 보고 정합니다.
TIP: 오류나 미확인은 완료로 표시하지 말고 원인과 남은 일을 기록하세요.