클로드 코드 Git 작업 흐름 (브랜치, 커밋, 워크트리)

이 글은 앤트로픽이 운영하는 code.claude.com/docs의 Common workflows, Worktrees, Checkpointing, Settings reference 문서를 한국어 사용자가 실무에 바로 옮길 수 있도록 정리한 글입니다. 명령과 설정 키는 2026년 9월 28일 공식 문서 기준이고, 원문 링크는 글 끝 참고 자료에 모았습니다.

🤔 클로드가 한 작업을 어디까지 되돌릴 수 있는지 모를 때

클로드 코드에게 기능 하나를 맡기고 나면 파일 여러 개가 바뀌어 있습니다. 결과가 마음에 들지 않을 때 어디까지 되돌릴 수 있는지, 커밋은 언제 해야 하는지, 버그 수정을 맡긴 사이에 다른 기능도 동시에 시켜도 되는지 판단이 필요해집니다.

Git의 기본 개념은 바이브코딩 기초 코스에 있습니다. 지금부터는 클로드 코드와 함께 Git을 쓸 때의 흐름, 즉 커밋과 PR을 맡기는 순서, 공동 작성자 표기 설정, 워크트리로 여러 세션을 나누는 법, 체크포인트와 Git이 각각 무엇을 되돌리는지 정리합니다.

🔑 클로드 코드 Git 작업 흐름의 정의

클로드 코드의 Git 작업 흐름은 브랜치를 나눠 작업하고, 확인한 변경만 커밋과 PR로 남기며, 여러 작업을 동시에 할 때는 워크트리로 폴더를 나누는 사용 방식입니다.

클로드 코드는 대화를 시작할 때 현재 브랜치, 메인 브랜치, git status, 최근 커밋을 한 번 읽어 둡니다. 또 커밋과 PR을 어떻게 쓸지에 관한 내장 지침을 갖고 있어서, "커밋해 줘"라고만 해도 바뀐 내용을 보고 메시지를 씁니다. 팀에 따로 정한 커밋 규칙이 있어 이 내장 지침과 부딪힌다면 includeGitInstructions를 false로 두면 내장 지침과 git 상태 스냅숏이 함께 빠집니다.

🧭 커밋과 PR을 맡기는 순서

1. 브랜치를 먼저 만듭니다: "로그인 개선 작업용 브랜치를 만들고 시작해 줘"처럼 요청합니다. 메인 브랜치에서 바로 작업하지 않습니다
2. 작업을 맡깁니다: 한 브랜치에는 한 가지 목적의 변경만 둡니다
3. 바뀐 내용을 확인합니다: git diff를 직접 보거나 /review(/code-review의 별칭)로 검토를 맡깁니다
4. 커밋을 요청합니다: 잘 된 시점마다 "지금까지 한 거 커밋해 줘"라고 하면 설명을 붙여 커밋합니다
5. PR을 요청합니다: "변경 내용 요약해 줘", "PR 만들어 줘" 순서로 나눠 요청하면 설명을 다듬기 쉽습니다. 공식 문서는 제출 전에 생성된 PR을 검토하라고 권합니다

PR과 이슈 작업은 깃허브 CLI(gh)가 있을 때 가장 매끄럽습니다. 공식 모범 사례 문서는 gh를 설치해 두면 클로드가 이슈 생성, PR 열기, 댓글 읽기를 처리한다고 적고, gh가 없으면 인증 없는 요청이 사용량 제한에 자주 걸린다고 경고합니다. 설치 뒤 gh auth login으로 한 번 로그인합니다. 클로드가 만든 PR은 세션과 연결되어, 나중에 claude --from-pr 1234로 그 PR 작업을 하던 세션을 다시 찾을 수 있습니다.

🏷️ 공동 작성자 표기 설정

클로드 코드가 만든 커밋과 PR에는 기본으로 표기가 붙습니다. 이 표기는 설정 파일의 attribution으로 정합니다.

예전에 쓰던 includeCoAuthoredBy는 v2.0.62부터 사용 중단 예정으로 표시되어 있고, attribution 값을 설정하면 무시됩니다. "attribution": false로 한 번에 끄는 방법은 v2.1.281 이상에서만 받으므로, 이전 버전도 읽는 설정 파일이라면 각 값을 빈 문자열과 false로 적는 편이 안전합니다.

🌳 워크트리로 여러 세션 나누기

같은 폴더에서 클로드 코드 세션 두 개를 동시에 돌리면 같은 파일을 서로 덮어쓸 수 있습니다. 워크트리(worktree)는 한 저장소를 폴더 여러 개에 따로 꺼내 쓰는 git 기능이고, 클로드 코드는 이를 시작 옵션 하나로 만들어 줍니다.

이렇게 시작하면 .claude/worktrees/feature-auth/에 폴더가 생기고 worktree-feature-auth 브랜치에서 세션이 열립니다. 짧게 -w로 써도 되고, 이름을 빼면 임의의 이름을 붙여 줍니다. 알아 둘 동작은 다음과 같습니다.

• .gitignore에 추가: 공식 문서는 .claude/worktrees/를 .gitignore에 넣으라고 권합니다
• .env는 따라오지 않음: git이 관리하지 않는 파일은 복사되지 않습니다. 저장소 루트의 .worktreeinclude에 .gitignore와 같은 문법으로 적은 파일만 복사됩니다
• 끝낼 때: 변경이 없으면 워크트리와 브랜치를 자동으로 지우고, 변경이 있으면 남길지 묻습니다. 남긴 워크트리는 claude --worktree 이름 --resume으로 돌아옵니다
• 기준 브랜치: 기본은 원격의 기본 브랜치에서 새로 시작하고, worktree.baseRef를 "head"로 두면 지금 로컬 HEAD에서 시작합니다
• PR에서 시작: claude --worktree "#1234"로 PR 번호의 코드를 바로 꺼냅니다
• 커밋이 없는 저장소: 첫 커밋이 하나도 없으면 기준 브랜치를 찾지 못해 실패합니다

워크트리 안에서 세션이 원래 폴더의 파일을 고치거나 git -C로 우회하는 것은 막힙니다. 여러 에이전트를 워크트리마다 나눠 한 화면에서 관리하는 방식은 오르카 이해하기에도 정리했습니다. 서브에이전트에 isolation: worktree를 두면 서브에이전트도 임시 워크트리에서 일합니다.

⏪ 체크포인트와 Git은 되돌리는 범위가 다릅니다

클로드 코드는 프롬프트마다 체크포인트를 만들어 세션당 최근 100개의 파일 상태를 보관합니다. /rewind나 입력창이 비었을 때 Esc 두 번으로 메뉴를 열면 코드와 대화를 함께 되돌리거나, 코드만, 대화만 되돌릴 수 있습니다.

공식 문서는 체크포인트를 세션 안의 빠른 되돌리기로, Git을 영구 기록과 협업 도구로 나누고, 체크포인트가 버전 관리를 대신하지 않는다고 적습니다. 그래서 결과가 괜찮은 시점마다 커밋해 두는 습관이 여전히 필요합니다. 커밋 직전에 검사를 자동으로 돌리고 싶다면 훅 실전의 커밋 전 검사 예시를 씁니다.

⚠️ 자주 하는 실수

• 메인 브랜치에서 바로 작업을 맡깁니다: 결과를 버리기 어렵습니다. 작업마다 브랜치를 만듭니다
• 체크포인트만 믿고 커밋하지 않습니다: 셸 명령으로 바뀐 파일은 체크포인트로 되돌릴 수 없습니다
• CLAUDE.md에 커밋 규칙을 적고 표기 설정은 그대로 둡니다: 공식 문서는 CLAUDE.md의 표기 지시가 설정보다 우선한다고 클로드에게 알린다고 적습니다. 두 곳이 어긋나지 않게 맞춥니다
• 두 세션을 같은 폴더에서 돌립니다: 워크트리로 나눕니다

❓ 자주 묻는 질문

클로드가 쓴 커밋 메시지 형식을 바꿀 수 있나요?

바꿀 수 있습니다. CLAUDE.md에 "커밋 메시지는 한국어로, 첫 줄에 변경 종류를 적는다"처럼 규칙을 적으면 됩니다. 내장 지침과 부딪히면 includeGitInstructions를 false로 둡니다. 공식 문서에 커밋 메시지의 구체적 형식 규격은 따로 적혀 있지 않습니다.

대화를 둘로 나눠 다른 방법을 시험해 볼 수 있나요?

/branch나 claude --continue --fork-session으로 대화를 나눕니다. 파일까지 따로 두고 시험하려면 워크트리를 함께 씁니다.

워크트리를 다 쓴 뒤 정리는 어떻게 하나요?

대화형 세션은 끝낼 때 변경이 없으면 자동으로 지웁니다. claude -p로 만든 워크트리는 자동으로 정리하지 않으므로 git worktree remove로 직접 정리합니다.

📋 3줄 요약

1. 클로드 코드는 대화를 시작할 때 현재 브랜치와 git status, 최근 커밋을 읽고 내장된 커밋과 PR 지침에 따라 커밋 메시지와 PR을 작성합니다.

2. claude --worktree 이름으로 시작하면 .claude/worktrees/ 아래에 별도 폴더와 worktree-이름 브랜치가 생겨 여러 세션이 같은 파일을 덮어쓰지 않습니다.

3. /rewind 체크포인트는 세션 안에서 클로드가 고친 파일만 되돌리고 셸 명령으로 바뀐 파일이나 원격 작업은 되돌리지 못해서 영구 기록은 Git 커밋으로 남깁니다.

📚 참고 자료

• 자주 쓰는 작업 흐름 문서: https://code.claude.com/docs/en/common-workflows
• 워크트리 문서: https://code.claude.com/docs/en/worktrees
• 체크포인트 문서: https://code.claude.com/docs/en/checkpointing
• 설정 참고 문서(attribution): https://code.claude.com/docs/en/settings-reference
• 모범 사례 문서(gh CLI): https://code.claude.com/docs/en/best-practices