Git Commit Message Prefix Guide - 정리

Git Commit Message Prefix Guide

목적: 팀/개인 모두에게 일관성 있는 커밋 히스토리를 제공하고, 변경 의도를 커밋 한 줄만 보고 즉시 파악할 수 있게 한다.

이 가이드는 Conventional Commits를 기반으로 하되, 실무에서 가장 많이 쓰이고 오해가 적은 형태로 정리했다.

---

1️⃣ 기본 형식 (표준)

<prefix>(scope): short description

예시

feat(auth): add social login with Google fix(web): resolve hydration mismatch on SSR chore: bump version to 0.1.5

• prefix : 변경의 성격 (가장 중요)
• scope : 영향 범위 (선택)
• description : 명확하고 짧게 (명령문)

---

2️⃣ Prefix 표준 목록 (실무 추천)

✅ feat — 기능 추가

의미

• 사용자에게 보이는 새 기능

언제 쓰나

• 버튼, API, 화면, 옵션 추가

예시

feat(payment): add KakaoPay support

---

🐛 fix — 버그 수정

의미

• 잘못된 동작을 바로잡음

언제 쓰나

• 에러, 크래시, 잘못된 계산, 예외 처리

예시

fix(api): handle null token edge case

---

🧹 chore — 잡일 / 유지보수

의미

• 기능과 무관한 필수 관리 작업

언제 쓰나

• 버전 업, 의존성 업데이트, 설정 변경

예시

chore: bump version to 0.1.5 chore(ci): update node version

---

♻️ refactor — 리팩토링

의미

• 동작은 그대로, 구조만 개선

언제 쓰나

• 코드 정리, 중복 제거, 가독성 개선

절대 포함되면 안 되는 것

• 기능 변경
• 버그 수정

예시

refactor(auth): simplify token validation logic

---

📚 docs — 문서 변경

의미

• 문서만 변경

언제 쓰나

• README, 가이드, 주석, API 문서

예시

docs: add expert guide for deployment

---

🎨 style — 코드 스타일

의미

• 로직 변화 없는 스타일 수정

언제 쓰나

• 포맷팅, 세미콜론, 공백, 린트

예시

style: apply prettier formatting

---

⚡ perf — 성능 개선

의미

• 속도, 메모리, 리소스 개선

언제 쓰나

• 캐싱, 쿼리 최적화, 렌더링 개선

예시

perf(web): reduce bundle size by code splitting

---

🧪 test — 테스트

의미

• 테스트 코드 추가/수정

언제 쓰나

• 유닛 테스트, E2E, 테스트 리팩토링

예시

test(auth): add token expiration tests

---

🔧 build — 빌드 시스템

의미

• 빌드 도구, 설정 변경

언제 쓰나

• webpack, vite, gradle, maven 설정

예시

build: update next.js build config

---

🚀 ci — CI/CD 설정

의미

• 자동화 파이프라인 변경

언제 쓰나

• GitHub Actions, Jenkins, GitLab CI

예시

ci: add release workflow

---

3️⃣ 자주 헷갈리는 Prefix 비교

---

4️⃣ 추천 규칙 (팀 적용용)

• prefix는 소문자
• description은 동사 원형 (add, fix, remove)
• 한 커밋에 하나의 성격만
• 애매하면 feat / fix / chore 중 하나로 귀결

---

5️⃣ 한 줄 요약

커밋 메시지는 과거 기록이 아니라 미래의 설명서다.

이 prefix 가이드만 지켜도

• git log 가 읽히고
• 리뷰 속도가 빨라지고
• 릴리즈 노트 자동화가 가능해진다.