핵심 요약
좋은 커밋 메시지는 "무엇을 바꿨나"가 아니라 "왜 바꿨나"를 남긴다. 코드는 diff로 알 수 있지만 의도는 메시지에만 있다. Conventional Commits(type: subject 형식)를 쓰면 사람도 읽기 좋고, 버전·changelog 자동화까지 얻는다.
1. 기본 구조
<type>(<scope>): <subject>
<body> # 왜 이렇게 바꿨는지(선택)
<footer> # BREAKING CHANGE, 이슈 번호(선택)feat(auth): 소셜 로그인 추가
fix(cart): 수량 0일 때 결제 버튼 비활성화
docs: README에 설치 방법 보강2. 주요 type
| type | 의미 |
|---|---|
| feat | 새 기능 |
| fix | 버그 수정 |
| docs | 문서만 변경 |
| refactor | 동작 변화 없는 구조 개선 |
| test | 테스트 추가·수정 |
| chore | 빌드·설정 등 잡무 |
3. subject 규칙
- 명령형·현재형으로("추가함" ❌ → "추가" ✅ / "add" ✅ "added" ❌)
- 50자 이내, 끝에 마침표 없이
- "무엇을"보다 왜가 궁금하면 body에 배경을 적는다
4. 왜를 남기는 예
fix(api): 결제 재시도 시 중복 청구 방지
네트워크 타임아웃 후 클라이언트가 재요청하면
같은 결제가 두 번 처리되는 문제가 있었다.
멱등성 키로 중복 요청을 차단한다.
Closes #1425. 자동화로 얻는 것
- 자동 changelog — feat/fix를 모아 릴리스 노트 생성
- 시맨틱 버저닝 — feat=minor, fix=patch, BREAKING CHANGE=major 자동 판정
- commitlint + husky로 형식을 커밋 단계에서 강제
자주 묻는 질문
커밋 메시지에 왜까지 꼭 써야 하나요?
무엇을 바꿨는지는 diff로 확인되지만, "왜 그렇게 했는지"는 코드에 남지 않습니다. 6개월 뒤 그 코드를 건드릴 사람(대개 본인)이 배경을 이해해 실수를 피하도록, 판단의 이유를 body에 남기는 게 가장 값집니다.
Conventional Commits를 꼭 따라야 하나요?
강제는 아니지만 팀 전체가 일관되면 히스토리 검색·리뷰·자동화가 쉬워집니다. 특히 changelog와 버전 자동화를 쓸 계획이면 큰 이점이 있습니다. 작은 개인 프로젝트라도 습관을 들여두면 좋습니다.
커밋은 얼마나 잘게 나눠야 하나요?
"하나의 논리적 변경 = 하나의 커밋"이 원칙입니다. 기능 추가와 리팩터링을 한 커밋에 섞으면 리뷰·되돌리기가 어렵습니다. 각 커밋이 독립적으로 말이 되고 빌드가 깨지지 않도록 나누세요.
댓글 0