좋은 커밋 메시지 쓰는 법 & 협업 매너 (Git 컨벤션 실전 정리)

3개월 전 코드에서 버그가 터졌습니다. git log를 열어보니 '수정', '버그픽스', 'ㅇㅇ', 'asdf'... 무엇을 왜 바꿨는지 도무지 알 수 없습니다. 커밋 메시지는 미래의 나와 동료에게 보내는 편지입니다. 잘 쓰면 디버깅·협업 시간이 극적으로 줄어듭니다.

1. 커밋 메시지의 기본 구조

널리 쓰이는 형식은 타입: 요약 + (필요시) 본문입니다.

[나쁜 예]
수정함
버그 픽스
update code

[좋은 예]
fix: 로그인 시 토큰 만료 처리 누락 버그 수정

- 401 응답 시 자동 로그아웃되지 않던 문제 해결
- 만료 토큰으로 API 호출 시 무한 로딩 발생
- 관련 이슈: #142

요약은 50자 이내, 명령형('수정함'❌ → '수정'⭕), 끝에 마침표 없이가 관례입니다.

2. 타입 컨벤션을 팀과 통일하라

널리 쓰이는 Conventional Commits 타입입니다. 메시지만 봐도 변경 성격이 보입니다.

타입	용도	예시
feat	새 기능	feat: 다크모드 토글 추가
fix	버그 수정	fix: 결제 중복 호출 방지
refactor	기능 변화 없는 구조 개선	refactor: API 모듈 분리
docs	문서	docs: README 설치 가이드 보완
test	테스트	test: 로그인 케이스 추가
chore	빌드·설정	chore: eslint 규칙 업데이트

3. '무엇'보다 '왜'를 남겨라

코드를 보면 '무엇이' 바뀌었는지는 압니다. 메시지로 남길 가치가 있는 건 '왜' 바꿨는가입니다.

나쁜 본문: "setTimeout을 100ms로 변경" 좋은 본문: "렌더링 전에 DOM이 준비되지 않아 깜빡임이 생겨, 다음 프레임까지 100ms 지연 추가"

6개월 뒤 "이 100ms는 대체 왜 있지?" 하고 지웠다가 버그가 부활하는 사고를 막아줍니다.

4. 커밋·브랜치 협업 매너

• 하나의 커밋엔 하나의 논리적 변경만 (기능+오타수정 섞지 않기)
• 의미 단위로 자주 커밋, 거대한 '몰아 커밋' 금지
• 브랜치명도 컨벤션: feat/login-oauth, fix/payment-bug
• main에 직접 push 금지, PR을 통해 머지
• 남의 작업 위에 강제 push(--force)는 사전 합의 없이는 금지

마무리 체크리스트

• 요약이 50자 이내·명령형인가
• **타입(feat/fix...)**을 붙였는가
• 본문에 **'왜'**가 적혀 있는가
• 한 커밋에 하나의 변경만 담았는가
• 브랜치명·PR 규칙을 지켰는가

좋은 커밋 메시지는 비용이 아니라 투자입니다. 30초 더 쓰면, 미래의 누군가가 30분을 아낍니다. 다음 커밋부터 타입: 요약 한 줄만이라도 지켜보세요.