# Git Workflow

> Git 브랜치 전략 및 협업 워크플로우. 브랜치 전략, 커밋 메시지, PR 생성, Git 협업 요청 시 사용.

- Skill: `koaedo/git-workflow` (Agent Skill)
- Install (CLI): `npx skillmds@latest add koaedo/git-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/koaedo/git-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: koaedo (https://skillmd.com/u/koaedo)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/koaedo/git-workflow

---


# Git Workflow Skill

Git 브랜치 전략 및 협업 워크플로우 가이드

## When to Use
- Git 브랜치 전략 수립 시
- 커밋 메시지 작성 시
- PR 생성 시
- 협업 워크플로우 정립 시

---

## 🌳 브랜치 전략

### GitHub Flow (권장 - 소규모/CI-CD)

```
main ──●────●────●────●────●──
        ╲        ↗    ╲      ↗
         ╲──●──●╱      ╲──●─╱
         feature-1    feature-2

규칙:
- main은 항상 배포 가능
- feature 브랜치에서 작업
- PR로 main에 머지
```

### Git Flow (복잡한 릴리즈 관리)

```
main     ●──────────────────●────────●──
          ╲                ↗        ↗
release    ╲────●────●────╱        ╱
develop ────●──────●──────●──────●────

브랜치:
- main: 프로덕션
- develop: 개발 통합
- feature/*: 기능 개발
- release/*: 릴리즈 준비
- hotfix/*: 긴급 수정
```

---

## 📋 브랜치 네이밍

```bash
# 기능 개발
feature/user-authentication
feature/JIRA-123-add-login

# 버그 수정
fix/login-redirect-error
fix/JIRA-456-memory-leak

# 긴급 수정
hotfix/security-vulnerability

# 리팩토링
refactor/database-layer

# 문서
docs/api-documentation
```

### 명명 규칙

```
✅ 좋은 예
feature/add-user-profile
fix/cart-item-count

❌ 나쁜 예
feature/myFeature     # 불명확
john-branch           # 개인 이름
test123               # 의미 없음
```

---

## 📋 커밋 메시지

### Conventional Commits

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

<body>

<footer>
```

### Type 종류

```
feat:     새 기능 추가
fix:      버그 수정
docs:     문서 변경
style:    코드 포맷팅 (기능 변경 없음)
refactor: 리팩토링 (기능 변경 없음)
perf:     성능 개선
test:     테스트 추가/수정
build:    빌드 시스템 변경
ci:       CI 설정 변경
chore:    기타 변경
revert:   커밋 되돌리기
```

### 예시

```bash
# 기능 추가
feat(auth): 소셜 로그인 추가

Google, GitHub OAuth 연동
- OAuth2 클라이언트 설정
- 콜백 핸들러 구현

Closes #123

# 버그 수정
fix(cart): 수량 0 이하로 설정되는 버그 수정

최소 수량을 1로 제한하는 검증 추가

Fixes #456

# Breaking Change
feat(api)!: API 응답 형식 변경

BREAKING CHANGE: 응답 wrapper가 변경됨
```

---

## 📋 Pull Request 가이드

### PR 템플릿

```markdown
## 📋 변경 사항
- 사용자 프로필 편집 기능 추가
- 이미지 업로드 구현

## 🎯 관련 이슈
Closes #123

## 🧪 테스트 방법
1. 프로필 페이지 접속
2. 편집 버튼 클릭
3. 정보 수정 후 저장

## ✅ 체크리스트
- [ ] 테스트 통과
- [ ] 린트 통과
- [ ] 문서 업데이트 (필요시)
```

### PR 크기 가이드

```
✅ 이상적인 PR
- 200-400 줄 변경
- 하나의 기능/수정
- 빠른 리뷰 가능

⚠️ 큰 PR은 분할
- 리팩토링 PR + 기능 PR
- 의존성 업데이트 별도 PR
```

---

## 📋 Git 명령어 치트시트

### 브랜치 작업

```bash
git checkout -b feature/new-feature
git switch -c feature/new-feature  # 새 명령어

git branch          # 로컬
git branch -r       # 원격
git branch -a       # 전체

git branch -d feature/done        # 머지된 브랜치
git push origin --delete feature/old
```

### 커밋 관리

```bash
git commit --amend -m "수정된 메시지"
git reset --soft HEAD~1   # 커밋 취소 (변경사항 유지)
git reset --hard HEAD~1   # 커밋 취소 (변경사항 삭제)
git revert <commit-hash>  # 특정 커밋 되돌리기
```

### Stash

```bash
git stash
git stash push -m "설명"
git stash list
git stash pop         # 적용 후 삭제
git stash apply       # 적용 (삭제 안 함)
```

### Rebase

```bash
git checkout feature/my-feature
git rebase main

git rebase -i HEAD~3  # 인터랙티브 rebase
git rebase --continue
git rebase --abort
```

---

## 📋 충돌 해결

```bash
# 1. 충돌 파일 확인
git status

# 2. 충돌 마커 확인
<<<<<<< HEAD
현재 브랜치 코드
=======
머지하려는 브랜치 코드
>>>>>>> feature/other

# 3. 수동으로 해결 후
git add <resolved-file>
git commit -m "Merge conflict resolved"
```

---

## 📋 Git 체크리스트

```
브랜치:
[ ] 의미 있는 브랜치명?
[ ] 최신 main에서 분기?

커밋:
[ ] 작은 단위 커밋?
[ ] 명확한 커밋 메시지?

PR:
[ ] PR 설명 작성?
[ ] 테스트 통과?
```

---

## 🚫 Git 안티패턴

```
❌ main에 직접 푸시
❌ force push (공유 브랜치에)
❌ 너무 큰 커밋
❌ "WIP", "fix" 같은 불명확한 메시지
❌ 비밀정보 커밋 (API 키, 비밀번호)
❌ node_modules, .env 커밋
```

