0004. PR 본문을 의사결정 문서로 만들고, 리뷰 무게를 차등한다
- 상태: Accepted
- 결정일: 2026-08-05
- 결정자: 박지현
- 관련 문서: 카카오페이 — PR을 느리게 만들기, WORKFLOW.md
맥락 (Context)
AI 도구로 코드 생산 속도는 올랐지만 리뷰 속도는 사람 가용성에 묶여 그대로다(카카오페이 실측: PR 생성→머지 시간은 AI 도입 전후 동일). 기존 FE·BE PR 템플릿은 “무엇을 했나”만 묻고, 리뷰어가 판단에 필요한 “왜 했나 · 무엇을 포기했나 · 어디를 봐야 하나”를 담지 않는다. 그 결과 모든 PR이 같은 무게로 리뷰 큐에 쌓인다.
고려한 옵션 (Considered Options)
- 리뷰를 빠르게 — 리뷰 SLA·독촉 자동화
- PR을 리뷰하기 쉽게 — 본문을 의사결정 문서로, 리뷰 무게 차등, AI 사전 리뷰
- 현행 유지 — 템플릿 그대로
옵션별 비교
| 기준 | 1 리뷰 독촉 | 2 PR 재설계 | 3 현행 |
|---|---|---|---|
| 병목 원인 해소 | 아니오(증상만) | 예 | 아니오 |
| 작성자 부담 | 없음 | 섹션 6개 | 없음 |
| 소규모 팀 적합 | 낮음 | 높음 | — |
결정 (Decision)
옵션 2를 선택한다. 리뷰 속도가 아니라 리뷰 비용을 줄인다. 작성자가 PR 본문에 “왜 · 한계와 트레이드오프 · 리뷰 포인트(Risk)“를 미리 쓰는 비용을 감수하고, 그 대가로 리뷰어는 판단이 필요한 지점만 본다. 구체 규칙은 WORKFLOW.md의 PR 규약이 원본이다.
핵심 3가지:
- PR 본문 = 의사결정 문서 — 왜/한계·트레이드오프/리뷰 포인트를 작성자가 채운다.
- 리뷰 무게 차등 — 자명한 변경(리네임·포맷팅·테스트 추가·동작 동일 리팩토링)은 AI 리뷰 통과만으로 머지 가능. 비즈니스 로직·새 패턴·트레이드오프가 있으면 사람 승인 필수.
- AI 사전 리뷰 — 자체 봇 대신 기성 claude-code-action을 FE·BE에 붙이고, 코멘트에 심각도 태그(
[r]반드시 반영 /[c]권장 /[a]사소)를 강제한다. Copilot 리뷰는 보조로 유지.
결과 (Consequences)
- 좋아지는 것: 사람 리뷰가 비즈니스 판단에 집중. 자명한 PR이 큐를 막지 않음. PR 본문이 결정 기록으로 남음.
- 감수하는 것: PR 작성 시간 증가(섹션 6개). AI 리뷰 토큰 비용. “한계” 섹션을 빈칸으로 도망갈 유인 — 자명한 변경 유형을 열거로 못박아 방어.
- 후속 작업: FE·BE 템플릿 교체, claude-review 워크플로 추가, 레포 시크릿
CLAUDE_CODE_OAUTH_TOKEN등록(사용자 수동).
재검토 조건
팀원 증가로 리뷰어가 2명 이상 되거나, AI 리뷰 코멘트 반영률이 유의미하게 낮으면(카카오페이 기준 16%) 태그 체계·차등 기준을 재조정한다.