결론부터 말하자면, 커밋 메시지 작성 방식에도 절대적인 ‘하나의 정답’은 없다.
팀의 규모, 프로젝트의 성격, 그리고 개발 문화에 따라 선호하는 스타일은 매번 달라지기 때문이다.
하지만 분명한 것은, 규칙(Convention) 없이 작성된 커밋 히스토리는 개발자가 늘어날수록 거대한 기술 부채(Tech Debt)로 돌아온다는 사실이다.

이번 글에서는 많은 오픈소스와 글로벌 기업에서 표준처럼 사용하는 Git 커밋 컨벤션(Conventional Commits)의 대표적인 타입들과 그 구체적인 활용법을 정리해 보고자 한다.

Git 커밋 컨벤션이 필요한 진짜 이유

맹목적으로 “남들이 다 쓰니까 나도 쓴다”는 식의 접근은 오래가지 못한다.
커밋 메시지에 머리말(Prefix)을 붙여 형식을 맞추는 본질적인 이유는 다음과 같다.

히스토리 추적의 효율성: git log를 확인했을 때, 어떤 커밋이 새로운 기능을 포함하고 있고 어떤 커밋이 버그를 고쳤는지 1초 만에 파악할 수 있다.
코드 리뷰의 편의성: 풀 리퀘스트(PR)를 검토할 때, 커밋 메시지만 보고도 변경 사항의 성격(단순 문서 수정인지, 위험도가 높은 기능 추가인지)을 미리 짐작하여 리뷰의 완급을 조절할 수 있다.
자동화 도구와의 연계: 잘 정돈된 커밋 타입을 기반으로, 다음 버전 배포 시 ‘업데이트 내역(Changelog)’을 자동으로 생성해 주는 CI/CD 툴을 매끄럽게 도입할 수 있다.

대표적인 커밋 타입(Type)과 상황별 활용법

커밋 메시지는 보통 타입(Type): 본문(Subject)의 형태를 취한다.
이때 접두어로 들어가는 주요 타입들을 정확한 사용 시기와 예시와 함께 살펴보자.

feat: 새로운 기능 추가

사용 시기: 시스템에 새로운 기능(Feature)을 구현하여 코드가 추가되거나 기능적 변경이 일어났을 때 사용한다.
예시
- feat: 회원가입 시 이메일 중복 확인 기능 추가
- feat: 주문 상세 엔티티 수정 및 DTO 작성

fix: 버그 수정

사용 시기: 기존 코드에 존재하던 에러나 오류, 잘못된 비즈니스 로직을 바로잡았을 때 사용한다.
예시
- fix: 로그인 시 패스워드 불일치 예외 처리 오류 수정
- fix: 결제 취소 시 포인트 환불이 누락되던 버그 수정

docs: 문서 수정

사용 시기: 프로덕션 코드는 손대지 않고, README.md, API 명세서, 위키 등 개발 및 프로젝트 문서만 생성하거나 수정했을 때 사용한다.
예시
- docs: 프로젝트 설치 및 로컬 실행 가이드 업데이트
- docs: Swagger API 문서에 회원 관리 도메인 설명 추가

style: 코드 포맷팅 및 스타일 변경

사용 시기: 코드의 비즈니스 로직이나 기능에는 아무런 영향이 없는 단순 포맷팅 작업을 했을 때 사용한다. 세미콜론 누락 수정, 인덴트(들여쓰기) 정렬, 공백 제거, 혹은 Prettier/Linter 툴 적용 등이 해당된다. (변수명 변경 등은 refactor에 가깝다.)
예시:
- style: 자바 코딩 컨벤션에 맞춰 줄바꿈 및 들여쓰기 교정
- style: 코드 가독성 향상을 위한 불필요한 공백 제거

refactor: 코드 리팩토링

사용 시기: 새로운 기능을 추가하지도 않고, 그렇다고 버그를 고친 것도 아니지만, 기존 코드의 구조를 개선하여 가독성을 높이거나 유지보수성을 향상시켰을 때 사용한다.
예시
- refactor: 중복된 유저 검증 로직을 별도 도메인 서비스로 분리
- refactor: 컨트롤러의 무거운 비즈니스 로직을 서비스 레이어로 이관

chore: 빌드 업무 및 설정 파일 수정

사용 시기: 프로덕션 코드나 테스트 코드와는 직접적인 상관이 없는 사소한 설정 변경, 빌드 스크립트 수정, 의존성 패키지 관리(.gitignore 설정, build.gradle 라이브러리 추가 등) 시 사용한다.
예시
- chore: .gitignore에 인텔리제이 설정 파일(.idea) 제외 항목 추가
- chore: Spring Boot Security 의존성 라이브러리 추가

test: 테스트 코드 작성 및 수정

사용 시기: 테스트 코드를 새로 추가하거나 기존 테스트 코드를 보완, 삭제할 때 사용한다. 당연히 프로덕션 코드의 변경이 없어야 한다.
예시
- test: 유저 회원가입 서비스 레이어 단위 테스트 추가
- test: 기존 주문 생성 통합 테스트의 엣지 케이스 보완

perf: 성능 개선

사용 시기: 사용자나 시스템 관점에서 명확한 성능(Performance) 향상을 가져오는 코드 수정을 진행했을 때 사용한다.
예시
- perf: 메인 인덱스 페이지 조회 쿼리 튜닝 및 캐시 도입으로 속도 개선

ci / build: CI 설정 및 빌드 시스템 변경

사용 시기: GitHub Actions, Jenkins 같은 CI 구성 파일 수정을 의미하는 ci 타입이나, Gradle/Maven 등 빌드 시스템 자체의 변화를 다루는 build 타입도 팀에 따라 세분화하여 사용한다.
예시
- ci: GitHub Actions 배포 워크플로우 트리거 조건 변경
- build: 자바 버전을 17에서 21로 업그레이드

revert: 이전 커밋 되돌리기

사용 시기: 프로덕션 배포나 머지 이후 문제가 발생하여 특정 커밋의 변경 사항을 완전히 취소하고 이전 상태로 되돌려야 할 때 사용한다.
예시
- revert: “feat: 장바구니 기능 추가” 커밋 변경 사항 되돌림

좋은 커밋 메시지를 쓰기 위한 5가지 원칙

타입을 잘 나누는 것만큼 제목과 본문을 건강하게 작성하는 것도 중요하다.
전 세계적으로 통용되는 몇 가지 룰을 요약하면 다음과 같다.

제목은 50자 이내로 간결하게: 핵심 요약은 명확하고 짧을수록 가독성이 좋다.
제목 끝에 마침표(.) 찍지 않기: 마침표는 불필요한 노이즈다.
영문 작성 시 첫 글자는 대문자로, 명령형으로 시작하기: 한글인 경우 ‘ ~~추가’, ‘~~ 수정’과 같은 명사형 종결로 통일하는 것이 깔끔하다.
본문은 ‘어떻게(How)’보다 ‘왜(Why)’와 ‘무엇을(What)’ 중심으로: 코드는 어떻게 수정되었는지 이미 보여준다. 커밋 메시지에는 이 수정을 왜 해야만 했는지 배경을 담는 것이 가치 있다.
이슈 번호 활용하기: Jira나 GitHub Issue를 사용한다면 푸터(Footer)나 제목에 #123 형태로 연동해 두면 히스토리 추적이 극대화된다.

결국 본질은 ‘협업과 커뮤니케이션’이다

아무리 정교하고 훌륭한 커밋 컨벤션이라도 팀원들이 공감하지 못하고 억지로 지키는 템플릿은 금방 무너지거나 오염된다.
소규모 토이 프로젝트에 10가지가 넘는 타입을 억지로 구별해 쓰는 것은 오히려 생산성을 갉아먹는 오버 엔지니어링이 될 수 있고, 반대로 거대한 엔터프라이즈 시스템에서 아무런 규칙 없이 커밋을 던지는 것은 재앙을 부르는 지름길이다.

내가 속한 팀의 규모, 프로젝트의 진행 단계, 그리고 팀원들의 숙련도까지 종합적으로 고려하여 ‘우리 팀이 소통 비용을 가장 최소화할 수 있는 최적의 컨벤션 수준’을 맞추는 것.

그 유연한 합의와 소통의 과정이야말로 진정한 코드 퀄리티의 시작이자 좋은 개발자로 성장하는 밑거름이 될 것이다.

0 글이 마음에 드시면 하트를 눌러주세요! 행복한 고민이 됩니다!

Git 커밋 컨벤션

커밋 메시지에 정답은 없다?

협업의 시작점, 커밋 메시지