[Git] 단 한 줄 커밋에서 벗어나, 명확한 커밋 메시지 구조로 기록하기

| 서론

우아한테크코스 8기 프리코스를 하면서, 코드 변경 사항이 발생했을 때 commit을 남기며 문득 그런 생각이 들었는데요?

"이 커밋이 무엇을 바꾸었고, 왜 바꾸었는지를 기록하고 싶은데, 이걸 커밋명으로만 하기엔 한계가 있는걸,,"

커밋의 Title과 Body가 구분된다는 것은 알았지만, 제대로 해본 적은 없었던 찰나, 이번 기회에 이러한 필요성을 느끼며, 커밋 방식을 한 단계 개선해 보기로 하였습니다.

| 기존 방식의 한계

기존에는 다음과 같은 단순한 절차로 커밋을 작성하였습니다.

git add .
git commit -m "커밋명"
git push

이 방식의 문제는, 커밋 메시지가 한 줄로만 작성되어, 다음과 같은 정보를 한눈에 파악하기 어렵다는 점이었습니다.

• 어떤 파일이 수정되었는지

• 왜 수정했는지

• 수정의 목적이 단순한 버그 수정인지, 리팩토링인지, 기능 추가인지

결과적으로 커밋 로그만으로는 변경 의도나 작업 범위를 명확하게 이해하기 어려웠습니다.

이러한 방식은 시간이 지난 뒤에 커밋 변경 사항을 다시 볼 때면,
“이 부분은 왜 수정했더라?”와 같은 상황을 자주 만들곤 했습니다.

| 개선된 방식

개선된 방식에서는 명확한 커밋 구조와 메시지 가이드라인을 도입하였습니다.

커밋을 단순한 저장이 아닌 명시적 기록의 형태로 남기기 위해 아래와 같은 절차를 적용하였습니다.

git add .
git commit
# 에디터가 열린 뒤에는 'i' 키를 눌러 작성 모드로 들어갑니다.
# 이후 Title과 Body를 구분하여 작성합니다.
# 작성을 완료한 이후에는 'Esc' 키를 누른 뒤 ':wq'를 입력하여 저장합니다.
git push

• Title (제목) : 변경의 핵심을 한 줄로 요약예: fix: correct typos and remove duplicate code

• Body (본문) : 변경된 주요 내용, 원인, 추가 설명 등을 구체적으로 작성

| 실제 적용 예시

feat: implement daily mission progress component in Day5 page

1) DailyProgress 컴포넌트 추가 (src/components/Day5/DailyProgress.jsx)
: 사용자가 Day5에서 오늘의 미션 진행 상황을 시각적으로 확인할 수 있도록 Progress Bar UI를 구현했습니다.

2) missionCompletion API 연동 (src/api/mission.js)
: 미션 완료 데이터를 백엔드와 실시간으로 동기화하도록 Axios 요청 로직을 추가했습니다.

3) 반응형 디자인 적용
: 모바일 환경에서 Progress Bar의 너비와 폰트 크기를 동적으로 조정하도록 CSS 개선을 진행했습니다.

이와 같이 각 항목을 구체적으로 기록함으로써 “무엇을, 왜” 수정했는지가 명확하게 드러나게 되었습니다.

또한, 이러한 개선 포인트를 통해 기대되는 점을 정리해보았는데요?

| 결론

이번 커밋 방식 개선은 단순히 “형식을 맞춘다”는 수준을 넘어, 개발자 간의 커뮤니케이션 품질을 높이는 문화적 변화이지 않을까 기대하는 바램이 있었습니다.

좋은 커밋 메시지는 단순한 로그가 아니라, 개발자의 사고 과정과 코드의 역사를 기록하는 일종의 “문서”라고 생각합니다.

앞으로도 커밋을 작성할 때마다 “이 변경은 무엇을, 왜, 어떻게 바꾸었는가?” 라는 질문을 스스로에게 던지며 작성한다면, 코드 품질은 물론 협업 효율 또한 더욱 향상될 것이라고 확신합니다.