Claude Code Git 작업 흐름 — 워크트리로 나눠 돌리고 체크포인트로 되돌리기

KAITABASE가 공식 문서와 원문을 직접 읽고 새로 쓴 가이드입니다.

이 가이드로 할 수 있는 것

Claude Code로 코드를 고치다 보면 두 가지가 겁납니다. 하나는 세션 두 개가 같은 파일을 동시에 고쳐 꼬이는 것이고, 다른 하나는 AI가 엉뚱한 방향으로 고쳐 놓은 것을 되돌리기 어려운 것입니다. 공식 문서는 이 둘을 서로 다른 도구로 풉니다.

공식 체크포인트 문서는 체크포인트가 Git을 대신하지 않는다고 분명히 적습니다. 이 가이드는 세 가지를 한 흐름으로 묶습니다.

빠른 시작

커밋이 하나 이상 있는 저장소 루트에서, 터미널 두 개에 각각 실행합니다(공식 문서 기준, 직접 실행 안 함).

claude --worktree feature-auth
claude --worktree bugfix-123

각 세션은 저장소 루트의 .claude/worktrees/<이름>/ 폴더에서 worktree-<이름> 이라는 새 브랜치로 시작합니다. 이름을 빼면 bright-running-fox 같은 이름을 Claude가 지어 줍니다. 세션 안에서 잘못 고친 것은 Esc 를 두 번(입력창이 비어 있을 때) 누르거나 /rewind 로 되돌립니다.

STEP 1. 연습용 저장소 준비하기

목표: 워크트리를 만들 수 있는 저장소 상태를 갖춥니다. · 예상 시간: 3분

워크트리는 기존 커밋에서 갈라져 나오므로 커밋이 최소 하나 있어야 합니다. 공식 문서에 따르면 커밋이 없는 저장소에서 claude --worktree 를 실행하면 Failed to resolve base branch "HEAD": git rev-parse failed 로 실패합니다.

123456mkdir demo && cd demo
git init -b main
echo "hello" > app.txt
printf ".claude/worktrees/\n.env\n" > .gitignore
git add app.txt .gitignore
git commit -m init

공식 문서는 .claude/worktrees/ 를 .gitignore 에 넣어 워크트리 내용이 원래 폴더에서 추적되지 않은 파일로 보이지 않게 하라고 권합니다.

확인 git log --oneline 에 커밋 한 줄이 보이면 준비가 끝났습니다.

막히면 처음 쓰는 폴더라면 claude --worktree 가 작업 공간 신뢰(workspace trust) 확인을 요구하며 멈출 수 있습니다. 공식 문서는 그 폴더에서 claude 를 한 번 실행해 신뢰 창을 승인하라고 안내합니다.

STEP 2. Git으로 워크트리를 직접 만들어 보기

목표: 워크트리가 무엇인지 Git 명령으로 눈으로 확인합니다. · 예상 시간: 4분

Claude Code의 --worktree 는 Git 워크트리 위에서 동작합니다. 먼저 Git 명령만으로 만들어 보면 구조가 보입니다. 아래는 공식 문서의 "Manage worktrees manually" 절 명령이며, 2026-10-22에 git 2.53.0으로 직접 실행했습니다.

git worktree add ../demo-feature-a -b feature-a
git worktree list

실제 출력:

1234Preparing worktree (new branch 'feature-a')
HEAD is now at df06e9a init
.../demo            df06e9a [main]
.../demo-feature-a  df06e9a [feature-a]

같은 커밋을 가리키는 폴더 두 개가 생겼고, 각자 다른 브랜치에 있습니다. 한쪽 폴더에서 고친 파일은 다른 쪽에 보이지 않습니다. 이미 있는 브랜치로 만들 때는 -b 없이 git worktree add ../demo-bugfix fix-issue-456 처럼 씁니다.

확인 새 폴더 ../demo-feature-a 에 app.txt 와 .gitignore 가 있고 .env 는 없습니다. 직접 실행했을 때도 Git이 추적하지 않는 .env 는 복사되지 않았습니다.

막히면 경로에 한글이 들어 있으면 git worktree list 가 경로를 \355\232\214... 처럼 8진수 문자로 표시합니다. 실제 경로가 깨진 것이 아니라 Git의 표시 방식이므로 그대로 써도 됩니다.

STEP 3. Claude Code로 워크트리 세션 열기

목표: 세션마다 따로 떨어진 작업 공간을 줍니다. · 예상 시간: 4분

공식 문서 기준(직접 실행 안 함):

claude --worktree feature-auth

알아 둘 기본값은 다음과 같습니다.

• 위치: 저장소 루트의 .claude/worktrees/feature-auth/
• 브랜치: worktree-feature-auth
• 출발점: 기본값 "fresh" 는 원격의 기본 브랜치(보통 main)에서 갈라집니다. 지금 작업 중인 로컬 HEAD 에서 갈라지려면 설정에서 worktree.baseRef 를 "head" 로 둡니다.
• PR에서 시작: claude --worktree "#1234" 처럼 # 을 붙인 PR 번호나 GitHub PR · GitLab MR 주소를 주면 .claude/worktrees/pr-<번호> 에 그 변경의 마지막 커밋으로 만듭니다. # 이 주석으로 읽히지 않게 따옴표를 붙입니다.

세션 중에 "워크트리에서 작업해 줘"라고 요청해도 Claude가 EnterWorktree 도구로 만들어 들어갑니다.

확인 공식 문서에 따르면 워크트리 세션에서는 Claude Code가 원래 폴더(main checkout)를 고치는 Edit · Write 와, 원래 폴더로 Git을 돌리는 명령을 막습니다. 다만 cp 나 셸 리디렉션처럼 Git을 쓰지 않고 원래 폴더에 쓰는 명령까지 막지는 않습니다.

막히면 워크트리는 새로 꺼낸 폴더라 node_modules 나 .env 가 없습니다. 의존성 설치를 Claude에게 맡기고, .env 처럼 Git이 무시하는 파일은 다음 STEP의 .worktreeinclude 로 옮깁니다.

STEP 4. .env 같은 파일을 워크트리로 옮기기

목표: Git이 추적하지 않는 설정 파일을 새 워크트리마다 자동 복사합니다. · 예상 시간: 3분

저장소 루트에 .worktreeinclude 파일을 만듭니다. 문법은 .gitignore 와 같고, 패턴에 맞으면서 Git이 무시하는 파일만 복사됩니다.

.env
.env.local
config/secrets.json

이 파일은 Claude Code가 Git으로 만드는 모든 워크트리(--worktree, 서브에이전트 워크트리, 데스크톱 앱 병렬 세션)에 적용됩니다.

확인 STEP 2에서 본 것처럼 git worktree add 로 직접 만든 워크트리에는 .env 가 복사되지 않습니다. 공식 문서도 .worktreeinclude 는 Claude Code가 만드는 워크트리에 적용된다고 설명하므로, 직접 만든 워크트리라면 필요한 파일을 손으로 복사합니다.

주의 비밀 값이 든 파일을 복사 대상으로 넣으면 워크트리 수만큼 사본이 늘어납니다. 워크트리를 다 쓰면 STEP 5대로 지웁니다.

STEP 5. 끝난 워크트리 정리하기

목표: 남은 작업을 잃지 않고 워크트리를 지웁니다. · 예상 시간: 3분

Claude Code로 연 워크트리 세션을 끝낼 때 공식 문서의 동작은 다음과 같습니다.

-p 로 돌린 비대화형 실행은 종료 질문이 없어 워크트리를 치우지 않습니다. 이때와 직접 만든 워크트리는 Git으로 지웁니다. 직접 실행해 본 결과입니다.

echo "change" >> ../demo-feature-a/app.txt
git worktree remove ../demo-feature-a

fatal: '../demo-feature-a' contains modified or untracked files, use --force to delete it

Git은 고친 내용이 있으면 지우기를 거부합니다. 정말 버려도 될 때만 --force 를 붙입니다. 잠겨 있다는 오류가 나면 git worktree unlock 을 먼저 실행합니다.

확인 git worktree remove --force ../demo-feature-a 뒤 git worktree list 에는 원래 폴더 한 줄만 남았습니다. 그런데 git branch 에는 feature-a 브랜치가 그대로 남아 있었습니다. 워크트리를 지워도 Git으로 직접 만든 브랜치는 지워지지 않으므로, 필요 없으면 git branch -D feature-a 로 따로 지웁니다.

되돌리기 --force 로 지운 워크트리의 커밋하지 않은 변경은 되살릴 수 없습니다. 지우기 전에 커밋하거나 git stash 로 옮겨 둡니다.

STEP 6. 체크포인트로 몇 턴 되돌리기

목표: Claude가 방금 고친 내용을 세션 안에서 빠르게 되돌립니다. · 예상 시간: 4분

공식 문서 기준(직접 실행 안 함): Claude Code는 내가 보내는 프롬프트마다 그 직전 코드 상태를 자동으로 저장합니다. 세션당 최근 100개 체크포인트의 파일 사본을 보관하고, 대화와 함께 저장되므로 세션을 다시 열어도 /rewind 를 쓸 수 있습니다.

/rewind 를 입력하거나, 입력창이 비어 있을 때 Esc 를 두 번 누르면 메뉴가 열립니다. 되돌릴 프롬프트를 고른 뒤 동작을 고릅니다.

주의 체크포인트는 Claude의 파일 편집 도구로 바뀐 것만 기록합니다. rm · mv · cp 같은 Bash 명령으로 바뀐 파일, 내가 편집기에서 직접 고친 파일, 다른 세션이 고친 파일은 되돌리지 못합니다. 백그라운드 서브에이전트가 고친 파일도 대부분 되돌려지지 않으니 Git으로 되돌립니다. 심볼릭 링크 · 하드 링크 파일은 건너뛰고 Restored the code, but skipped N files 경고를 보여 줍니다.

막히면 파일 사본은 기본적으로 세션이 마지막으로 저장한 지 약 30일 뒤 정리됩니다. 그 뒤에 되돌리면 No files were restored 로 실패할 수 있습니다. 더 오래 두려면 cleanupPeriodDays 설정을 늘립니다. 다른 방향을 시험해 보고 싶다면 요약 대신 /branch 나 claude --continue --fork-session 으로 세션을 갈라 둡니다.

STEP 7. 결과를 커밋 · PR로 남기기

목표: 세션 안의 작업을 영구 기록으로 옮깁니다. · 예상 시간: 2분

공식 Common workflows 문서의 순서대로 요청합니다.

summarize the changes I've made to the authentication module
create a pr

Claude가 gh pr create 로 PR을 만들면 세션과 PR이 연결되어, 나중에 claude --from-pr 1234 로 그 PR에 연결된 세션을 찾을 수 있습니다. 공식 문서는 제출 전에 Claude가 만든 PR을 직접 검토하고 위험 요소를 짚어 달라고 요청하라고 권합니다. 고치기 전에 계획부터 보고 싶다면 claude --permission-mode plan 으로 시작합니다.

잘못 쓰는 예 · 바르게 쓰는 예

바로 쓰는 프롬프트 · 템플릿

워크트리 세션을 시작하며 첫 메시지로 붙입니다.

이 세션은 워크트리에서 돌고 있습니다. 먼저 의존성을 설치하고 테스트가 통과하는지 확인해 주세요.
작업 범위는 src/auth 폴더로 제한하고, 다른 폴더는 고치지 마세요.
끝나면 바뀐 파일 목록과 테스트 결과를 보여 주고, 커밋 메시지 초안을 제안해 주세요. 커밋은 제가 확인한 뒤에 하겠습니다.

서브에이전트를 늘 워크트리에서 돌리려면 .claude/agents/ 에 이렇게 둡니다(공식 문서 예시를 옮김).

12345678---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

Apply the requested refactor across every affected file, then run the tests
and report the results.

주의할 점

• 권한: 워크트리 세션에서 "Yes, and don't ask again" 으로 허락한 Bash 규칙은 원래 폴더의 .claude/settings.local.json 에 저장되어 다른 워크트리에도 적용됩니다. 다만 공식 문서는 Windows 등 일부 경우에는 그 워크트리에만 남는다고 설명합니다.
• 보안: .worktreeinclude 로 비밀 파일을 복사하면 사본이 늘어납니다. Git LFS를 git lfs install --local 로 설정한 저장소는 Claude Code가 만든 워크트리에 실제 파일 대신 포인터 파일이 들어가므로, 워크트리 안에서 git lfs pull 을 실행합니다.
• 요금: 세션을 여러 개 동시에 돌리면 그만큼 사용량이 함께 늘어납니다. 요금제는 claude.com/pricing에서 확인합니다.
• 한계: 체크포인트는 버전 관리를 대신하지 않습니다(공식 문서). 팀과 공유할 기록은 반드시 커밋 · PR로 남깁니다.
• 라이선스: 이 가이드는 Anthropic 공식 문서를 우리 말로 다시 정리한 것입니다. Git 명령의 전체 옵션은 Git 공식 문서를 봅니다.

공식 자료

• Run parallel sessions with worktrees — https://code.claude.com/docs/en/worktrees
• Checkpointing — https://code.claude.com/docs/en/checkpointing
• Common workflows — https://code.claude.com/docs/en/common-workflows
• Manage sessions(/branch · --fork-session) — https://code.claude.com/docs/en/sessions
• Git worktree 공식 문서 — https://git-scm.com/docs/git-worktree

더 보기

이 가이드는 KAITABASE가 공식 문서와 원문을 직접 읽고 실행해 본 뒤 새로 쓴 자료입니다. 같은 주제의 다른 글은 KAITABASE에서 이어서 볼 수 있습니다.

• AI 코딩 자료 모음 — https://kaitabase.vercel.app/?area=coding
• KAITABASE 전체 자료 — https://kaitabase.vercel.app