Claude Code Git 워크플로 실전: 깨끗한 브랜치, 작은 커밋, CI와 팀 인수인계

Claude Code가 코드를 빠르게 작성할수록 Git 워크플로는 더 엄격해야 합니다. AI가 몇 분 만에 유용한 diff를 만들 수 있지만, 관련 없는 파일을 섞거나, 너무 큰 커밋을 만들거나, 충돌의 의도를 이해하지 못한 채 해결하거나, 로컬 검증 없이 push할 수도 있습니다.

이 글은 개인 개발과 팀 개발 모두에 쓸 수 있는 Claude Code Git 워크플로를 정리합니다. staging, commit, rebase를 초보자도 이해할 수 있게 설명하고, 그대로 복사해 쓸 수 있는 명령, CLAUDE.md 규칙, pre-commit, GitHub Actions, 충돌 처리, 안전한 rollback, daily handoff까지 다룹니다.

함께 보면 좋은 글은 Claude Code Git 충돌 해결, GitHub Actions 고급 활용, review workflow checklist입니다. 공식 문서는 Claude Code hooks, Claude Code headless mode, Git user manual, Git rebase, GitHub Actions workflow syntax, pre-commit을 참고하세요.

Git 용어를 먼저 쉽게 이해하기

working tree는 지금 파일을 수정하고 있는 작업 공간입니다. Claude Code가 파일을 바꾸는 곳도 여기입니다. staging area는 “다음 커밋에 넣을 바구니”입니다. git add는 영구 저장이 아니라 다음 commit에 포함할 변경을 고르는 작업입니다.

commit은 staging area에 들어간 변경을 하나의 기록으로 남기는 것입니다. 좋은 commit은 reviewer가 한 번에 이해할 수 있을 만큼 작습니다. rebase는 내 branch의 commit을 최신 main 위에 다시 쌓는 작업입니다. 기록은 깔끔해지지만, 이미 공유한 branch에서 무심코 쓰면 다른 사람의 기록을 꼬이게 할 수 있습니다.

Claude Code는 코드 생성만 담당하면 부족합니다. diff를 읽고, 무엇을 stage할지 제안하고, commit message를 만들고, 충돌의 양쪽 의도를 설명하고, 로컬 검증을 실행하고, handoff를 남기는 역할까지 포함해야 실무에서 안전합니다.

flowchart LR
  A["목표를 한 줄로 작성"] --> B["main 업데이트 후 branch 생성"]
  B --> C["작은 단위로 구현"]
  C --> D["diff를 읽고 staging 선택"]
  D --> E["review gate와 local CI"]
  E --> F["작은 commit"]
  F --> G["rebase 또는 PR"]
  G --> H["handoff와 rollback 기록"]

깨끗한 branch loop

Claude Code에 수정을 맡기기 전에 작업 공간을 이해 가능한 상태로 만듭니다. “깨끗하다”는 말은 변경이 0개라는 뜻만은 아닙니다. 이번 작업과 관련 없는 변경이 섞이지 않았다는 뜻입니다.

git status --short
git fetch origin
git switch main
git pull --ff-only origin main
git switch -c feature/checkout-coupon-validation
git status --short

PowerShell에서는 날짜가 들어간 branch 이름이 여러 session을 동시에 돌릴 때 유용합니다.

$topic = "checkout-coupon-validation"
$date = Get-Date -Format "yyyyMMdd"
git fetch origin
git switch main
git pull --ff-only origin main
git switch -c "feature/$date-$topic"
git status --short

첫 prompt는 구현보다 범위 지정이 먼저입니다.

Goal: add coupon expiry validation to checkout.
Scope: edit only src/checkout, src/coupons, and matching tests.
Do not stage, commit, push, or edit unrelated files.
Before editing, read package.json and existing checkout tests.
After editing, show git diff --stat and the exact test commands you ran.

ClaudeCodeLab 운영에서 Masa가 겪은 실제 문제는 문법 오류보다 설명할 수 없는 diff였습니다. 기사 하나만 고치려 했는데 상품 페이지 초안이나 로컬 보고서가 같이 섞이면, build가 통과해도 review 비용이 올라갑니다. 시작 prompt에 제외 대상을 쓰는 습관이 중요합니다.

staging과 작은 commit

git add -A는 편하지만 AI 작업에서는 너무 넓습니다. 임시 파일, 로컬 설정, 다른 작업의 반쯤 끝난 수정까지 stage할 수 있습니다.

git diff --stat
git diff
git add src/checkout/validateCoupon.ts
git add tests/checkout/validateCoupon.test.ts
git diff --staged --stat
git diff --staged

commit message는 Conventional Commits 스타일이면 나중에 history를 검색하기 쉽습니다.

git commit -m "feat(checkout): validate coupon expiry before payment"

사용자 영향이 있는 변경은 body를 남깁니다.

git commit -m "fix(content): keep Claude Code Git workflow CTA localized" -m "Updates the localized article body, internal links, and review checklist so translated pages follow the same Git workflow."

Claude Code에는 message 제안만 맡기고 commit 실행은 막을 수 있습니다.

Read only the staged diff.
Propose one Conventional Commits message.
Do not run git commit.
Mention the user impact in the body if the change affects readers or customers.

CLAUDE.md에 Git 규칙 고정하기

CLAUDE.md는 Claude Code를 위한 프로젝트 작업 규칙입니다. 사용자용 README가 아니라 AI pair programmer에게 주는 운영 지침이라고 보면 됩니다.

# Claude Code Git rules

- Start every coding task with `git status --short` and report unrelated dirty files.
- Do not run `git add -A`, `git commit`, `git push`, `git reset --hard`, or `git clean -fd` unless the user explicitly asks.
- Keep commits small: one behavior change, one test update, or one content slug at a time.
- Before proposing a commit, show `git diff --stat` and `git diff --staged --stat`.
- If a conflict appears, explain both sides before editing the conflicted file.
- Run the closest local checks before push: lint, typecheck, test, build, or article metadata checks.
- Leave a handoff note with changed files, commands run, failing checks, and rollback option.

팀에서는 hook도 함께 둡니다. Claude Code hook은 tool 실행 전후 같은 lifecycle 지점에서 자동 실행되는 사용자 정의 명령입니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "node .claude/hooks/block-dangerous-git.mjs"
          }
        ]
      }
    ]
  }
}

// .claude/hooks/block-dangerous-git.mjs
import process from "node:process";

let raw = "";
for await (const chunk of process.stdin) raw += chunk;

const input = JSON.parse(raw || "{}");
const command = input.tool_input?.command ?? "";

const blocked = [
  /git\s+reset\s+--hard\b/,
  /git\s+clean\s+-[^\s]*f/,
  /git\s+push\s+--force(?!-with-lease)/,
  /git\s+checkout\s+--\s+\./,
  /git\s+restore\s+\.\b/
];

if (blocked.some((pattern) => pattern.test(command))) {
  process.stderr.write(`Blocked risky Git command: ${command}\n`);
  process.exit(2);
}

hook은 보조 장치입니다. 사람의 terminal 명령까지 모두 막지는 못합니다. 그래서 CLAUDE.md, review gate, CI와 함께 써야 합니다.

push 전에 local CI 실행

remote CI가 실패할 때까지 기다리면 늦습니다. 프로젝트에 있는 script만 실행하는 preflight를 두면 Claude Code 작업마다 반복할 수 있습니다.

// scripts/claude-git-preflight.mjs
import { execSync } from "node:child_process";
import { existsSync, readFileSync } from "node:fs";

const run = (command) => {
  console.log(`\n$ ${command}`);
  execSync(command, { stdio: "inherit", shell: true });
};

run("git diff --check");
run("git diff --cached --check");
run("git status --short");

const pkg = existsSync("package.json")
  ? JSON.parse(readFileSync("package.json", "utf8"))
  : { scripts: {} };

for (const script of ["lint", "typecheck", "test", "build"]) {
  if (pkg.scripts?.[script]) run(`npm run ${script}`);
}

node scripts/claude-git-preflight.mjs

Claude Code에는 성공했다고 말할 수 있는 기준을 분명히 줍니다.

After implementation, run the local preflight.
If a command fails, stop and explain the first failing command, likely cause, and smallest next fix.
Do not push until the preflight is green.

pre-commit과 GitHub Actions

pre-commit은 commit 직전에 검사하는 도구입니다. 사람과 Claude Code가 같은 local gate를 지나게 할 수 있습니다.

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: git-diff-check
        name: git diff whitespace check
        entry: git diff --check
        language: system
        pass_filenames: false
      - id: npm-test
        name: npm test when available
        entry: node scripts/claude-git-preflight.mjs
        language: system
        pass_filenames: false

python -m pip install pre-commit
pre-commit install
pre-commit run --all-files

PR에서는 GitHub Actions가 같은 관점을 clean runner에서 다시 확인합니다.

# .github/workflows/claude-code-pr-gate.yml
name: Claude Code PR Gate

on:
  pull_request:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - run: npm ci
      - run: git diff --check origin/main...HEAD
      - run: npm run lint --if-present
      - run: npm run typecheck --if-present
      - run: npm test --if-present
      - run: npm run build --if-present

conflict, rebase, rollback

conflict는 Git이 같은 위치의 두 변경 중 무엇을 선택할지 모르는 상태입니다. Claude Code에게 바로 해결하라고 하지 말고, 양쪽 의도를 먼저 설명하게 하세요.

git fetch origin
git rebase origin/main
git status --short
git diff --name-only --diff-filter=U

We are in a rebase conflict.
For each conflicted file, explain what our branch changed and what origin/main changed.
Resolve only after explaining the business intent.
After editing, run the narrowest relevant test.
Do not continue the rebase until I approve the resolved diff.

git add src/checkout/validateCoupon.ts
npm test -- --runInBand validateCoupon
git rebase --continue

잘못된 방향이면 중단합니다.

git rebase --abort

공유된 commit을 되돌릴 때는 증거가 남는 git revert를 우선합니다.

git log --oneline -5
git revert --no-edit HEAD
git status --short

아직 commit하지 않은 파일은 정확한 path만 복구합니다.

git restore --staged src/checkout/validateCoupon.ts
git restore src/checkout/validateCoupon.ts

실무 use case와 실패 예

개인 기능 개발에서는 feature/yyyyMMdd-topic branch를 만들고, Claude Code에 수정 파일과 테스트를 제한합니다. commit은 하나의 동작 변화만 담고 push 전 preflight를 통과합니다.

팀 PR에서는 역할을 나눕니다. 구현 session은 commit하지 않고, review session은 staged diff만 봅니다. 사람은 PR title, CI, risk, rollback을 확인합니다.

콘텐츠와 상품 페이지 업데이트에서는 slug와 locale 단위로 작업합니다. ClaudeCodeLab에서는 글, Gumroad 링크, 교육 CTA, 내부 링크가 매출 흐름과 연결되므로 description 길이, hero, CTA, 깨진 번역을 함께 확인해야 합니다.

장기 refactor는 테스트 추가, 내부 구현 변경, 삭제를 commit으로 나눕니다. 한 번에 모든 것을 바꾸라고 요청하지 않습니다.

실패	원인	예방
git add -A가 무관한 파일을 stage	AI가 넓게 수정함	path 지정으로 stage
commit이 너무 큼	구현, 테스트, 설정이 섞임	commit 하나에 목적 하나
conflict를 대충 해결	양쪽 의도를 읽지 않음	ours/theirs 설명 먼저
rebase 후 push 사고	remote history와 충돌	팀 규칙 아래 --force-with-lease만
PR CI 실패	local check 생략	preflight 실행
파괴적 rollback	reset --hard 사용	공유 commit은 git revert

daily handoff

handoff는 짧고 검증 가능해야 합니다.

## Handoff: 2026-06-02

Branch: feature/20260602-checkout-coupon-validation
Goal: validate coupon expiry before payment authorization

Changed:
- src/checkout/validateCoupon.ts
- tests/checkout/validateCoupon.test.ts

Checks:
- npm run lint: passed
- npm test -- --runInBand validateCoupon: passed
- npm run build: not run, no UI/build config touched

Risk:
- Coupon timezone boundary still needs one integration test.

Rollback:
- Revert commit `abc1234` if production checkout rejects valid coupons.

다음 단계

혼자 익히는 단계라면 무료 Claude Code cheatsheet로 기본 명령을 옆에 두세요. reusable prompt, CLAUDE.md, review template이 필요하면 ClaudeCodeLab 제품과 템플릿을 확인하면 됩니다. 팀의 실제 repo에 맞춰 branch 규칙, CI, 권한, rollback, handoff를 설계해야 한다면 Claude Code 교육 및 도입 상담이 더 현실적인 선택입니다.

실제로 적용해 본 결과

ClaudeCodeLab 콘텐츠 업데이트에 이 Git loop를 적용하자 review 기준이 “전체를 다시 읽기”에서 “slug, locale, metadata, CTA, diff scope 확인”으로 줄었습니다. 특히 git diff --staged --stat과 handoff가 효과적이었습니다. Claude Code의 장점은 빠르게 쓰는 것뿐 아니라, 다음 사람이 믿고 이어갈 증거를 남기게 할 때 가장 커집니다.