협업하는 개발팀에서 코드만큼 중요한 것이 바로 커밋 메시지입니다. 잘 작성된 커밋 메시지는 단순한 변경 이력 기록을 넘어, 팀원 간의 의사소통 수단이자 프로젝트의 살아있는 역사 문서가 됩니다. 반대로 "fix", "수정", "asdfgh"처럼 의미 없는 커밋 메시지들이 쌓이면, 버그 추적과 코드 리뷰, 배포 이력 관리가 극도로 어려워집니다. 이 글에서는 전 세계 개발자들이 표준으로 사용하는 Conventional Commits 규칙과 실전 커밋 작성 노하우를 완벽하게 정리해드립니다.
1. 왜 커밋 메시지 규칙이 필요한가?
무질서한 커밋 히스토리가 유발하는 실질적인 문제점들을 살펴봅시다.
- 버그 추적 불가: "fix" 라는 커밋이 수십 개 쌓이면
git log나git bisect로 버그가 도입된 정확한 시점을 찾는 것이 불가능에 가깝습니다. - 코드 리뷰 품질 저하: 커밋 단위가 너무 크거나 목적이 불분명하면 리뷰어가 변경 의도를 파악하기 어렵습니다.
- CHANGELOG 자동화 불가: 일관된 규칙이 있어야
standard-version,semantic-release같은 도구로 릴리즈 노트를 자동 생성할 수 있습니다. - 협업 맥락 단절: 새로 합류한 팀원이 과거 결정 사항을 추론하기가 매우 어렵습니다.
2. Conventional Commits 명세
Conventional Commits는 인간과 도구 모두가 읽기 쉬운 커밋 메시지를 작성하기 위한 경량 컨벤션으로, Angular 팀이 처음 도입한 후 업계 표준으로 자리 잡았습니다.
기본 형식
<타입>[적용 범위(선택)]: <설명>
[본문(선택)]
[꼬리말(선택)]
커밋 타입 종류
| 타입 | 의미 | 예시 |
|---|---|---|
feat |
새로운 기능 추가 | feat: 소셜 로그인 기능 추가 |
fix |
버그 수정 | fix: 로그인 토큰 만료 오류 수정 |
docs |
문서 수정 (README 등) | docs: API 명세 업데이트 |
style |
코드 포맷팅 (로직 변경 없음) | style: 세미콜론 누락 추가 |
refactor |
리팩토링 (기능·버그 변경 없음) | refactor: 회원가입 서비스 레이어 분리 |
test |
테스트 코드 추가·수정 | test: 주문 서비스 단위 테스트 추가 |
chore |
빌드 설정, 의존성 업데이트 | chore: Spring Boot 3.2.0 버전 업 |
perf |
성능 개선 | perf: 상품 목록 캐싱 로직 최적화 |
ci |
CI/CD 설정 변경 | ci: GitHub Actions 배포 스크립트 수정 |
revert |
이전 커밋 되돌리기 | revert: feat: 소셜 로그인 기능 추가 |
3. 좋은 커밋 메시지 실전 예시
나쁜 예 vs 좋은 예
# ❌ 나쁜 예
git commit -m "수정"
git commit -m "fix bug"
git commit -m "update code asdf"
# ✅ 좋은 예 - 타입과 명확한 설명
git commit -m "fix(auth): 리프레시 토큰 만료 시 자동 로그아웃 처리 오류 수정"
git commit -m "feat(order): 장바구니 물품 일괄 삭제 API 추가"
git commit -m "refactor(user): UserService에서 이메일 발송 로직을 EmailService로 분리"
본문(Body)과 꼬리말(Footer)이 있는 완성형 커밋
feat(payment): 카카오페이 결제 연동 기능 추가
- 카카오페이 SDK 3.2.0 연동 및 초기화 설정 추가
- 결제 요청/승인/취소 API 엔드포인트 구현
- 결제 실패 시 재시도 로직(최대 3회) 구현
- 결제 내역 DB 저장 및 영수증 이메일 발송 연동
Resolves: #142
Co-authored-by: 홍길동 <hong@example.com>
꼬리말 활용 팁:
Resolves: #이슈번호: GitHub/Jira 이슈를 자동으로 닫아줍니다.BREAKING CHANGE:: 하위 호환이 깨지는 변경 사항을 명시적으로 표기합니다.Co-authored-by:: 페어 프로그래밍으로 작업한 공동 작업자를 표기합니다.
4. Git 커밋 단위 황금률
좋은 커밋 메시지 못지않게 중요한 것이 **커밋의 크기와 원자성(Atomicity)**입니다.
원자적(Atomic) 커밋의 원칙:
- 한 커밋 = 하나의 논리적 변경 단위: 로그인 버그 수정과 상품 목록 UI 변경을 하나의 커밋에 담지 마세요.
- 빌드 가능한 상태 유지: 각 커밋은 독립적으로 체크아웃했을 때 빌드가 가능한 상태여야 합니다.
- 너무 작아도 안 됨: 변수명 하나 바꾼 커밋과 로직 변경 커밋을 분리할 필요는 없습니다. 관련된 변경을 묶어 의미 있는 단위로 만드세요.
5. 커밋 메시지 자동 검증: commitlint 설정
팀 전체에 컨벤션을 자동으로 강제하려면 commitlint와 husky를 함께 설정합니다.
# 패키지 설치
npm install --save-dev @commitlint/config-conventional @commitlint/cli husky
commitlint.config.js 설정:
// commitlint.config.js
module.exports = {
extends: ['@commitlint/config-conventional'],
rules: {
'type-enum': [
2, 'always',
['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore', 'perf', 'ci', 'revert']
],
'subject-max-length': [2, 'always', 72], // 제목 최대 72자
'subject-case': [2, 'never', ['upper-case']], // 제목 대문자 시작 금지
}
};
husky hook 등록:
# husky 초기화 및 commit-msg 훅 등록
npx husky init
echo "npx --no-install commitlint --edit \$1" > .husky/commit-msg
이 설정을 적용하면 규칙에 맞지 않는 커밋 메시지는 자동으로 거부되어 팀 전체의 컨벤션이 코드 레벨에서 강제됩니다.
6. 자주 묻는 질문 (FAQ)
Q1. 커밋 메시지를 한국어로 써야 하나요, 영어로 써야 하나요?
팀의 구성원에 따라 다릅니다. 외국인 개발자가 없는 한국 팀이라면 한국어로 써도 전혀 문제없습니다. 중요한 것은 언어의 일관성입니다. 한 프로젝트 안에서 한국어와 영어가 섞이는 것이 가장 좋지 않습니다. 단, feat:, fix: 같은 타입 키워드는 Conventional Commits 명세에 따라 영어 소문자로 유지하는 것이 commitlint 도구 연동 시 호환성 측면에서 권장됩니다.
Q2. 이미 작성된 커밋 메시지를 수정할 수 있나요?
가장 최근 커밋이라면 git commit --amend -m "새 메시지" 명령어로 수정 가능합니다. 더 이전 커밋을 수정하려면 git rebase -i HEAD~N 명령어로 인터랙티브 리베이스를 사용합니다. 단, 이미 원격 브랜치(origin)에 push된 커밋은 되도록 수정하지 않는 것을 권장합니다. 강제 push(push --force)는 팀원들의 히스토리를 깨뜨릴 수 있습니다.
Q3. 커밋 컨벤션과 CHANGELOG 자동 생성은 어떻게 연결되나요?
standard-version 또는 semantic-release 라이브러리를 사용하면 Conventional Commits 규칙을 따르는 커밋 히스토리를 자동 분석하여 버전을 자동으로 올리고(Semantic Versioning), CHANGELOG.md 파일을 자동 생성할 수 있습니다. feat: 커밋은 마이너 버전을, fix: 커밋은 패치 버전을 올리며, BREAKING CHANGE: 가 있으면 메이저 버전을 올립니다.
7. 마무리 및 권장사항
커밋 메시지는 미래의 나 자신과 팀원들에게 쓰는 기술 편지입니다. 처음에는 불편하게 느껴질 수 있지만, 한 달만 습관으로 만들면 코드 리뷰 속도가 빨라지고, 버그 추적이 명확해지며, 팀의 협업 수준이 한 단계 높아지는 것을 체감하게 됩니다. commitlint + husky 도구를 통해 팀 전체에 자동으로 강제하는 것을 강력히 권장합니다.
