🚀 Claude Code + Git 워크플로우 완벽 가이드

Claude Code와 Git을 결합하면 개발 속도가 10배는 빨라진다. 브랜치 관리부터 PR 생성까지 자동화하는 방법을 알아보자.

🎯 핵심 개념

Claude Code는 Git과 완벽하게 통합되어 있다:

✅ 자동 커밋 메시지 생성 (Conventional Commits)
✅ PR 자동 생성 및 설명 작성
✅ 브랜치 전략 자동화
✅ Git Hooks와의 통합
✅ Git Worktrees를 통한 병렬 개발

Claude Code로 브랜치 관리하기

새 기능 브랜치 생성

claude "feature/user-profile-edit 브랜치 만들고,
       사용자 프로필 수정 기능 구현해줘"

Claude가 자동으로:

브랜치 생성
코드 작성
커밋 메시지 생성
푸시

브랜치 네이밍 컨벤션

.claude/CLAUDE.md에 추가:

## Branch Naming Convention

Always follow this format:

- `feature/{feature-name}` - 새 기능
- `fix/{bug-name}` - 버그 수정
- `refactor/{module-name}` - 리팩토링
- `docs/{topic}` - 문서화
- `test/{test-name}` - 테스트 추가

Use kebab-case for all branch names.

사용 예시:

claude "로그인 버그 수정하는 브랜치 만들어줘"

# Claude가 자동으로 fix/login-validation-error 같은 이름 생성

🤖 Conventional Commits 자동화

Conventional Commits란?

커밋 메시지를 표준화해서 자동 릴리즈 노트 생성, semantic versioning을 가능하게 한다.

포맷:

<type>(<scope>): <subject>

<body>

<footer>

타입:

feat: 새 기능
fix: 버그 수정
refactor: 리팩토링
docs: 문서 변경
test: 테스트 추가
chore: 빌드/설정 변경

Claude Code의 자동 커밋

# 변경사항 자동 분석 후 커밋
claude commit

실제 예시:

feat(auth): add JWT token refresh mechanism

- Implement automatic token refresh before expiration
- Add retry logic for failed refresh attempts
- Store refresh token in httpOnly cookie for security

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>

커밋 스타일 커스터마이징

.claude/CLAUDE.md에 추가:

## Commit Message Style

When creating commits, follow these rules:

1. Use Conventional Commits format
2. Keep subject line under 50 characters
3. Include ticket number if available (e.g., "feat: add feature (PROJ-123)")
4. Write imperative mood ("add" not "added")
5. Explain WHY, not WHAT in the body

Example:
feat(api): add rate limiting to auth endpoints

Previous implementation allowed unlimited requests, causing
server overload during peak hours. New rate limiter uses
Redis to track request counts per IP.

Closes #456

이렇게 설정하면 Claude가 자동으로 이 스타일을 따라 커밋 메시지를 생성한다.

🔀 PR 자동화

PR 자동 생성

claude "현재 브랜치로 main에 PR 만들어줘"

Claude가 자동으로:

변경사항 분석
PR 제목/본문 작성
체크리스트 생성
GitHub PR 생성

실제 생성된 PR 예시

제목:

feat: Add user profile editing with image upload

본문:

## Summary

Implements user profile editing feature with the following capabilities:

- ✅ Edit name, email, bio
- ✅ Upload profile image with automatic resizing
- ✅ Crop and preview before saving
- ✅ S3 integration for image storage

## Technical Changes

- Added `/api/users/[id]/profile` PUT endpoint
- Integrated `sharp` for image processing
- Added form validation with `zod`
- Updated User model schema

## Test Plan

- [ ] Create new user and edit profile
- [ ] Upload image larger than 5MB (should fail)
- [ ] Upload valid JPG/PNG (should succeed)
- [ ] Check S3 bucket for uploaded images
- [ ] Verify thumbnail generation

## Screenshots

[스크린샷 자동 첨부]

🤖 Generated with Claude Code

Closes #123

PR 템플릿 커스터마이징

.claude/CLAUDE.md:

## Pull Request Template

When creating PRs, include:

1. **What**: Brief description (1-2 sentences)
2. **Why**: Problem being solved
3. **How**: Technical approach
4. **Testing**: How to verify
5. **Screenshots**: For UI changes
6. **Breaking Changes**: If any
7. **Related Issues**: Link to issues

Format:

```markdown
## What & Why

Added user profile editing feature to allow users to update their personal information and profile pictures.

## Technical Approach

- Created `/api/users/[id]/profile` PUT endpoint with authentication middleware
- Integrated `sharp` library for server-side image resizing (max 800x800px)
- Added S3 bucket integration for profile image storage
- Implemented form validation using `zod` schema
- Updated User model to include `profileImageUrl` field

## Testing

- [ ] Unit tests passing (auth middleware, image processing)
- [ ] Manual testing completed (upload various image formats)
- [ ] E2E tests added (user journey: login → edit profile → verify changes)
- [ ] Tested with images > 5MB (should reject)
- [ ] Verified S3 bucket permissions

## Related Issues

Closes #42
```

🪝 Git Hooks 통합

커밋 전 자동 체크

.claude/settings.json:

{
  "hooks": {
    "beforeCommit": "npm run lint && npm run type-check",
    "afterCommit": "echo 'Commit successful! 🎉'",
    "beforePush": "npm test"
  }
}

동작 방식:

claude commit

# 1. Claude가 변경사항 분석
# 2. 커밋 메시지 생성
# 3. beforeCommit hook 실행 (lint + type-check)
# 4. ✅ 통과하면 커밋
# 5. afterCommit hook 실행

실전 Hook 시나리오

시나리오 1: 커밋 전 자동 포맷팅

{
  "hooks": {
    "beforeCommit": "prettier --write . && git add -u"
  }
}

→ 커밋 전에 자동으로 코드 포맷팅 + 스테이징

시나리오 2: 푸시 전 빌드 검증

{
  "hooks": {
    "beforePush": "npm run build && npm run test:e2e"
  }
}

→ 빌드 실패하면 푸시 차단!

시나리오 3: 커밋 메시지 검증

.git/hooks/commit-msg (수동 생성):

#!/bin/sh

# Conventional Commits 형식 검증
commit_msg=$(cat "$1")

if ! echo "$commit_msg" | grep -qE "^(feat|fix|docs|refactor|test|chore)(\(.+\))?: .+"; then
  echo "❌ 커밋 메시지가 Conventional Commits 형식이 아닙니다!"
  echo "예시: feat(auth): add login feature"
  exit 1
fi

🔄 Git Worktrees로 병렬 개발

Worktrees란?

하나의 Git 저장소를 여러 디렉토리에 체크아웃해서 동시에 여러 브랜치 작업 가능!

설정 방법

# 메인 프로젝트
cd ~/projects/my-app

# 새 브랜치용 worktree 생성
git worktree add ../my-app-feature1 feature/authentication
git worktree add ../my-app-feature2 feature/dark-mode

# 이제 3개의 디렉토리가 생김
# ~/projects/my-app (main)
# ~/projects/my-app-feature1 (feature/authentication)
# ~/projects/my-app-feature2 (feature/dark-mode)

Claude Code로 병렬 작업

터미널 1:

cd ~/projects/my-app-feature1
claude "인증 미들웨어 구현해줘"

터미널 2 (동시에!):

cd ~/projects/my-app-feature2
claude "다크모드 토글 UI 만들어줘"

두 Claude 인스턴스가 독립적으로 작업!

Worktrees 관리

# 활성 worktree 목록
git worktree list

# worktree 삭제
git worktree remove ../my-app-feature1

# 브랜치도 삭제
git branch -d feature/authentication

💡 실전 워크플로우

워크플로우 1: 기능 개발 → PR

# 1. 새 기능 브랜치
claude "feature/add-comments 브랜치 만들고,
       블로그 포스트에 댓글 기능 추가해줘.
       DB 스키마, API, UI 모두 포함"

# Claude가 작업하는 동안 기다리기...
# 완료되면 자동으로 커밋됨

# 2. PR 생성
claude "PR 만들어줘. 제목은 'Add comment system with moderation'으로"

# 3. 코드 리뷰 요청
claude "이 PR의 변경사항 요약해서 Slack에 알려줘"

5분 만에 기능 개발 완료!

워크플로우 2: 버그 수정 (Hotfix)

# 1. main에서 hotfix 브랜치
git checkout main
claude "hotfix/login-csrf 브랜치 만들고,
       로그인 CSRF 취약점 수정해줘"

# 2. 즉시 PR 생성 (리뷰 생략 가능)
claude "긴급 hotfix PR 만들어줘"

# 3. 병합 후 배포
gh pr merge --merge --delete-branch
npm run deploy

워크플로우 3: 멀티 브랜치 동시 작업

# Worktrees 활용

# 터미널 1: 메인 기능
cd ~/my-app
claude "feature/new-dashboard 브랜치에서 대시보드 UI 리팩토링"

# 터미널 2: 문서화 (동시에!)
git worktree add ../my-app-docs docs/api-guide
cd ../my-app-docs
claude "API 문서 작성해줘. OpenAPI 스펙으로"

# 터미널 3: 버그 수정 (동시에!)
git worktree add ../my-app-fix fix/memory-leak
cd ../my-app-fix
claude "메모리 누수 원인 찾고 수정해줘"

3개의 Claude가 동시에 다른 작업 수행!

🔧 고급 팁

1. 자동 브랜치 정리

.claude/CLAUDE.md:

## Branch Cleanup Policy

After merging PRs, always:

1. Delete the merged branch locally
2. Delete the remote branch
3. Run `git fetch --prune` to clean up references

Command: `git branch --merged | grep -v main | xargs git branch -d`

2. 커밋 메시지에 이슈 번호 자동 추가

.claude/settings.json:

{
  "hooks": {
    "beforeCommit": "node scripts/add-issue-number.js"
  }
}

scripts/add-issue-number.js:

// 브랜치 이름에서 이슈 번호 추출
// feature/user-auth-123 → "Refs #123"
const branch = require('child_process').execSync('git branch --show-current').toString().trim();

const match = branch.match(/-(\d+)$/);
if (match) {
  console.log(`\n\nRefs #${match[1]}`);
}

3. PR 자동 라벨링

.claude/CLAUDE.md:

## PR Labels

When creating PRs, auto-assign labels based on changes:

- `feat` → label: `enhancement`
- `fix` → label: `bug`
- `docs` → label: `documentation`
- `refactor` → label: `refactoring`
- `test` → label: `testing`

Use `gh pr create --label "enhancement,high-priority"`

4. Draft PR로 시작하기

claude "Draft PR 만들어줘. 아직 리뷰 준비 안 됨"

# Claude가 실행:
gh pr create --draft --title "WIP: Add payment integration"

나중에:

gh pr ready  # Draft → Ready for review

🚦 브랜치 보호 규칙

GitHub Branch Protection 설정

main 브랜치 보호:

Settings → Branches → Add rule

Branch name pattern: main

✅ Require pull request reviews (최소 1명)
✅ Require status checks to pass
  - CI/CD pipeline
  - Code coverage > 80%
✅ Require branches to be up to date
✅ Include administrators

Claude Code와 보호 규칙 우회 방지

.claude/CLAUDE.md:

## Branch Protection

NEVER push directly to `main` or `production` branches.
Always create a PR, even for small changes.

If you need to make changes to protected branches:

1. Create a feature branch
2. Make changes
3. Create PR
4. Wait for CI/CD approval
5. Merge via GitHub UI

🎨 팀 협업 시나리오

시나리오 1: 코드 리뷰 요청

# PR 생성 후
claude "이 PR을 @senior-dev에게 리뷰 요청하고,
       주요 변경사항을 Slack #dev-team 채널에 알려줘"

시나리오 2: Conflict 해결

# Merge conflict 발생 시
claude "main 브랜치와 conflict 났어. 해결해줘"

# Claude가 자동으로:
# 1. main pull
# 2. conflict 파일 분석
# 3. 자동 머지 (가능하면)
# 4. 수동 개입 필요하면 알림

시나리오 3: Release 준비

claude "v2.0.0 릴리즈 준비해줘:
       1. release/v2.0 브랜치 생성
       2. CHANGELOG.md 업데이트 (최근 커밋 기반)
       3. package.json 버전 업데이트
       4. Release PR 생성"

⚠️ 주의사항

1. 민감한 정보 커밋 방지

.gitignore:

.env
.env.local
*.key
*.pem
secrets/
config/local.js

.claude/CLAUDE.md:

## Security Rules

NEVER commit:

- API keys or tokens
- Database credentials
- Private keys
- User data

Always check with `git diff --staged` before committing.

2. Force Push 절대 금지

# ❌ 절대 하지 말 것
git push --force origin main

# ✅ 대신 이렇게
git revert <commit-hash>

3. 커밋 히스토리 정리

# feature 브랜치에서 작은 커밋들 정리
claude "최근 5개 커밋을 하나로 합쳐줘. 메시지는 'feat: complete user auth system'으로"

# Claude가 실행:
git rebase -i HEAD~5
# squash commits

🎓 정리

Claude Code + Git 핵심:

자동 커밋 - Conventional Commits로 표준화
PR 자동화 - 제목/본문/체크리스트 자동 생성
Git Hooks - 커밋/푸시 전 자동 검증
Worktrees - 병렬 개발로 생산성 10배
브랜치 전략 - GitHub Flow 추천

실전 팁:

.claude/CLAUDE.md로 브랜치/커밋 규칙 정의
Hooks로 품질 관리 자동화
Draft PR로 빠른 피드백
Worktrees로 context switching 최소화

다음 단계:

GitHub Actions와 Claude Code 통합
Semantic Release 자동화
Monorepo에서 Claude Code 활용

Git 워크플로우 자동화하면 코딩에만 집중할 수 있다! 🚀

참고 자료: