개발을 하다 보면 과거의 내가 짠 코드를 보며 “도대체 왜 이렇게 짰지?” 라고 생각할 때가 있다.

코드는 그나마 주석이라도 있지만, git log를 열었을 때 fix, update, aaa 같은 커밋 메시지만 가득하다면?

나중에 로그를 봐도 어떤걸 수정했는지 전혀 알 수 없을거다.

좋은 커밋 메시지는 ‘과거의 나’와 ‘미래의 동료’에게 보내는 편지와 같다. 잘 작성된 메시지는 코드 리뷰 시간을 단축시키고, 나중에 치명적인 버그를 추적할 때 결정적인 단서가 된다.

오늘은 개발자들 사이에서 가장 널리 쓰이는 ‘Conventional Commits’ 규칙과 작성 팁을 정리했다.

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

커밋 메시지는 크게 제목(Subject), 본문(Body), 꼬리말(Footer) 세 부분으로 나뉜다.

type(scope): subject  <-- 제목 (필수)

body                  <-- 본문 (선택, 제목과 한 줄 띄움)

footer                <-- 꼬리말 (선택, 이슈 트래킹 ID 등)

2. 제목(Header) 작성 규칙 Type

제목은 보통 태그: 설명 형식으로 쓴다. 이때 사용하는 태그(Type)는 아래와 같이 구분하여 사용하는 것이 일반적이다.

태그 (Type) 설명 예시
feat 새로운 기능 추가 feat: 로그인 API 구현
fix 버그 수정 fix: 무한 스크롤 로딩 에러 수정
docs 문서 수정 (README 등) docs: API 문서 업데이트
style 코드 포맷팅 (로직 변경 없음) style: 세미콜론 누락 수정
refactor 리팩토링 (기능 변경 없이 코드 구조 개선) refactor: 유저 모델 클래스 분리
test 테스트 코드 추가/수정 test: 로그인 실패 테스트 케이스 추가
chore 빌드 업무 수정, 패키지 매니저 설정 등 chore: 패키지 버전 업그레이드

💡 제목 작성 Tip

  • 50자 이내로 간결하게 작성한다.
  • 끝에 마침표(.)를 찍지 않는다.
  • 명령문/청유형으로 작성한다.
  • 영어: “Added” 대신 “Add”, “Fixed” 대신 “Fix”
  • 한글: “~했음”보다 “~수정”, “~추가” 등의 명사형 어미 사용

3. 본문(Body) 작성 규칙: Why & How

단순한 수정이라면 제목만으로 충분하지만, 복잡한 로직 변경이나 팀원들에게 설명이 필요한 경우 본문을 작성한다.

무엇을(What) 변경했는지보다 왜(Why) 변경했는지를 적는 것이 핵심이다.

어떻게(How) 해결했는지, 특별한 알고리즘이나 라이브러리를 사용했다면 언급한다.

💡 Tip

터미널에서 git commit -m “메시지” 대신 git commit만 입력하면 텍스트 에디터가 열려 여러 줄을 편하게 쓸 수 있다.

4. 좋은 예시 vs 나쁜 예시

❌ 나쁜 예시 (Bad)

이런 커밋 메시지는 피해야 한다. 나중에 히스토리를 봐도 아무런 정보를 얻을 수 없기 때문이다.

bug fix (어떤 버그..?)

update code (너무 포괄적임)

aaaaa (뭘 했는지 전혀 알 수 없음)

로그인 수정 (무엇을 어떻게 수정했는지 모름)

✅ 좋은 예시 (Good)

[한글 작성 예시]

feat: 소셜 로그인(구글, 카카오) 기능 추가

- OAuth 2.0 기반 인증 로직 구현
- 사용자 정보 DB 저장 로직 추가
- 기존 일반 로그인과 계정 연동 처리 로직 개선

Resolves: #123

[영어 작성 예시]

fix(auth): handle expired token error correctly

- Update interceptor to refresh token on 401 error
- Redirect to login page if refresh fails

Fixes #45

5. 핵심 원칙 3가지

마지막으로 커밋 메시지를 잘 쓰기 위한 3가지 원칙을 되새겨 보자.

- Atomic Commit (단위 쪼개기): 하나의 커밋에는 하나의 변경 사항만 담는다.
    feat: 로그인 기능 및 게시판 수정처럼 여러 기능을 섞지 말자. 나중에 롤백하기 힘들어진다.

- 팀 규칙 준수: 회사나 팀마다 규칙(Jira 티켓 번호 붙이기 등)이 다를 수 있다. 팀의 컨벤션이 언제나 최우선이다.

- 구체적으로: '수정함'보다는 '00함수의 리턴 타입 수정'처럼 구체적으로 명시한다.

커밋메세지는 항상 귀찮다. 하지만 깔끔하게 정리된 커밋 로그가 언젠가는 감사해지는 날이 올거라고 생각한다.

앞으로는 귀찮더라도 잘 작성해보자!