리뷰어가 정말 이 PR을 이해하고 승인하는가
리뷰어가 정말 이 PR을 이해하고 승인하는가
들어가며
PR 리뷰는 보통 “코드가 잘 짜였나”를 본다. diff를 읽고, 컨벤션을 확인하고, 의심스러운 부분에 코멘트를 단다. 이 흐름은 익숙하다.
문제는 머지된 뒤 운영에서 터질 때 자주 보이는 패턴이다. 리뷰어가 그 PR이 왜 그렇게 만들어졌는지 설명하지 못한다.
- 왜 이 설계를 골랐는지
- 외부 의존성이 죽으면 어떻게 되는지
- 검증 위치가 바뀌면서 보호받지 못하게 된 호출자가 누군지
- 캐시 TTL 값이 왜 이 숫자인지
이런 공백은 리뷰에서는 잘 안 보인다. 운영에서 보인다.
pr-understanding-question은 이 공백을 머지 전에 드러내기 위한 스킬이다.
저장소는 여기다.
https://github.com/hansonkim/pr-understanding-question
무엇을 다르게 하나
일반 PR 리뷰는 보통 두 갈래로 간다.
- 자동 리뷰 — 린트, 정적 분석, 보안 스캐너, AI 리뷰어가 코드 자체에 대해 코멘트를 단다.
- 사람 리뷰 — 동료가 diff를 보고 의견을 단다.
둘 다 “코드가 어떤가”에 초점이 있다. pr-understanding-question은 다른 질문을 한다.
이 PR을 승인하려는 리뷰어가, 그 책임을 질 만큼 변경을 이해하고 있는가?
스킬이 검사하는 대상은 코드가 아니라 리뷰어의 이해도다.
어떻게 동작하나
스킬은 일회성 출력이 아니라 대화로 진행된다. 단계는 단순하다.
- PR 정보(제목, 설명, diff, 설계 메모, 알려진 위험)를 스킬에 넘긴다.
- 스킬이 내부적으로 3~7개의 질문을 만든다. 답변 채점 기준은 숨겨둔다.
- 질문이 한 번에 하나씩 제시된다. 리뷰어는 답하고 나서야 다음 질문을 본다.
- 모든 답변이 끝나면 각 답변을 PR 사실과 대조해 평가한다.
- 0~4점 점수, 빠진 부분, 후속 질문이 나온다.
핵심은 채점 기준을 미리 보여주지 않는 것이다. 기준을 먼저 보면 그 기준에 맞춰 답을 짜게 된다. 이해를 검사하는 게 아니라 컨닝페이퍼 시험이 된다.
질문은 이렇게 생겼다
예를 들어, 위치 이력 API에 Redis 캐시를 도입하면서 “Redis 실패 시 fallback 없음”이 설계 메모에 명시된 PR을 본다고 하자. 스킬이 만들 질문은 이런 식이다.
## Question 2 / 5: Behavior when Redis is unavailable
### Context
설계 메모에 "no fallback logic when Redis fails"가 명시되어 있다.
get_history()는 self.redis.get()을 예외 처리 없이 호출한다.
### Why this matters
이 PR 이전에는 Redis 장애가 이 API에 영향을 주지 않았다.
이 PR 이후에는 Redis가 hard dependency가 되어, Redis 가용성이 API 가용성의 천장이 된다.
### Question
이 PR 이전에는 Redis 장애가 /v2/location/history에 영향을 주지 않았다.
이 PR 이후 Redis가 죽으면 어떤 일이 일어나고, 그 영향을 받아들인 이유는 무엇이었나?이 질문에는 모범답안이 없다. 모범답안이 무엇인지 알아내라는 게 아니라, 리뷰어가 이 질문에 답할 수 있는 사람인가를 본다.
평가는 어떻게 하나
리뷰어가 답하면, 스킬이 PR 안의 사실(파일, 함수, 설계 메모)에 대조해 채점한다. 답변마다 다음과 같은 결과가 나온다.
## Question 2 / 5: Behavior when Redis is unavailable
### Score
1 / 4
### Assessment
HTTP 500이 반환된다는 점은 정확히 짚었지만,
fallback을 두지 않은 이유와 모니터링 전략을 언급하지 않았다.
### Supported by provided context
- services/location_service.py: self.redis.get()에 예외 처리 없음 — 확인됨
### Gaps
- fallback을 두지 않은 근거(Redis SLA, 운영 비용, 수용 가능한 위험) 누락
- Redis 장애를 어떻게 탐지·알람할지 누락
### Follow-up question
fallback 없이 출시한 근거는 무엇인가?
이 API의 SLA를 만족시키는 데 충분한 Redis 가용성 SLA가 확인되었나?핵심은 “잘했다/못했다”가 아니라 PR의 어떤 사실에 근거해 채점했는지를 인용하는 것이다. 채점이 의견 싸움이 되지 않게 한다. 그리고 부족한 부분을 닫기 위한 후속 질문을 함께 준다 — 리뷰어가 이 자리에서 보강할 기회를 주는 셈이다.
어디에 쓰나
| 상황 | 일반 리뷰 | 이 스킬을 끼웠을 때 |
|---|---|---|
| 시니어가 주니어 PR을 검토 | 코드만 보고 LGTM | 주니어가 자기 PR을 설명하게 만들고 약점을 찾는다 |
| 리뷰어가 한 명뿐인 작은 팀 | 한 명이 모든 책임 | 머지 전에 그 한 명이 정말로 이해했는지 자기검증 |
| 외주·위탁 코드 | 시간 부족으로 형식적 승인 | 위탁자가 답변하지 못하는 영역이 어디인지 빠르게 노출 |
| 신입 온보딩 | 큰 PR을 던져주고 알아서 봐라 | 핵심 결정과 위험 지점을 질문 형태로 학습 |
| 본인이 쓴 PR을 자기검증 | 어렵다 | 스킬이 객관적인 질문을 만들어 줘서 자기 점검 가능 |
특히 마지막이 의외로 유용하다. 자기 PR을 자기가 리뷰할 때, 우리는 자연스럽게 “내가 잘 알고 있다”고 가정한다. 스킬은 그 가정을 깬다.
한계
이 스킬이 대신해 주지 않는 것이 있다.
- 코드 정확성: 버그, 보안, 성능 검증은 여전히 다른 리뷰어와 도구의 몫이다.
- 설계 결정 자체의 옳고 그름: 스킬은 “리뷰어가 그 결정을 설명할 수 있는가”를 본다. 결정 자체가 옳은지를 판정하지는 않는다.
- 승인 책임: 점수가 만점이어도 승인 책임은 사람이 진다. 스킬은 보조자다.
또 채점 기준이 PR에 제공된 사실에 한정된다. 설계 메모와 diff에 적혀 있지 않은 맥락(과거 사고, 팀 컨벤션, 외부 SLA)을 리뷰어가 답에 포함시켰다면, 스킬은 그것을 Unverified from provided context로 표시한다. 이건 단점이라기보다 의도된 동작이다. 스킬이 못 본 사실을 임의로 추측하지 않게 한다.
왜 질문을 한 번에 하나씩 보여주는가
질문 5개를 한꺼번에 늘어놓으면 리뷰어는 자연스럽게 답을 다듬어 정합성을 맞춘다. 첫 답에서 한 말과 다섯 번째 답에서 한 말이 어긋나지 않게 머릿속에서 후처리를 한다. 그러면 정작 알고 싶은 것 — 즉시 떠오르는 이해 수준 — 이 가려진다.
질문을 하나씩 보여주고 답을 받은 뒤 다음으로 넘어가는 방식은, 그 후처리를 차단한다. 리뷰어가 모르는 영역에서 모른다는 신호가 그대로 드러난다.
리뷰어 입장에서는 약간 불편하다. 그러나 그 불편함이 이 스킬의 목적과 정확히 같은 방향을 가리킨다.
마무리
PR 리뷰가 코드를 검사하는 일에서 멈추면 책임은 흩어진다. 코드가 통과해도, 그 코드를 운영에서 책임지는 사람의 머릿속에 무엇이 있는지는 아무도 확인하지 않는다.
pr-understanding-question은 작은 장치다. PR을 한 번 더 보게 하지 않는다. PR을 승인하려는 리뷰어 자신을 한 번 더 보게 한다.
승인 직전에 몇 분, 몇 개의 질문. 그게 사고가 운영으로 빠져나가는 것을 의외로 자주 막는다.
참고
작성일: 2026년 5월 6일