좋은 커밋 메시지와 풀 리퀘스트(Pull Request)를 작성하는 방법 — 팀 가이드

이 글은 명확성, 일관성, 그리고 실제 사례에 초점을 맞춘 실용적이고 구조적인 게시물입니다.
명확한 커밋 메시지와 풀 리퀘스트(Pull Request)는 단순히 "있으면 좋은 것"이 아닙니다. 이는 팀이 얼마나 빠르게 리뷰하고, 디버깅(Debug)하며, 배포(Ship)할 수 있는지에 직접적인 영향을 미칩니다. 잘 작성된 메시지는 버전 히스토리(Version history)를 문서화(Documentation)로 바꿔주지만, 잘못 작성된 메시지는 마찰과 혼란을 야기합니다.

이것이 중요한 이유

좋은 커밋 히스토리(Commit history)는 다음 세 가지 질문에 빠르게 답합니다:

• 무엇이 변경되었는가?
• 왜 변경되었는가?
• 나머지 작업과 어떤 관련이 있는가?

강력한 풀 리퀘스트(Pull Request, PR)는 다음을 답합니다:

• 어떤 문제를 해결하고 있는가?
• 어떻게 해결했는가?
• 리뷰어(Reviewer)가 어디에 집중해야 하는가?

팀원들이 당신에게 묻지 않고도 이 질문들에 답할 수 있다면, 당신은 제대로 하고 있는 것입니다.

명확한 커밋 메시지 작성하기

일관된 구조 사용하기

널리 채택되는 형식은 Conventional Commits입니다:

• <type>(optional-scope): short summary

일반적인 타입(Type):

• feat: 새로운 기능 (New feature)
• fix: 버그 수정 (Bug fix)
• refactor: 동작 변경 없는 코드 수정 (Code change without behavior change)
• chore: 유지보수 (deps, configs)
• docs: 문서 (Documentation)
• test: 테스트 (Tests)

예시:

• feat(auth): add password reset via email

요약(Summary)은 간결하게 유지하기

• 현재 시제를 사용하세요: “added”가 아닌 “add"
• 약 72자 이내로 유지하세요
• 어떻게(How)가 아닌 무엇(What)에 집중하세요

나쁜 예:

• fixed stuff

좋은 예:

• fix(cart): prevent duplicate items on rapid click

서술적인 커밋 본문(Body) 작성하기

변경 사항이 명확하지 않을 때는 본문(Body)을 사용하세요.

구조:

• 왜 변경이 필요했는지
• 어떤 접근 방식이 취해졌는지
• 어떠한 트레이드오프(Trade-offs)나 엣지 케이스(Edge cases)가 있는지

예시:

fix(cart): prevent duplicate items on rapid click

Users could add the same item multiple times by clicking quickly
...

커밋을 이슈(Issue)에 연결하기

가능할 때마다 항상 작업을 티켓(Ticket)이나 이슈(Issue)에 연결하세요.

• Closes #142
• Fixes PROJ-87

예시:

feat(search): add fuzzy matching for product names

Improves search results when users misspell product names.
...

이는 코드와 의도(intent) 사이의 추적 가능성(traceability)을 생성합니다.

커밋 전략: squash vs merge vs rebase

Squash and merge

가장 적합한 경우:

• 깔끔한 히스토리 (Clean history)
• 작은 커밋이 많은 기능 브랜치 (Feature branches)

결과:

• PR당 하나의 커밋 생성

장점:

• 읽기 쉬운 히스토리
• 노이즈(noise) 감소

단점:

• 세부적인 커밋 내역(granular commit detail) 손실

Merge commits

가장 적합한 경우:

• 전체 개발 맥락(development context) 보존

결과:

• 모든 커밋 + 머지 커밋(merge commit) 유지

장점:

• 완전한 추적 가능성
• 복잡한 기능 구현 시 유용

단점:

• 히스토리가 지저분해짐 (noisy)

Rebase and merge

가장 적합한 경우:

• 머지 커밋 없는 선형 히스토리 (Linear history)

장점:

• 깔끔하고 읽기 쉬운 히스토리
• 개별 커밋 유지

단점:

• 깨끗한 커밋 위생(commit hygiene) 요구
• 오용할 경우 히스토리를 재작성(rewrite)할 수 있음

실무 권장 사항

• 대부분의 기능 PR에는 squash를 사용하세요.
• 수명이 길거나 복잡한 브랜치에는 merge commits를 사용하세요.
• 엄격한 커밋 규율(commit discipline)에 익숙한 팀은 rebase를 사용하세요.

풀 리퀘스트(Pull Request) 설명 작성하기

좋은 PR 설명은 리뷰어의 추측을 제거해 줍니다.

핵심 구조

다음 내용을 포함하세요:

• 무엇을 (What): 변경 사항에 대한 간략한 요약
• 왜 (Why): 해결하려는 문제
• 어떻게 (How): 주요 구현 세부 사항
• 범위 (Scope): 포함된 사항과 포함되지 않은 사항

예시:

### What
이메일을 통한 비밀번호 재설정 기능 추가.

...

스크린샷 및 시각 자료 사용

PR이 UI에 영향을 미치는 경우, 전/후 시각 자료를 포함하세요.

• 정적 UI를 위한 스크린샷
• 상호작용(interactions)을 위한 GIF
• 흐름(flows)을 위한 짧은 영상

예시 노트:

• “이전: 에러 메시지가 보이지 않음”
• “이후: 입력창 아래에 인라인 검증(inline validation) 표시됨”

이는 리뷰어의 노력을 극적으로 줄여줍니다.

테스트 노트 포함

리뷰어에게 변경 사항을 검증하는 방법을 정확히 알려주세요.

예시:

### Testing
1. /login 페이지로 이동
2. "비밀번호 찾기" 클릭
...

이는 일관된 검증을 보장하고 승인 속도를 높여줍니다.

리뷰 체크리스트 추가

리뷰어가 중요한 것에 집중할 수 있도록 도와주세요.

예시:

### Review checklist
- 로직의 정확성
- 예외 케이스(Edge cases) 처리 여부
...

규모가 큰 PR(Pull Request)의 경우 선택 사항이지만 도움이 됩니다.

PR 리뷰를 더 쉽게 만들기

PR을 작게 유지하기

• 가능하면 ~400라인 미만을 목표로 하세요.
• 큰 기능은 더 작은 PR로 나누세요.

관심사 분리 (Separate concerns)

다음 사항들을 섞지 마세요:

• 기능 로직 (Feature logic)
• 리팩터링 (Refactoring)
• 포맷팅 변경 (Formatting changes)

PR 내부에서 의미 있는 커밋 사용하기

나중에 스쿼시(Squashing)를 하더라도, 깔끔한 커밋은 리뷰어가 흐름을 따라가는 데 도움이 됩니다.

실제 사례

약한 커밋 + PR

커밋:

• update stuff

PR:

• “우리가 이야기했던 기능을 추가합니다.”

문제점:

• 컨텍스트(Context) 없음
• 추적 가능성(Traceability) 없음
• 리뷰어를 위한 가이드 없음

강력한 커밋 + PR

커밋:

• feat(profile): allow users to upload avatar images

PR:

### 무엇을 (What)
사용자 프로필에 아바타 업로드 기능을 추가합니다.

...

결과:

• 리뷰어가 질문 없이 모든 것을 이해함
• 더 빠른 승인 (Approval)
• 더 나은 장기적 문서화 (Documentation)

최종 원칙

금요일 오후 5시에 당신의 코드를 리뷰하는 사람, 또는 6개월 뒤의 당신 자신을 위해 작성하세요. 만약 그들이 별도의 조사 없이도 당신의 작업을 이해할 수 있다면, 당신은 잘 해낸 것입니다.

이 내용을 팀 체크리스트나 재사용 가능한 PR 템플릿으로 변형해 드릴까요?

Rizwan Saleem — https://rizwansaleem.co