커밋 메시지는 무엇을 남겨야 하는가 — 나중에 읽는 사람이 자신일 때

독자는 6개월 뒤의 자신

커밋 메시지를 쓸 때 "지금 무엇을 했는지"만 적으면 대개 코드에 이미 적혀 있는 내용이 된다.

```

• 함수 수정
• 버그 픽스
• 코드 정리

```

이런 메시지는 git log를 볼 때 아무것도 알려주지 않는다. 정작 필요한 순간은 6개월 뒤 이 줄이 왜 이렇게 됐는지 추적할 때이고, 그때 필요한 것은 "무엇을"이 아니라 "왜" 다.

최소 형식

제목 한 줄이면 충분한 경우가 많다. 대신 다음을 담는다.

```

<범위>: <무엇이 어떻게 달라지는가>

```

예:

```

로그인: 세션 만료 시 갱신 시도 후 재시도

파서: 빈 배열 입력에서 예외 대신 빈 결과 반환

```

동작의 변화가 드러나야 한다. "수정"이 아니라 "무엇이 어떻게 달라지는가"다.

본문이 필요한 경우

제목으로 부족한 상황이 있다. 이때 본문에 쓸 것은 배경과 이유다.

```

캐시: 조회 결과를 요청 단위로만 유지

전역 캐시를 쓰면 배포 직후 이전 버전 응답이 섞여 나온다.

요청 단위로 줄이면 중복 조회 제거 이득은 유지하면서

버전 간 오염이 사라진다. 성능 손실은 요청당 1회 조회 수준.

```

• 왜 이 변경이 필요했는가
• 어떤 대안을 고려했고 왜 택하지 않았는가
• 알려진 한계는 무엇인가

코드 리뷰에서 나온 논의를 여기 남겨두면 나중에 같은 논의를 반복하지 않는다.

커밋 단위

메시지보다 앞서는 문제다. 한 커밋에 하나의 논리 변경.

섞으면 안 되는 조합:

• 기능 추가 + 포매팅 변경 → diff에서 실제 변경이 묻힌다
• 버그 수정 + 리팩터링 → 되돌릴 때 둘 다 되돌아간다
• 여러 무관한 수정 → 원인 추적이 불가능해진다

작업하다 보면 섞이기 마련이므로, 커밋 전에 나누는 습관이 필요하다.

```bash

git add -p # 변경 조각 단위로 선택

```

접두어를 쓸 것인가

컨벤셔널 커밋 형식(feat:, fix:, chore: 등)은 자동 릴리스 노트 생성 도구를 쓸 때 실익이 크다. 쓰지 않는다면 필수는 아니다.

다만 접두어가 있으면 git log --oneline에서 훑기 쉬워지는 이득은 남는다. 최소한으로 쓴다면:

• feat 기능 추가
• fix 버그 수정
• refactor 동작 변화 없는 구조 변경
• docs 문서
• chore 빌드·설정

동작이 바뀌는가(feat/fix)와 안 바뀌는가(refactor)를 구분하는 것만으로도 히스토리 가독성이 크게 달라진다.

확인 방법

지금 저장소의 히스토리를 훑어본다.

```bash

git log --oneline -30

```

읽으면서 "이건 무슨 변경이었지?"가 생기는 줄이 절반을 넘으면, 메시지가 제 역할을 못 하고 있는 것이다. 과거를 고칠 필요는 없고, 다음 커밋부터 바꾸면 된다.

최종 수정 2026-08-28