“좋은 PR은 코드를 설명하지 않는다.
무엇을 같게 만들었는지와 무엇을 다르게 남겼는지를 먼저 합의한다.”

횡단 PR은 늘 길다.
문제는 길이가 아니라, 리뷰어가 처음 보는 순간 길이밖에 안 보인다는 점이다.

최근 tail 지표를 정리한 글을 쓰면서, 생산성이 타이핑보다 맥락 비용에서 갈린다는 걸 다시 느꼈다.
그중 하나가 리뷰다. diff를 빨리 읽는 것보다, 무엇을 같게 만들었는지를 먼저 맞추는 쪽이 전체 속도를 올린다.

그래서 PR 본문을 코드 설명이 아니라 의도 합의 문서로 본다.
리뷰어가 먼저 읽어야 하는 건 함수명이 아니라, 바뀐 약속의 경계다.

왜 횡단 PR은 쉽게 망가질까

앱마다 구현 위치가 달라, 같은 정책이 다른 문장으로 흩어진다.
리뷰어는 도메인은 알아도 파일 경로는 모른다.
“일단 LGTM”이 빨라질수록, 런칭 뒤 누락이 늦게 터진다.

필요한 건 거창한 포맷이 아니라, 항상 같은 순서로 읽히는 본문이다.

내가 쓰는 PR 3단락

1) 의도

이번 변경으로 같게 만드는 것 2~3개
일부 앱에서 의도적으로 다르게 두는 것 1~2개

2) 리뷰어가 볼 곳

핵심 파일 2~4개
각 파일에서 “무엇을 판단해야 하는지” 한 줄

3) 롤백

플래그·토글·revert 중 실제로 가능한 경로
롤백 뒤 확인할 화면·로그 한 줄

아래는 가장 자주 복붙하는 뼈대다. 경로·플래그명은 가상 예시다.

## 의도
- checkout / wallet / home 에서 eligibility 문구를 같게 맞춘다.
- content는 약관 링크만 맞추고 배너는 의도적으로 제외한다.

## 리뷰어가 볼 곳
- `packages/payments-ui/useSummary.ts` — surface별 캐시 키
- `apps/checkout/.../SubmitBar.tsx` — payload optional 필드

## 롤백
- `FF_PHASE2` off 시 신규 배너·payload 확장 분기 전체 비활성화

리뷰 요청 전에 스스로에게 묻는 10가지

이 PR이 같게 만들려는 약속은 한 문장으로 무엇인가?
의도적으로 다르게 둔 곳은 어디이며, 합의 근거가 있는가?
화면 단위 누락이 없는가? (app/route 기준)
이벤트·로그 속성명이 기존과 충돌하지 않는가?
API payload의 optional 필드가 구버전 경로를 깨지 않는가?
플래그 off 시 정말 구경로로 돌아가는가?
QA 시나리오가 “정상”만 있고 조합 예외는 빠지지 않았는가?
문구·정책 표현이 앱별로 어긋나지 않는가?
리뷰 범위 밖(non-goals)이 명시되어 있는가?
런칭 후 48시간 안에 볼 지표·로그가 정해져 있는가?

붙이면 달라지는 것

3단락을 넣는다고 버그가 사라지지는 않는다.
다만 리뷰 대화가 “이 코드가 예쁘냐”에서 “이 약속이 맞냐”로 옮겨간다.

그 이동이 생산성이다.
코드 생성 속도보다 합의 실패를 줄이는 속도가 먼저 오른다.

마치며

횡단 PR에서 리뷰어는 코드보다 맥락을 먼저 본다.
그 순서를 PR 본문이 대신해 주면, diff가 길어도 대화는 짧아진다.

처음엔 템플릿 전체가 아니라 의도 단락 한 블록만 넣어도 충분하다.

한 줄 결: 횡단 PR의 첫 단추는 코드가 아니라 의도다. 의도가 선명하면 리뷰 속도보다 리뷰 품질이 먼저 오른다.