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

이 글은 2026년 10월 25일 기준 Claude Code 공식 문서(Checkpointing, Worktrees, Settings reference, Common workflows)와 git 공식 문서, 같은 날 macOS 터미널에서 Claude Code v2.1.310과 git 2.47.0으로 연습 저장소 보고서-연습을 다뤄 본 화면을 근거로 씁니다.

연습 저장소에는 주간보고.txt(세 줄)와 회의록.txt(두 줄) 두 파일만 두었습니다. Git의 기본 개념이 처음이라면 Git 이해하기에서 저장소와 커밋을 먼저 익히면 이 글의 화면을 따라가기 쉽습니다.

Git 작업 흐름에 나오는 용어: 저장소, 커밋, 브랜치

Claude Code에게 Git 작업을 맡기려면 아래 다섯 낱말을 구분하면 충분합니다. 이 글의 예는 모두 연습 저장소 보고서-연습의 두 파일입니다.

Claude Code는 대화를 시작할 때 현재 브랜치, 메인 브랜치, git status 결과, 최근 커밋을 한 번 읽어 두고, 커밋과 PR을 쓰는 방법에 관한 내장 지침도 갖고 있습니다. 그래서 "커밋해 줘"라고만 요청해도 Claude가 바뀐 내용을 보고 커밋 메시지를 씁니다. 대화 중에 바뀐 상태는 Claude가 git status나 git diff를 다시 실행해 확인합니다.

Claude Code에게 커밋을 맡기는 순서

실행해 본 순서는 다음과 같습니다. 각 단계는 Claude Code 입력창에 그대로 보낼 수 있는 요청입니다.

1. 작업 전 상태 확인: "지금 커밋하지 않은 변경이 있는지 알려 줘"라고 요청합니다. 다른 사람이나 다른 세션이 고친 변경이 섞여 있으면 그 변경을 먼저 커밋하거나 되돌립니다.
2. 수정 맡기기: "주간보고.txt의 매출을 135만 원으로 바꿔 줘"처럼 고칠 파일과 내용을 정합니다. 한 번에 한 가지 목적의 수정만 맡기면 커밋 설명도 한 줄로 끝납니다.
3. 바뀐 줄 확인: "무엇이 바뀌었는지 보여 줘"라고 요청하면 Claude가 git diff로 마지막 커밋과 지금 파일을 비교해 보여 줍니다.
4. 커밋할 파일 정하기: "주간보고.txt만 커밋해 줘. 회의록.txt는 빼 줘"처럼 파일 이름을 적습니다. Claude가 git add로 그 파일을 고르고 git commit으로 기록합니다.
5. 기록 확인: Claude Code를 나와 터미널에서 git log -1을 입력하면 방금 만든 커밋의 메시지를 볼 수 있습니다.

Manual 모드(파일 편집과 파일을 바꾸는 명령 전에 허락을 묻는 권한 모드)에서는 git add와 git commit을 실행하기 전에 승인 창이 뜹니다. 승인 창의 명령 줄에서 Claude가 고른 파일 이름과 커밋 메시지를 읽고 허락합니다. 2번 "Yes, and don't ask again for git add and git commit commands"를 고르면 그 폴더에서 같은 명령을 다시 묻지 않습니다. 권한 규칙이 저장되는 위치는 클로드 코드 권한 모드와 권한 규칙에 있습니다.

팀에서 정한 커밋 규칙이 있다면 CLAUDE.md에 "커밋 메시지 첫 줄은 한국어로, 바뀐 파일 이름을 넣는다"처럼 적어 둡니다. Claude Code의 내장 커밋 지침과 부딪혀 직접 만든 지침만 쓰고 싶다면 설정 파일에 "includeGitInstructions": false를 넣습니다. 이 값을 끄면 내장 커밋과 PR 지침, 대화 시작 때 읽는 git 상태가 함께 빠집니다. CLAUDE.md 쓰는 법은 CLAUDE.md 작성법에 있습니다.

깃허브에 PR을 만들 때

PR(pull request)은 원격 저장소에서 다른 사람에게 내 브랜치의 변경을 검토하고 합쳐 달라고 요청하는 절차입니다. 공식 문서는 "create a pr for my changes"처럼 요청하면 Claude가 PR을 만든다고 안내하고, 깃허브를 쓴다면 깃허브 명령줄 도구 gh를 설치하라고 권합니다. gh가 없으면 Claude가 깃허브 API를 직접 부르는데, 로그인하지 않은 요청은 사용 제한에 자주 걸립니다. Claude가 gh pr create로 만든 PR은 세션과 연결되어, 나중에 claude --from-pr 1234(1234는 PR 번호)로 그 PR을 만든 세션을 다시 찾을 수 있습니다.

push(원격 저장소로 올리기)와 PR 만들기는 다른 사람이 보는 저장소에 기록을 남기는 단계입니다. 올릴 저장소와 대상 브랜치를 정하고, PR 제목과 설명 초안을 먼저 받아 읽은 뒤 요청합니다.

클로드 커밋의 Co-Authored-By 표기 바꾸기와 끄기

Claude Code가 만든 커밋 메시지 끝에는 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> 같은 줄이 붙습니다. Co-Authored-By는 커밋 메시지 끝에 공동 작성자를 적는 줄이고, 깃허브는 이 줄을 읽어 그 커밋을 공동 작성자의 커밋으로도 표시합니다. Claude Code가 붙이는 줄에는 커밋할 때 쓴 모델 이름이 들어갑니다. 연습 저장소에서 git log -1로 연 실제 커밋에도 이 줄이 있었습니다. 이 표기는 설정 파일(.claude/settings.json이나 ~/.claude/settings.json)의 attribution으로 정합니다.

세 가지를 한 번에 끄려면 "attribution": false를 씁니다. 이 값은 Claude Code v2.1.281 이상에서만 받고, 그보다 이전 버전은 이 값이 든 설정 파일 전체를 건너뜁니다. 여러 버전이 같은 설정 파일을 읽는다면 아래처럼 하나씩 적습니다.

예전에 쓰던 includeCoAuthoredBy는 v2.0.62부터 사용 중단 예정이고, attribution.commit이나 attribution.pr을 설정하면 무시됩니다. CLAUDE.md나 메모리에 표기에 관한 지시를 적었다면 Claude Code는 그 지시가 이 설정보다 우선한다고 Claude에게 알립니다. 조직의 관리 설정(관리자가 배포한 설정)에 정한 표기는 예외입니다.

체크포인트(/rewind)와 Git은 되돌리는 범위가 다릅니다

체크포인트는 Claude Code가 요청마다 자동으로 남기는 파일 상태이고, 같은 세션 안에서 빠르게 되돌릴 때 씁니다. 공식 문서는 체크포인트가 버전 관리를 대신하지 않는다고 적습니다. 연습 저장소에서 실행해 본 결과와 공식 문서를 함께 정리하면 다음과 같습니다.

/rewind 화면을 여는 방법은 두 가지입니다. 입력창에 /rewind를 입력하거나, 입력창이 비었을 때 Esc를 두 번 누릅니다. 목록에서 요청을 고르면 Restore code and conversation(파일과 대화 모두), Restore conversation(대화만), Restore code(파일만), Summarize from here, Summarize up to here(대화 요약) 가운데 하나를 고릅니다. 고른 요청 뒤에 추적한 파일 변경이 없으면 파일을 되돌리는 두 선택지는 나오지 않습니다. 이미 Claude가 편집 도구로 고친 파일이라면 그 뒤 셸 명령이 바꾼 내용도 체크포인트가 되돌립니다.

심볼릭 링크와 하드 링크 파일은 체크포인트 복원에서 건너뛰고 Restored the code, but skipped N files 경고를 띄웁니다. 결과가 괜찮은 시점마다 커밋해 두면 이런 예외와 30일 보관 기간에 상관없이 그 시점으로 돌아갈 수 있습니다. 커밋 직전에 검사를 자동으로 돌리고 싶다면 클로드 코드 훅의 커밋 전 검사 설정을 씁니다.

대화만 둘로 나눠 다른 방법을 시험하려면 체크포인트 대신 /branch나 claude --continue --fork-session을 씁니다. 이 두 명령은 대화 기록을 나누는 기능이고 Git 브랜치를 만들지 않습니다.

깃 워크트리 뜻과 기본 명령

깃 워크트리(git worktree)는 한 저장소의 커밋 기록을 함께 쓰면서 작업 폴더를 여러 개 두는 Git 기능입니다. 한 폴더에서는 한 번에 브랜치 하나만 꺼낼 수 있어서, 같은 폴더에서 일하던 두 에이전트 가운데 하나가 브랜치를 바꾸면 다른 에이전트가 보던 파일도 함께 바뀝니다. 워크트리를 쓰면 브랜치마다 폴더를 따로 두고 여러 작업을 동시에 진행할 수 있습니다. git 공식 문서는 원래 작업 폴더를 메인 워크트리, 새로 만든 폴더를 연결된 워크트리라고 부릅니다.

한 워크트리에서 만든 커밋은 다른 워크트리에서도 바로 조회할 수 있지만, 다른 폴더의 파일이 자동으로 같은 내용으로 바뀌지는 않습니다. 저장소를 여러 번 복제하는 방법과 달리 기록을 폴더마다 따로 내려받지 않고, 브랜치를 합치는 일도 한 저장소 안에서 끝납니다.

Claude Code 없이 git 명령으로 워크트리를 다룰 때는 다음 세 명령을 씁니다.

브랜치 하나는 한 번에 한 워크트리에서만 꺼낼 수 있습니다. 연습 저장소의 원래 폴더에서 워크트리가 쓰는 브랜치로 바꾸려 하자 fatal: 'worktree-table' is already used by worktree at ...이 나왔습니다. git worktree remove는 수정한 파일이나 새 파일이 남은 워크트리를 지우지 않고 거부하며, 폴더를 지워도 브랜치는 남습니다. 폴더를 Finder나 파일 탐색기에서 직접 지웠다면 git에 등록 정보가 남으므로 git worktree prune으로 정리합니다.

코덱스 워크트리 사용법

오픈AI의 코딩 에이전트인 코덱스(Codex)도 같은 git 워크트리를 씁니다. 챗GPT 데스크톱 앱에서 코덱스 새 대화를 열고 입력창 아래의 Worktree를 고른 뒤, 워크트리를 만들 기준 브랜치를 고르고 요청을 보내면 코덱스가 그 브랜치에서 워크트리를 만들어 작업합니다. 기본으로는 브랜치 이름 없이 커밋을 꺼낸 상태(detached HEAD)에서 시작합니다. 저장소와 워크트리, 명령 실행은 모두 내 컴퓨터(또는 그 컴퓨터가 쓰는 원격 개발 환경)에 있습니다.

작업을 마친 뒤 워크트리에서 계속하려면 대화 화면 제목 줄의 Create branch here 버튼으로 브랜치를 만들고 커밋과 푸시를 진행합니다. 평소 쓰는 편집기에서 확인하려면 제목 줄의 Hand off 버튼으로 대화와 변경을 원래 작업 폴더(Local)로 옮깁니다. 코덱스 문서도 브랜치 하나는 한 곳에서만 꺼낼 수 있다고 적으므로, 워크트리에서 만든 브랜치는 원래 폴더에서 동시에 꺼낼 수 없습니다.

claude --worktree로 병렬 세션 나누기

claude --worktree 이름(짧게 -w 이름)으로 시작하면 Claude Code가 저장소 맨 위 폴더의 .claude/worktrees/이름/에 워크트리를 만들고, worktree-이름 브랜치에서 세션을 엽니다. 다른 터미널에서 다른 이름으로 같은 명령을 실행하면 두 번째 세션이 따로 열립니다. 이름을 빼면 bright-running-fox 같은 이름을 Claude Code가 붙입니다.

• 이름 규칙: 실행해 보니 claude --worktree 표정리처럼 한글 이름은 Invalid worktree name 오류가 나고, 영문, 숫자, 점, 밑줄(_), 하이픈(-)만 받았습니다.
• 폴더 신뢰: 그 폴더에서 Claude Code를 처음 연다면 --worktree 없이 claude를 한 번 실행해 폴더 신뢰 창에서 신뢰를 고릅니다.
• .gitignore: 원래 폴더의 git status에 ?? .claude/가 나옵니다. 공식 문서는 .claude/worktrees/를 .gitignore에 넣으라고 권합니다.
• 시작 커밋: 기본값은 원격 저장소의 기본 브랜치(보통 main)에서 시작하고, 원격 저장소가 없으면 지금 꺼낸 커밋에서 시작합니다. 설정 worktree.baseRef를 "head"로 두면 원격 저장소가 있어도 지금 꺼낸 커밋에서 시작합니다. 어느 쪽이든 원래 폴더의 커밋하지 않은 변경은 따라오지 않습니다.
• .env 같은 제외 파일: 새 워크트리에는 Git이 추적하는 파일만 있습니다. .gitignore로 뺀 .env 같은 파일이 필요하면 저장소 맨 위에 .worktreeinclude를 두고 .gitignore 문법으로 경로를 적습니다. 패턴에 맞고 Git에서 제외된 파일만 복사되므로, 복사해도 되는 개발용 값인지 먼저 정합니다.
• 끝낼 때: 변경이 없으면 세션 이름을 붙이지 않은 세션의 워크트리는 자동으로 지워지고, 세션 이름을 붙인 세션은 먼저 묻습니다(claude -n 이름이나 /rename 이름으로 붙인 세션 이름이며, 워크트리 이름과 다릅니다). 변경이 남아 있으면 Keep worktree와 Remove worktree 가운데 고르게 하고, Keep을 고르면 claude --worktree "이름" --resume <세션 ID> 명령이 나옵니다. claude -p로 실행한 워크트리는 묻지 않으므로 정리되지 않고 남습니다.
• PR에서 시작: claude --worktree "#1234"는 PR 번호 1234의 코드를 .claude/worktrees/pr-1234에 꺼내 세션을 엽니다.

Claude Code는 워크트리 세션에서 원래 폴더를 향한 파일 편집, 원래 폴더에서 실행하는 명령, 원래 폴더로 향하는 git 명령을 막습니다. 다만 cp나 셸 리디렉션처럼 git 없이 원래 폴더에 쓰는 명령은 이 검사로 막지 않으므로, 워크트리를 운영체제 수준의 완전한 격리로 보지 않습니다. 커밋 기록과 원격 저장소는 모든 워크트리가 함께 씁니다.

서브에이전트 설정에 isolation: worktree를 넣으면 서브에이전트도 임시 워크트리에서 일합니다. 여러 에이전트의 워크트리를 한 화면에서 관리하는 방법은 오르카 이해하기에 있습니다.

병렬 세션의 결과를 합치는 순서

워크트리는 파일을 고치는 폴더만 나눕니다. 어떤 결과를 합칠지 정하고 합친 뒤 전체가 맞는지 확인하는 일은 따로 남습니다.

1. 워크트리마다 바뀐 줄 보기: 그 세션에 맡긴 파일 밖이 바뀌지 않았는지부터 봅니다.
2. 워크트리마다 커밋하기: 합칠 결과를 그 워크트리의 브랜치에 커밋합니다. Remove worktree를 고르면 커밋하지 않은 변경뿐 아니라 그 워크트리 브랜치와 커밋도 지워지므로, 합치기 전에 세션을 끝낼 때는 Keep worktree를 고릅니다.
3. 한 번에 하나씩 합치기: 원래 폴더에서 main을 꺼내고 git merge worktree-이름으로 한 브랜치씩 합칩니다. 두 브랜치를 한꺼번에 합치면 충돌이 났을 때 어느 작업 때문인지 찾기 어렵습니다.
4. 합칠 때마다 다시 확인하기: 워크트리마다 맞았던 결과도 합친 뒤에는 서로 어긋날 수 있습니다.
5. 정리하기: 세션과, 그 워크트리 폴더에서 실행해 둔 미리보기 서버 같은 프로그램을 끄고, 합친 커밋을 확인한 뒤 워크트리를 지웁니다.

충돌을 줄이는 방법은 합치는 단계보다 나누는 단계에 있습니다. 클로드 코드의 에이전트 팀(여러 Claude Code 세션이 팀원처럼 일을 나눠 맡는 기능) 문서도 두 팀원이 같은 파일을 고치면 덮어쓰기가 생긴다며, 팀원마다 다른 파일 묶음을 맡기라고 권합니다.

직접 해 보기: 보고서-연습 저장소

Git과 Claude Code가 설치된 macOS 터미널 또는 Windows PowerShell에서 진행합니다. 기존 업무 폴더 대신 새 빈 폴더를 씁니다. 터미널을 여는 법은 터미널과 CLI에 있습니다. 요청을 보내면 계정의 사용량이 듭니다.

1. 빈 폴더 보고서-연습을 만들고 터미널에서 그 폴더로 이동한 뒤, 아래 명령을 한 줄씩 실행합니다. 둘째와 셋째 줄은 이 연습 저장소에서만 쓸 가상 작성자 이름과 주소이고, 넷째 줄은 한글 파일 이름을 그대로 보이게 하는 설정입니다.

1. 메모장이나 텍스트 편집기로 주간보고.txt에 주간보고, 날짜: 10월 20일, 매출: 120만 원 세 줄을, 회의록.txt에 회의록, 장소: 2번 회의실 두 줄을 저장합니다.
2. git add 주간보고.txt 회의록.txt와 git commit -m "첫 기록"을 차례로 실행합니다. [main (root-commit) ...] 첫 기록 줄이 나오면 첫 커밋이 만들어진 것입니다.
3. claude --permission-mode default로 Claude Code를 시작하고(default는 Manual 모드입니다), 폴더 신뢰 창에서 Yes, I trust this folder를 고릅니다.
4. "주간보고.txt의 날짜를 10월 27일로 바꿔 줘"를 보내고 편집 승인 창에서 1번 Yes를 고릅니다. 이어서 "지금 상태를 커밋해 줘"를 보내고, 승인 창의 명령 줄에 git add 주간보고.txt가 있는지 읽은 뒤 허락합니다.
5. "주간보고.txt를 표 형식으로 바꿔 줘"를 보낸 뒤 "마지막 커밋 상태로 되돌려 줘"를 보냅니다. 주간보고.txt를 열어 날짜가 10월 27일인 세 줄로 돌아왔는지 봅니다.
6. /exit로 나와 터미널에서 git log --oneline을 입력합니다. 첫 기록과 Claude가 쓴 날짜 수정 커밋 두 줄이 나오면 끝입니다.

/exit로 나와 새 세션에서 회의록.txt로 /rewind를 시험해 봅니다. 장소를 3번 회의실로 바꿔 달라고 한 뒤 /rewind에서 그 요청을 골라 Restore code로 되돌리고, 이번에는 파일 이름을 바꿔 달라고 한 뒤 같은 화면에 Restore code가 나오지 않는 것을 봅니다. 워크트리를 연습하려면 같은 폴더에서 claude --worktree table을 실행합니다.

막혔을 때

자주 묻는 질문

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

바꿀 수 있습니다. CLAUDE.md에 "커밋 메시지 첫 줄은 한국어로, 바뀐 파일 이름을 넣는다"처럼 규칙을 적으면 Claude가 그 규칙으로 메시지를 씁니다. 내장 커밋 지침을 빼고 직접 만든 지침만 쓰려면 설정 파일에 "includeGitInstructions": false를 넣습니다.

Co-Authored-By: Claude 줄은 무엇이고 어떻게 빼나요?

Claude Code가 만든 커밋이라는 표시로, 커밋할 때 쓴 모델 이름이 공동 작성자로 들어간 줄입니다. 설정 파일에 "attribution": {"commit": ""}을 넣으면 커밋에서 빠지고, PR 설명의 표기는 "pr": ""로 뺍니다. v2.1.281 이상만 쓴다면 "attribution": false로 한 번에 끕니다.

브랜치를 바꿔 가며 쓰는 것과 워크트리는 무엇이 다른가요?

브랜치를 바꾸면 커밋해 둔 파일은 그 브랜치의 마지막 커밋 내용으로 바뀌고, 커밋하지 않은 변경은 그대로 따라옵니다. 연습 저장소에서도 커밋하지 않은 회의록.txt 변경이 브랜치를 바꾼 뒤 그대로 남아 있었습니다. 워크트리는 브랜치마다 폴더를 따로 두므로 두 브랜치의 파일을 동시에 열어 두고 각자 고칠 수 있습니다.

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

claude --worktree로 연 세션은 /exit로 끝낼 때 나오는 질문에서 Keep worktree나 Remove worktree를 고릅니다. 직접 정리할 때는 원래 폴더에서 git worktree list로 워크트리 폴더를 찾고, 그 폴더에서 git status로 남은 변경을 본 뒤 남길 것은 커밋하고 합칩니다. 그다음 git worktree remove 폴더로 지우고, 필요 없는 브랜치는 git branch -d 브랜치로 지웁니다.

참고 자료

• Claude Code 공식 문서: Checkpointing(/rewind 선택지, 추적 범위, 보관 기간)
• Claude Code 공식 문서: Run parallel sessions with worktrees(--worktree, .worktreeinclude, 정리)
• Claude Code 공식 문서: Settings reference(attribution, includeGitInstructions, worktree.baseRef)
• Claude Code 공식 문서: Common workflows(PR 만들기, 병렬 세션)
• Claude Code 공식 문서: Best practices(gh 명령줄 도구)
• Claude Code 공식 문서: Agent teams(팀원마다 파일 나누기)
• git 공식 문서: git worktree
• git 공식 문서: git config(core.quotePath)
• 깃허브 공식 문서: 여러 작성자의 커밋 만들기(Co-authored-by)
• 코덱스 공식 문서: Worktrees