Claude Code로 만드는 Git 워크플로: 커밋과 PR 자동화 (2026)

Claude Code가 스스로 커밋과 PR을 만들 수 있나요?

네 — 그리고 이건 기본 내장 기능이라 따로 설치할 게 없어요. Claude Code는 Bash 도구를 통해 git과 gh를 호출해요. 그래서 "변경을 커밋해줘"라고만 말하면 git status와 git diff를 실행하고, 맥락을 읽은 뒤 커밋 메시지를 작성해요. "pr 만들어줘"라고 하면 gh pr create를 실행해 여러분의 커밋들로부터 제목과 본문을 생성해요.

최소 요건은 이래요. 저장소가 git init으로 초기화되어 있고, 여러분이 그 안에 있어야 해요. PR을 열려면 로그인된 gh CLI(GitHub CLI)도 필요해요. 없어도 Claude Code는 문제없이 커밋해요 — 다만 PR을 대신 열어주지 못할 뿐이에요. Anthropic의 공통 워크플로 문서(2026/08/09 확인)에 따르면, 이것들은 서드파티 해킹이 아니라 공식적으로 지원되는 흐름이에요.

먼저 신뢰에 대해 한마디. Claude Code는 Bash 도구의 권한 계층을 통해 git을 다루기 때문에, 모든 쓰기 명령(commit, push)은 미리 허용해 두지 않는 한 여러분의 승인을 요청해요. 여러분이 요청하지 않으면 원격으로 push하지 않아요. 하지만 이 글 마지막에서 다루듯, 확실히 하려면 CLAUDE.md에도 그 점을 명시해 두는 게 좋아요.

1단계 - 설정: git, gh CLI, 인증

git을 에이전트에게 맡기기 전에 세 가지를 확인해요. 터미널을 열고(또는 Claude Code에게 실행하게 하고) 다음을 확인하세요.

git --version
gh --version
gh auth status

gh가 설치되어 있지 않다고 나오면, GitHub CLI를 설치하고 한 번만 로그인하세요.

# macOS
brew install gh
# Windows
winget install --id GitHub.cli
# After installing, log in (opens a browser to authenticate)
gh auth login

GitHub.com을 고르고, 다음으로 HTTPS를 고른 뒤 브라우저에서 인증하세요. 이게 끝나면 gh가 토큰을 보관해 여러분을 대신해 PR을 열 수 있어요. 마지막으로, 올바른 저장소의 작업 브랜치에 있는지 확인하세요.

git rev-parse --is-inside-work-tree # true if this really is a git repo
git branch --show-current

팁: main에서 직접 작업하지 마세요. 먼저 브랜치를 만드세요 — Claude Code에게 시켜도 돼요: "feat/checkout 브랜치를 만들고 거기로 전환해줘". 깨끗한 브랜치는 마지막 PR 단계를 훨씬 깔끔하게 만들어줘요.

2단계 - 제대로 된 Conventional Commits 자동 작성

바로 여기서 Claude Code가 진가를 발휘해요. 코딩을 마친 뒤, 메시지를 직접 타이핑하는 대신 이렇게 지시하세요.

commit the current changes using conventional commits

Claude Code는 git status와 git diff --staged(그리고 스테이지되지 않은 diff)를 실행해, 여러분이 실제로 무엇을 바꿨는지 분석한 뒤 올바른 형식으로 메시지를 작성해요.

type(scope): short description in the present tense

- bullet detail if needed
- the reason for the change, not just a file list

자주 쓰는 Conventional Commits type 값은 다음과 같아요.

더 좋은 메시지를 위한 팁: 커밋하려는 부분을 정확히 스테이지해 뒀다면(의도적인 git add), Claude Code는 스테이지된 diff에 충실해지고 추측을 덜 해요. 구체적으로 지정할 수도 있어요: "커밋해줘, scope는 'checkout', 파일 나열 말고 왜 바뀌었는지에 초점을 맞춰줘". 변경이 일어난 이유에 대한 맥락을 많이 줄수록, 나중에 히스토리를 읽는 사람에게 메시지가 더 유용하게 남아요.

"Co-Authored-By" 줄에 대하여: 기본적으로 Claude Code는 커밋 끝에 Co-Authored-By: Claude <...> 같은 기여 표시를 붙이곤 해요. 개인 저장소나 사이드 프로젝트라면 남겨 둬도 무해하고 투명해요. 하지만 커밋 규약이 엄격한 회사 저장소(또는 commitlint로 메시지 형식을 검사하는 CI)에서는 끄고 싶을 수 있어요. 가장 간단한 방법은 CLAUDE.md에 규칙 하나를 두는 거예요: "커밋 메시지에 Co-Authored-By 줄이나 어떤 AI 서명도 넣지 마" — Claude Code는 따라요. 이건 저장소 정책 결정이니, 전체에 일괄 적용하기 전에 팀과 합의하세요. Claude Code로 자주 쓰는 git 명령을 빠르게 참고하고 싶다면, Claude Code 치트 시트에 편리한 조회 표가 있어요.

3단계 - type/scope별로 커밋 나누기(자동 분할)

실제로는 딱 한 가지만 바꾸는 경우가 드물어요. 한 번의 코딩 세션에서 기능 추가, 버그 수정, 문서 업데이트를 한꺼번에 할 수도 있어요. 그걸 전부 하나의 거대한 커밋에 욱여넣으면 리뷰어가 괴롭고, revert할 때 무관한 변경까지 끌려와요. Claude Code가 대신 나눠줄 수 있어요.

these changes span several types. Split them into separate atomic
commits by type/scope, one type of change per commit

diff를 주제별로 묶고, 각 그룹을 스테이지한 뒤(git add -p 또는 파일 단위), 하나씩 커밋을 만들어요. 뒤섞인 diff는 이렇게 될 수 있어요.

feat(payment): add VietQR payment flow
fix(payment): correct amount rounding
docs(payment): note the SEPAY_KEY environment variable

이게 가치 있는 이유: 각 atomic 커밋은 독립적인 리뷰 단위가 되고, 히스토리가 명확하게 읽히며, git revert가 필요할 때 나머지는 건드리지 않고 망가진 것만 제거할 수 있어요. 이건 거의 어떤 가이드도 언급하지 않는 기법이지만, "AI에게 아무렇게나 커밋하게 두는 것"과 "AI에게 꼼꼼한 개발자처럼 커밋하게 하는 것"의 큰 차이예요. 한 가지 주의: 승인하기 전에 제안된 커밋들을 훑어보세요 — 가끔 그어놓은 scope 경계가 여러분의 모듈 구조와 맞지 않을 때가 있는데, 그럴 땐 "앞의 두 커밋을 합쳐줘"라고 말하면 돼요.

4단계 - 커밋 전에 시크릿 검사하기

에이전트에게 커밋을 맡길 때의, 거의 어떤 가이드도 언급하지 않는 실제 위험이 여기 있어요. 에이전트는 실수로 .env, API 키, 토큰, 데이터베이스 연결 문자열을 커밋에 흘려 넣을 수 있고 — 일단 히스토리에 들어가면 깔끔하게 지우기가 성가셔요. 커밋하기 전에 검사를 요청하세요.

before committing, scan the staged files for any secrets:
API keys, tokens, passwords, connection strings, or a stray .env file

적용할 만한 안전 체크리스트:

• .env, *.pem, *.key를 차단하는 .gitignore를 저장소 초기부터 두세요.
• Claude Code에게 스테이지된 diff를 검사시키세요 — 매 커밋 전에 키나 토큰 같은 문자열이 없는지요.
• pre-commit 훅을 설치하세요 — git 계층에서 차단해서(예: gitleaks나 git-secrets) 에이전트에만 전적으로 의존하지 않도록요.
• 이미 시크릿을 커밋했다면: 그 토큰은 유출된 것으로 간주하고 — 지금 바로 교체하세요 — 파일만 지우고 그 위에 커밋하지 마세요.

이 부분을 완전히 자동화하려면 검사를 커밋 전에 실행되는 훅으로 옮기면 돼요 — 자동 검사를 연결하는 방법은 Claude Code의 훅 사용법을 참고하세요. 황금률: git 계층에 차단 층을 두지 않은 채, 히스토리에 대한 쓰기 권한을 에이전트에게 완전히 맡기지 마세요.

5단계 - gh로 풀 리퀘스트 자동으로 열기

커밋이 깔끔해지면, PR을 여는 건 한 문장이에요.

create a pr

Claude Code는 (허용하면) 브랜치를 push하고, gh pr create를 실행하며, 브랜치의 커밋들로부터 제목과 본문을 작성해요 — 저장소에 PR 템플릿이 있으면 변경 요약과 체크리스트까지요. 더 구체적으로 지정할 수도 있어요: "develop 브랜치를 대상으로 PR을 열고 내가 실행한 테스트를 명시해줘".

Anthropic 문서의 깔끔한 팁 하나: gh pr create로 만든 PR은 그것을 만들어낸 Claude Code 세션에 자동으로 연결돼요. 나중에 다시 리뷰할 때, 바로 그 세션 맥락을 다음 명령으로 다시 열 수 있어요.

claude --from-pr 1234

리뷰어가 코멘트를 남겼을 때, 원래의 전체 맥락을 기억한 채로 Claude Code가 계속 작업하게 하고 싶을 때 아주 편리해요.

이 단계에서 더 깊은 GitHub 작업이 필요하다면 — 이슈 읽기, 코멘트 달기, 세션 안에서 리뷰 요청 관리 등 — gh에만 의존하지 말고 GitHub MCP를 Claude Code와 결합하세요. MCP를 쓰면 Claude Code가 CLI 명령을 실행하는 것을 넘어 GitHub의 전체 맥락을 "볼" 수 있어요.

CLAUDE.md와 /commit 슬래시 커맨드로 표준화하기

자연어 지시는 빠르지만, 매번 "conventional commits, push 하지 마, AI 서명 없이"를 반복해야 한다면 고정된 규칙으로 만드세요. 다음 블록을 저장소 루트의 CLAUDE.md 파일에 넣으세요 — Claude Code는 매 세션 이걸 읽어요.

## Git Rules
- Commit using Conventional Commits: type(scope): description (present tense).
- Types to use: feat, fix, docs, refactor, chore, test.
- Split a mixed diff into atomic commits by type/scope.
- Scan for secrets (API keys, tokens, .env) before every commit.
- Do NOT run git push on your own; push only when I explicitly ask.
- Do NOT add a Co-Authored-By line or any AI signature to commit messages.
- Scope names follow the repo's module/folder names.

이 파일을 잘 쓰는 법은 CLAUDE.md에 git 규칙 작성하기 가이드를 보세요. 다음 단계는 전체 과정을 커스텀 슬래시 커맨드로 감싸서, 팀 전원이 하나의 명령으로 똑같은 흐름을 실행하게 하는 거예요. .claude/commands/commit.md 파일을 만드세요.

---
description: Conventional commit, atomic split, secret scan
---
Review git status and git diff. Scan the staged files for secrets.
Split the changes into atomic commits by type/scope.
Commit using Conventional Commits. Do NOT push.

그때부터 팀 전원이 그냥 /commit만 입력하면 동일한 동작을 얻고, 규약을 벗어난 커밋이 사라져요. 이것이 바로 "개인의 요령"을 "팀의 표준"으로 바꾸는 방법이에요.

고급 워크플로: worktree, PR 리뷰, CI

익숙해지면, 생산성을 한 단계 더 끌어올리는 몇 가지 기법이 있어요.

병렬 worktree. 메인 작업 디렉터리를 건드리지 않고 Claude Code가 자기만의 브랜치에서 기능을 만들게 하려면 worktree를 쓰세요.

claude --worktree feature-auth

두 worktree에 걸쳐, 한 세션은 버그를 고치고 다른 세션은 기능을 만드는 식으로 서로 방해 없이 병렬로 진행할 수 있어요.

pre-commit/CI로 파이프하기. Claude Code는 -p로 비대화식으로 동작하니, 스크립트에 넣을 수 있어요. 예를 들어 최근 커밋들을 changelog나 리뷰 단계용으로 요약하려면 이렇게요.

git log --oneline -20 | claude -p "summarize these recent commits into a changelog"

스택드 PR. 큰 기능이 서로 의존하는 여러 PR로 나뉠 때(PR B가 아직 병합되지 않은 PR A 위에 쌓일 때), Claude Code에게 스택된 브랜치 체인을 만들게 하고 올바른 부모-자식 순서로 PR을 열게 할 수 있어요. 덕분에 리뷰어는 하나의 거대한 PR 대신 작은 조각들을 승인할 수 있고, 바로 이 지점에서 준비된 git 스킬이 반복 작업을 많이 덜어줘요.

병합 전에 PR 셀프 리뷰하기. 병합을 누르기 전에, Claude Code가 diff를 읽고 로직 버그, 엣지 케이스, 취약점을 찾게 하세요 — 병합 전에 Claude가 PR을 리뷰하게 하는 방법을 보세요. 저장소의 CI와 결합하면 두 겹의 검사를 얻어요: 기계는 테스트를 돌리고, AI는 변경의 의미를 읽어요. 역할은 분리해 두세요 — 에이전트는 탄탄한 1차 리뷰를 하지만, 최종 병합 결정은 특히 보안이나 데이터를 건드리는 변경에서는 여전히 사람의 눈을 거쳐야 해요.

준비된 스킬로 git 가속하기(AgentKit의 ak-git)

이 글 전체는 사실상 그걸 직접 만드는 법을 알려줘요: 프롬프트를 쓰고, CLAUDE.md 규칙을 정하고, 슬래시 커맨드를 만드는 것. 그 방식도 전혀 문제없고 무료예요. 하지만 각 조각을 손으로 조립하고 싶지 않다면, 이 글의 네 가지 — conventional commits, type/scope별 자동 분할, 시크릿 검사, 스택드 PR — 을 한 번의 호출로 해주는 ak-git이라는 준비된 git 스킬이 있어요.

혼동을 막기 위한 한 줄: ak-git은 AgentKit의 일부예요 — agentkit.best에 있는 Claude Code용 키트(ak CLI)로, OpenAI의 "AgentKit"과는 다른 거예요. 둘을 헷갈리지 마세요.

ak-git은 Engineer Kit($99, 사이트에 반복 결제 언급은 없어요)에 들어 있어요 — 그 안에 또 뭐가 있는지 알고 싶다면 결정하기 전에 Engineer Kit 리뷰를 읽어보세요. 솔직히 말하면, 이 git 워크플로를 돌리려고 뭔가를 살 필요는 없어요 — 이 글의 모든 내용은 순수한 Claude Code로 동작해요. 키트의 가치는 설정 수고를 줄이고 팀 전체에서 동작을 일관되게 유지해 준다는 데 있어요.

흔한 실수와 안전 팁

에이전트에게 git을 맡기는 건 편하지만, 익숙한 함정이 몇 가지 있어요. 잘 깨지는 지점과 대처법은 다음과 같아요.

기억해 둘 솔직한 한계: Claude Code는 여러분만큼 깊이 비즈니스 로직을 "이해"하지는 못해서, 메시지가 왜보다 무엇을 바꿨는지를 더 잘 설명할 때가 있어요. 중요한 커밋에는 "왜"를 직접 덧붙이세요. 그리고 승인 전에 항상 diff를 리뷰하세요 — 에이전트는 빠르지만, 히스토리에 대한 책임은 여전히 여러분에게 있어요.

자주 묻는 질문(FAQ)

Claude Code가 스스로 원격에 push하나요?

아니요, 요청하지 않는 한 안 해요. 모든 git 쓰기 명령은 Bash 도구의 권한 계층을 거치고, 여러분이 말하지 않으면 Claude Code는 push하지 않아요. 안전하게 하려면 CLAUDE.md에 "스스로 git push 하지 마" 규칙을 추가하세요.

gh CLI를 설치해야 하나요?

커밋에는 필요 없어요 — git만으로 충분해요. 하지만 Claude Code가 gh pr create로 직접 풀 리퀘스트를 열려면, gh를 설치하고 gh auth login으로 로그인해 둬야 해요.

커밋에 "Generated with Claude" 줄이 들어가나요? 어떻게 끄나요?

기본적으로 보통 Claude를 크레딧하는 Co-Authored-By 줄이 있어요. 끄려면 CLAUDE.md에 규칙을 추가하세요: "커밋 메시지에 Co-Authored-By 줄이나 어떤 AI 서명도 넣지 마". Claude Code가 그걸 빼요.

변경 더미를 여러 커밋으로 나누게 하려면 어떻게 하나요?

"이 변경들을 type/scope별 atomic 커밋으로 나눠줘"라고 지시하세요. Claude Code는 diff를 주제별로 묶고, 각 그룹을 스테이지한 뒤, 변경 종류마다 별도의 커밋을 만들어요.

비공개(드래프트) 풀 리퀘스트를 열 수 있나요?

네. "PR을 드래프트로 만들어줘"라고 하면 Claude Code가 gh pr create를 실행할 때 해당 플래그를 붙여요. 대상 브랜치와 리뷰어도 지정할 수 있어요.

GitLab이나 Bitbucket에서도 되나요?

conventional commits, 커밋 분할, 시크릿 검사는 어떤 git 저장소에서도 동작해요. 자동 PR 단계만 GitHub에 묶인 gh에 의존해요; GitLab/Bitbucket에서는 대응하는 CLI(예: glab)를 쓰거나 수동으로 하세요.

맺음말과 다음 단계

Claude Code를 이용한 git 워크플로는 네 단계로 요약돼요: git과 gh를 설정하고, 제대로 된 conventional commits를 쓰고, atomic 커밋으로 나눠 시크릿을 검사하고, 그런 다음 gh로 PR을 여는 것. 규칙을 CLAUDE.md와 /commit 슬래시 커맨드에 넣으면 팀 전원이 하나의 표준을 공유해요. 다음으로, 더 깊은 GitHub 작업을 위해 GitHub MCP를 연결하고, 병합 전에 Claude가 PR을 리뷰하게 하세요. 직접 만드는 부분을 건너뛰고 싶다면, AgentKit 번들 — 현재 $149(기존 $198)에 이 워크플로를 그대로 실행하는 ak-git 스킬이 들어 있어요.