커밋, 브랜치, Issue, 그리고 코드 리뷰
아직 앱 개발이 완전히 끝난 것은 아니지만,
지금 시점에서 이번 프로젝트의 협업 방식에 대해 한 번 정리해보고 싶었다.
이번 개발을 진행하면서 단순히 기능을 구현하는 것 이상으로,
“어떻게 함께 개발할 것인가”가 코드 품질과 유지보수성에 얼마나 큰 영향을 주는지 체감했다.
✅ 커밋 컨벤션: 기록은 남기되, 읽히게
프로젝트 초반에는 최소한의 커밋 컨벤션만 지켰다.
fix: controller 같은 형식은 사용했지만,
커밋 단위에 대한 기준은 명확하지 않았다.
그 결과 하나의 커밋에 너무 많은 변경 사항이 들어갔고,
나중에 커밋 히스토리를 다시 보면
“이 코드는 언제, 왜 바뀐 거지?”라는 질문에 바로 답하기 어려웠다.
그래서 팀원들과 합의한 목표는 단순했다.
커밋 히스토리만 봐도
이 코드가 어디가, 왜, 어떤 의도로 바뀌었는지 알 수 있도록 하자.
이를 위해 커밋을 의미 단위로 나누고,
main 브랜치는 깨끗하게 유지하기 위해 squash & merge 방식을 사용했다.
- 개별 커밋: 세부 변경 사항과 맥락을 자세히 남기고
- squash 커밋: 하나의 기능이나 변경을 대표하는 메시지로 정리
덕분에 main 브랜치는 보기 좋은 히스토리를 유지하면서도,
필요하면 PR 내부 커밋을 통해 세부 흐름을 추적할 수 있게 되었다.
✅ 브랜치 전략: 사람 단위에서 기능 단위로
이전 개발에서는 팀원 각자 이름으로 브랜치를 만들어 작업했고,
작업이 끝나면 main에 바로 반영하는 방식이었다.
하지만 리팩토링과 신규 기능이 동시에 늘어나면서
어떤 변경이 어떤 기능에 속하는지 파악하기가 점점 어려워졌다.
이번 프로젝트에서는 Git Flow 기반 브랜치 전략을 도입했다.
- 브랜치는 기능 단위
- 네이밍: feature/{issue-number}-{description}
- 브랜치 하나당 PR 하나
처음에는 기능 단위 브랜치가 번거롭게 느껴졌지만,
막상 사용해보니 장점이 더 컸다.
- 기능별 히스토리가 서로 섞이지 않고
- dev 브랜치 기준으로 개발 진행 상황이 명확해졌으며
- PR 리뷰 시 변경 범위가 깔끔하게 보였다
✅ PR 템플릿: 코드를 보기 전에 맥락을 공유하다
이전에는 PR을 각자 자유롭게 작성했다.
그러다 보니 리뷰어가 코드를 먼저 읽고 맥락을 유추해야 하는 상황이 자주 발생했다.
이를 개선하기 위해 PR 템플릿을 도입했다.
- 관련 Issue
- 변경 배경(What / Why)
- 핵심 변경 사항
- 테스트 체크리스트
이 템플릿 덕분에
리뷰어는 “왜 이 코드가 필요한지”를 먼저 이해한 상태에서 리뷰할 수 있었고,
작성자 입장에서도 변경 의도를 스스로 정리하는 계기가 되었다.
## 🔗 Related Issue
- #123
## 📝 Description
> 무엇을(What), 왜(Why) 변경했는지 설명합니다.
### 기획 배경 및 비즈니스 문제
- 예: 기존 결제 시스템에서 특정 카드사의 할부 승인이 거절되는 문제를 해결하기 위해 로직을 수정했습니다.
## 🛠 Changes
> 핵심 변경 사항을 요약합니다.
- **API 변경**: `POST /api/v1/payments` 엔드포인트에 `installment_month` 파라미터 추가
- **DB 스키마**: `orders` 테이블에 `promotion_code` 컬럼 추가
## ✅ Test Checklist
> 변경 사항이 정상적으로 동작하는지 확인하기 위해 수행한 테스트 목록입니다.
- [ ] 단위 테스트(Unit Test)를 작성하고 통과했나요?
- [ ] 관련 API 응답 결과가 기획서와 일치하는지 확인했나요?✅ Issue: 의사결정을 남기는 가장 좋은 방법
이번 프로젝트에서 가장 만족스러웠던 변화 중 하나는
GitHub Issue를 적극적으로 활용하게 된 점이다.
이전에는 회의에서 결정된 내용이 시간이 지나면 흐려지거나,
왜 이런 선택을 했는지 기억이 나지 않는 경우가 많았다.
Issue를 도입한 이후에는 다음과 같은 흐름으로 개발을 진행했다.
- 회의 후 Issue 발행
- 유형 선택: docs / feature / fix / refactor
- 왜(Why), 무엇을(What), 어떻게(How) 변경할지 명시
- Issue 기반 브랜치 생성
- PR과 Issue 연동
- 코드 리뷰 → 수정 → squash & merge
이 방식의 가장 큰 장점은
의사결정의 맥락이 기록으로 남는다는 점이었다.
장기 개발을 하다 보면
“왜 이 코드를 이렇게 작성했지?”라는 질문을 다시 마주하게 되는데,
그럴 때 관련 Issue를 찾아보면 당시의 고민과 결정을 다시 확인할 수 있었다.
실제로 테스트 코드를 작성하면서
DTO에 @Valid 검증이 있고 서비스 계층에 검증 로직이 분리된 이유를
이전 Issue와 PR을 통해 파악한 경험이 있다.
당시 “모든 검증 로직은 서비스에서 처리한다”는 의사결정을 확인했고,
이를 바탕으로 검증 로직을 정리하는 리팩토링을 진행했다.
✅ 가장 잘 도입했다고 느낀 것: 코드 리뷰 ⭐
여러 협업 방식 중에서
가장 잘 도입했다고 느낀 것은 단연 코드 리뷰였다.
Issue와 PR을 통해 충분히 고민했다고 생각한 코드도,
리뷰 과정에서는 항상 놓친 부분이 발견되었다.
- 리팩토링이 덜 된 코드
- 불필요한 의존성
- 예외 처리 누락
- 코드 스타일의 미묘한 불일치
이번 개발 기간에는 리팩토링 비중이 컸기 때문에,
코드 리뷰가 없었다면 그대로 main에 들어갔을 생각을 하면 아찔하다.
이 과정에서 발견한 세부적인 실수들과 트러블 슈팅 경험은
별도로 Backend / Trouble Shooting 카테고리에 정리해두었다.
https://wlals916.tistory.com/category/Backend/Trouble%20Shooting
중간 회고를 정리하면서 느낀 점은 하나다.
협업 규칙은 개발 속도를 늦추기 위한 장치가 아니라,
나중의 나와 팀원을 위한 투자라는 것.
프로젝트가 끝난 뒤, 이 글을 다시 읽으면서
“그래도 이때는 제대로 고민하면서 개발했구나”라고 말할 수 있기를 바란다.