개발을 하다 보면 누구나 한 번쯤은 커밋메시지를 급하게, 대충, 형식 없이 작성해본 경험이 있으실 겁니다. 당장은 바빠 보이고, 눈앞의 작업이 더 중요해 보이기 때문입니다. 하지만 시간이 지나고, 팀이 커지고, 코드가 쌓이면서 그 대충 쓴 커밋메시지가 어떤 문제를 만드는지 뼈저리게 느끼게 됩니다. 이 글은 그런 경험을 바탕으로, 우리가 왜 커밋메시지를 신경 써야 하는지 일상적인 이야기와 함께 풀어낸 글입니다.
1. 나중에 나를 괴롭힌 건 코드가 아니라 커밋메시지였습니다
개발을 처음 시작했을 때는 ‘코드만 잘 짜면 된다’고 생각했습니다. 기능이 잘 돌아가고, 에러가 없고, 성능도 괜찮으면 된다고 여겼습니다. 그래서 커밋할 때마다 메시지는 늘 비슷했습니다. “수정”, “버그 픽스”, “기능 추가”, “리팩토링”, 심지어는 “ㅇㅇ” 같은 것도 있었던 기억이 납니다. 당시에는 이게 그렇게 큰 문제라고 느껴지지 않았습니다.
그런데 몇 달 뒤, 과거의 코드를 다시 보게 되면서 상황이 달라졌습니다. 분명 제가 작성한 코드인데, 왜 이렇게 고쳤는지 전혀 기억이 나지 않았습니다. 변경된 라인은 보이는데, ‘왜’ 바꿨는지가 보이지 않았습니다. 그 순간 깨달았습니다. 문제는 코드가 아니라 커밋메시지에 있었다는 것을요.
솔직히 말해서, 코드는 읽으면 어느 정도 이해가 됩니다. 하지만 의도는 코드만으로는 알 수 없는 경우가 많습니다. 특히 예외 처리나 조건 분기, 구조 변경 같은 경우는 당시의 상황과 맥락이 굉장히 중요합니다. 그런데 커밋메시지가 “수정”이라고 되어 있으면, 그 맥락은 완전히 사라져버립니다.
저는 어느 날, 특정 기능에서 이상한 동작이 발견되어 Git 히스토리를 뒤져본 적이 있습니다. 그 기능은 분명 제가 만들었고, 중간에 제가 수정도 했습니다. 그런데 커밋메시지들이 전부 “수정”, “수정2”, “버그”, “fix” 이런 식이었습니다. 결국 코드를 일일이 비교하면서 과거 변경 사항을 역추적해야 했고, 그 과정에 생각보다 많은 시간이 들어갔습니다.
그때 느꼈습니다. 커밋메시지는 남을 위한 게 아니라, 미래의 나를 위한 기록이라는 것을요.
한 번은 팀원이 제게 물었습니다. “이 부분 왜 이렇게 바꾸셨어요?” 저는 바로 대답하지 못했습니다. 코드 작성자는 저인데, 의도를 설명하지 못하는 상황이었습니다. 그때 참 민망했습니다. 커밋메시지가 제대로 적혀 있었다면, 그 질문에 훨씬 빠르게 답할 수 있었을 겁니다.
개발을 오래 할수록, 코드를 작성하는 시간보다 코드를 ‘읽는 시간’이 더 많아집니다. 그런데 커밋메시지가 부실하면, 그 읽는 시간이 몇 배로 늘어납니다. 작은 게 쌓여서 큰 낭비가 되는 구조였습니다.
개인적으로는 이 경험 이후로 커밋메시지를 조금씩 바꾸기 시작했습니다. 처음에는 어색했습니다. 굳이 이렇게 길게 써야 하나 싶기도 했습니다. 하지만 시간이 지나면서 그 효과를 체감하게 되었고, 그때서야 예전에 대충 썼던 커밋메시지들이 얼마나 큰 부담이 되었는지 실감했습니다.
2. 팀에서 더 크게 드러나는 커밋메시지의 중요성
혼자 개발할 때는 그래도 상황이 조금 낫습니다. 기억이라도 어렴풋이 남아 있기 때문입니다. 하지만 팀에서 일하게 되면 커밋메시지의 중요성은 훨씬 커집니다. 특히 협업이 많아질수록, 커밋메시지는 하나의 의사소통 수단이 됩니다.
제가 팀 프로젝트를 진행할 때의 일입니다. 한 팀원이 특정 모듈의 로직을 수정했고, 그 이후 다른 기능에서 문제가 발생했습니다. 원인을 찾기 위해 Git 히스토리를 확인했는데, 커밋메시지는 “로직 수정”이었습니다. 이 한 줄로는 무엇을 어떻게 바꿨는지 전혀 알 수 없었습니다.
결국 그 팀원에게 직접 물어봐야 했습니다. 그런데 그 팀원도 정확히 기억을 못 하고 있었습니다. 시간이 꽤 지난 뒤였기 때문입니다. 이 상황을 겪고 나니, 커밋메시지가 단순한 기록이 아니라 팀 전체의 시간을 좌우한다는 생각이 들었습니다.
사실 커밋메시지는 일종의 문서 역할을 합니다. 별도의 문서를 만들지 않아도, 커밋메시지가 잘 작성되어 있으면 히스토리만으로도 충분한 맥락을 파악할 수 있습니다. 반대로, 커밋메시지가 부실하면 문서를 아무리 잘 만들어도 히스토리 추적이 어렵습니다.
저는 이 경험 이후로, 코드 리뷰를 할 때도 커밋메시지를 유심히 보게 되었습니다. 코드가 아무리 깔끔해도, 커밋메시지가 성의 없으면 뭔가 빠진 느낌이 들었습니다. 개발 과정이 제대로 기록되지 않은 느낌이랄까요.
또 한 가지 느낀 점은, 커밋메시지가 잘 작성된 사람의 코드는 대체로 정리가 잘 되어 있다는 것이었습니다. 이건 우연이 아니었습니다. 커밋메시지를 고민하는 사람은, 변경 단위도 자연스럽게 작게 가져가고, 무엇을 왜 바꾸는지 스스로 정리하면서 작업하기 때문이었습니다.
개인적으로는 커밋메시지를 쓰면서 제 생각도 더 정리되는 느낌을 받았습니다. ‘내가 지금 뭘 하고 있지?’를 스스로에게 묻는 과정이 되었습니다. 그래서 오히려 작업 품질도 좋아졌습니다.
팀원들끼리 이런 이야기를 나눈 적이 있습니다. “커밋메시지 보면 그 사람의 개발 습관이 보인다”는 말이었는데, 그 말이 꽤 공감되었습니다. 단순한 텍스트 한 줄이지만, 그 안에 개발자의 태도가 담겨 있었습니다.
3. 결국 습관의 문제였고, 작은 습관이 큰 차이를 만들었습니다
처음에는 커밋메시지를 제대로 쓰는 게 꽤 귀찮게 느껴졌습니다. 작업이 끝났는데, 또 글을 써야 한다는 느낌이 들었기 때문입니다. 하지만 어느 순간부터 생각이 바뀌었습니다. 이건 추가 작업이 아니라, 개발의 일부라는 생각이 들기 시작했습니다.
그래서 저만의 기준을 만들었습니다. “무엇을 바꿨는가”보다 “왜 바꿨는가”를 쓰자고요. 그 한 줄이 달라지니 커밋메시지의 질이 확연히 달라졌습니다. 예를 들어 “로그인 오류 수정” 대신 “토큰 만료 시 예외 처리 누락으로 인한 로그인 오류 수정”처럼 쓰기 시작했습니다.
이렇게 작성된 커밋메시지는 시간이 지나도 스스로에게 친절했습니다. 과거의 제가, 미래의 저에게 설명해주는 느낌이 들었습니다.
가끔 예전 프로젝트의 Git 로그를 보면, 커밋메시지만 읽어도 흐름이 보이는 경우가 있습니다. 그럴 때마다 묘한 만족감이 듭니다. ‘그래도 내가 제대로 해놓았구나’ 하는 생각이 들기 때문입니다.
저는 요즘 커밋할 때마다 잠깐 멈춥니다. 그리고 스스로에게 묻습니다. “이 커밋메시지를 6개월 뒤에 봐도 이해할 수 있을까?” 이 질문 하나만으로도 커밋메시지의 질이 많이 달라졌습니다.
결국 커밋메시지는 실력의 문제가 아니라 습관의 문제였습니다. 조금만 신경 쓰면 누구나 충분히 잘 작성할 수 있는 부분이었습니다. 그런데 대부분의 사람들이, 저를 포함해서, 그 중요성을 늦게 깨닫는 것뿐이었습니다.
돌이켜보면, 예전에 대충 썼던 커밋메시지들 때문에 꽤 많은 시간을 낭비했습니다. 그 시간을 생각하면, 커밋메시지에 30초 더 투자하는 게 훨씬 이득이라는 걸 이제는 확실히 알겠습니다.
지금도 가끔 급할 때는 유혹이 생깁니다. 그냥 “수정”이라고 쓰고 넘어가고 싶은 마음이요. 하지만 그때마다 예전의 고생이 떠올라서 다시 한 번 생각하게 됩니다. 그리고 결국, 조금 더 구체적으로 쓰게 됩니다.
작은 습관 하나가 개발 생활을 훨씬 편하게 만들어준다는 걸, 저는 커밋메시지를 통해 가장 크게 느꼈습니다.
✅함께 보면 좋은 글✅