# Pr Review Loop
> 팀원이 올린 PR을 리뷰한다. **`PR` + `올라온/올라왔` + `리뷰`가 한 문장에 있으면 형태를 가리지 않고 발동한다** — 요청문뿐 아니라 평서형·전언형도 포함이다: "PR 올라온게 있는데 리뷰 좀 해줘", "PR 올라온거 리뷰하려고", "PR이 하나 올라왔더라고, 리뷰 좀 해줄수 있어?", "PR 새로 올라왔던데 리뷰 해 줄 수 있어?", "팀원 쪽 PR 올라온게 있는데 리뷰좀 해줘". 충돌 확인만 언급해도("충돌 없는지 봐줘") 같은 절차를 탄다. **호출되면 리뷰를 서술하기 전에 이 PR이 이해도 대조(3.5) 대상인지부터 판정한다** — 상태·저장·데이터 구조를 건드리는 PR이면 리뷰 결과를 대화에 쓰지 않고 파일에 먼저 쓴 뒤 질문 네 개를 던지고 멈춘다. 절차는 충돌 확인 → 팀 머지 기준·설계 문서 대조 → 코드 리뷰 → (이해도 대조) → "사용자가 에디터에서 직접 확인할 항목"을 O/X 체크리스트로 분리 생성 → 코멘트 → 머지 → 컴파일 검증. "내가 에디터에서 확인해야 할 항목"은 사용자가 요구하기 전에 낸다. 또한 "이 스킬 의도대로 작동해?", "이 스킬 잘 되고 있어?"처럼 스킬 자체의 효과를 점검해 달라는 요청에도 발동하며, 그때는 같은 폴더의 `RATIONALE.md`를 읽고 이번 세션·기존 기록과 대조한다.
- Skill: `iceberggymnast/pr-review-loop` (Agent Skill)
- Install (CLI): `npx skillmds@latest add iceberggymnast/pr-review-loop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/iceberggymnast/pr-review-loop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: iceberggymnast (https://skillmd.com/u/iceberggymnast)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/iceberggymnast/pr-review-loop
---
# PR Review Loop — 상대 PR 리뷰
## 실행 프레임
리뷰를 시작할 때 아래 5단을 그대로 적용한다.
1. **역할** — 이 팀의 코드 리뷰어이자, 에디터 검증 항목을 뽑아주는 QA
2. **프로젝트 맥락** — 팀 구성·트랙 분담·확정 설계 결정. **스킬이 아니라 프로젝트 CLAUDE.md와 설계 문서에서 읽는다** (아래 2단계)
3. **우선순위** — 충돌 → 계약 위반 → 코드 → 사람 확인 항목. 아래 절차 순서가 곧 우선순위다
4. **규칙** — 의례적 칭찬 금지 / 없는 내용을 가정하지 말 것 / **판단 불가는 별도 표시**
5. **출력 형식** — 리뷰 코멘트 + **O/X/? 체크리스트를 분리**해서
## 이 스킬이 다루는 것
| 상황 | 담당 |
|---|---|
| **팀원이 올린 PR을 리뷰** | **이 스킬** |
| 내가 PR을 올릴 때 | `senior-mentor` (러프 복습 모드) |
트리거를 나눈 이유: 두 스킬이 같은 시점을 두고 경합하면 발동 신뢰도가 떨어진다.
## 절차
### 0. 진입 판정 — 리뷰를 서술하기 전에 먼저 한다
절차에 들어가면 **가장 먼저 이 PR이 3.5(이해도 대조) 대상인지 판정한다.** 판정 전에는 리뷰 내용을 대화에 쓰지 않는다.
**대상**: 상태가 어디에 저장되고 언제 사라지는지에 영향을 주는 변경.
- 영속 데이터의 스키마·직렬화
- 객체의 생성/소멸/소유권
- 확정 설계 결정이 정의한 축
**비대상**: 값 튜닝, 레이아웃, 로그, 포맷
프로젝트 CLAUDE.md에 "3.5 대상 파일 패턴"이 적혀 있으면 그걸 우선한다.
**애매하면 대상으로 본다** — 잘못 걸린 비용은 5분, 놓친 비용은 학습 기회 하나다.
| 판정 | 흐름 |
|---|---|
| 비대상 | 1 → 2 → 3 → 4 → 5 → 6 을 평소대로 연속 진행 |
| **대상** | 1 → 2 → 3 → **3.5의 2번(파일 쓰기)까지만 하고 멈춘다.** 사용자 답변을 받은 뒤에야 3.5의 4~5번(대조·적재) → 4단계로 간다.
**판정 시점부터 3.5의 3번까지, 1~3단계 산출물을 일절 대화에 쓰지 않는다.** 충돌 유무·ADR 대조·코드 리뷰 전부 파일로만 간다. 화면에 나가는 것은 진입 판정 한 줄과 질문 네 개뿐이다 |
**충돌 유무까지 막는 이유**: 바이너리 충돌 여부가 어느 에셋을 건드렸는지를 알려준다. 2단계도 마찬가지로 — "확정 설계 결정 X와 충돌하는 것 같다"고 한 줄만 말하면 그 결정이 정의한 상태·저장 축을 직접 지목하게 되어 질문 1번과 3번이 동시에 무력화된다. 계약 위반 판정은 3.5 질문의 답을 배달하는 정보다.
대상이면 판정 결과를 한 줄로 알린다("이 PR은 이해도 대조 대상입니다. 리뷰는 파일에 먼저 쓰고 질문 네 개를 드립니다"). 이 알림이 없으면 사용자는 리뷰가 왜 화면에 없는지 모른다.
**판정과 함께 PR 규모를 잰다** — `gh pr view <번호> --json additions,deletions,changedFiles`. 재서 3.5의 적재 때 출처 칸에 적는다(`PR #47 (96f/+4.6k)`).
**임계값은 두지 않는다.** 규모로 절차를 갈라야 할 것 같지만, 지금 그 선을 정하면 지어내는 것이 된다 — 실측에서 41파일 PR과 96파일 PR의 대조 결과가 갈리지 않았다. 먼저 기록만 하고, 몇 회 쌓인 뒤 판정한다.
### 1. 충돌 확인
텍스트 충돌 + **병합 불가 바이너리**를 본다. 유형은 프로젝트에 따라 다르다:
- **UE** — `.uasset` `.umap`: 병합 불가. DataTable 소스(CSV/JSON)의 줄바꿈
충돌은 실제 변경이 아닐 수 있다 (`core.autocrlf` × `.gitattributes`)
- **Unity** — `.prefab` `.unity` `.asset`: YAML이라 병합은 되지만 신뢰하지 않는다.
`.meta` 파일 누락/중복 GUID를 함께 본다
- **그 외** — 이미지·바이너리 에셋 일반
**어느 유형인지는 레포를 보고 판단한다.**
### 2. 팀 머지 기준 대조
**기준은 프로젝트 CLAUDE.md에서 읽는다. 스킬에 박아두지 않는다.**
아래 항목을 CLAUDE.md에서 찾아 대조한다:
- 빌드·컴파일 통과 조건
- 확정 설계 결정(ADR 등) 위반 여부
- 승인 요건 / 리뷰 마감
- 병합 불가 바이너리 유형
**CLAUDE.md에 해당 항목이 없으면 지어내지 않는다.**
"이 프로젝트의 머지 기준이 문서에 없습니다"라고 알리고,
확인 가능한 것(빌드, 충돌)만 대조한다.
**설계 문서도 같은 방식으로 찾아 대조한다.** CLAUDE.md는 팀 운영 규칙이고,
PR이 건드리는 시스템이 "원래 어떻게 되기로 했는지"는 거기 없다.
- PR이 건드리는 시스템 이름으로 레포의 `.md`를 검색한다
(세이브를 건드리면 `save`·`세이브`, 퀘스트면 `quest`·`퀘스트` 식으로)
- 나오면 읽고 대조한다 — 코드가 문서와 다르면 어느 쪽이 맞는지는 리뷰가 정하지 않고 지적만 한다
- **안 나오면 "이 시스템의 설계 문서가 없습니다"라고 밝히고** 코드 기준으로만 판정한다
레포에 설계 문서가 아예 없는 경우가 정상이다. 없는 것을 문제로 만들지 않는다.
**같은 자리에서 두 가지를 더 본다.** 둘 다 코드 밖에 있어서 3단계로는 안 걸리고, 실제로 두 번 다 사용자가 리뷰보다 먼저 짚었다.
- **직전 PR의 남은 항목** — 이전 리뷰 코멘트에 "남은 항목"·"추후 확인"으로 넘긴 것이 있으면 이번 PR에서 처리됐는지 대조한다. 안 됐으면 그대로 다시 올린다
- **회의록의 합의 범위** — 팀 회의록이 있으면 이번 PR의 구현 범위가 회의에서 정한 것과 같은지 본다. **합의에 없던 구현, "보류"로 정해둔 항목의 구현은 결함이 아니어도 짚는다.** 코드만 보면 멀쩡해서 코드 리뷰로는 절대 안 걸린다
둘 다 없으면 없다고 밝힌다. 지어내지 않는 것은 위와 같다.
### 3. 코드 리뷰
- 스코프는 **PR이 건드린 범위**로 제한한다. 프로젝트 전체 훈수를 두지 않는다
- 이미 진단이 끝난 사안은 재분석하지 않고 **델타만** 본다
- 수정 제안은 GitHub `suggestion` 블록으로 — 상대가 클릭 한 번으로 반영할 수 있게
3.5 대상이면 0단계의 금지가 여기까지 걸려 있다. 곧바로 3.5로 간다.
### 3.5 이해도 대조 (선별 적용) ← 학습 루프
**적용 대상은 0단계에서 이미 판정했다.** 여기서 다시 정의하지 않는다.
전건 적용하면 2주 안에 유지가 불가능하므로 선별은 유지한다.
**순서를 반드시 지킨다. 순서가 이 절차의 전부다.**
1. 3단계 리뷰를 끝낸다.
2. 결과를 **세션 스크래치패드 디렉터리**의 `review-.md`에 **먼저 쓴다.**
- 경로는 시스템 프롬프트에 명시된 세션 스크래치패드 절대경로를 쓴다. **작업 중인 저장소에 쓰지 않는다** — 상대경로로 쓰면 레포에 파일이 생겨 git에 딸려 들어간다.
- 위험 지점 / 이유 / 확신도만. 대화에는 서술하지 않는다.
- 파일에 쓰기 전에는 사용자에게 아무것도 묻지 않는다.
3. **아래 질문을 토씨 그대로** 사용자에게 던진다. 발견 사항에 맞춰
변형하거나 새로 만들지 않는다. 질문이 지점을 지목하면 이 절차는 무효다.
> 이 PR 읽고 아래 네 개만 답해줘. 모르면 "모름"으로 두면 된다.
> 1. 이 변경이 건드리는 상태는 무엇이고 어디에 저장되나
> 2. 이게 깨지면 어떤 증상으로 나타나나
> 3. 이 변경의 영향 범위가 어디까지인가
> 4. **지금 확신이 안 서는 지점은 어디인가**
4. 답을 받은 뒤 2번 파일을 다시 읽고 대조한다. **세 칸을 모두 채운다.**
| 구분 | 처리 |
|---|---|
| 둘 다 짚음 | 부채가 아니다. 5(a)의 집계 한 줄로만 남긴다 |
| **AI만 짚음** | **`## 부채 항목`행.** 개념명까지 붙여서 기록 |
| **사용자만 짚음** | 리뷰가 놓친 것. 왜 놓쳤는지 한 줄 + `CLAUDE.md` 후보인지 판정 |
4.5. **`모름`·`짚었으나 틀림`이 나온 항목마다 원인을 한 번 묻는다.**
> 아래 항목은 답에 안 나왔습니다. 각각 ① 개념을 몰라서인지 ② 그 부분까지 못 읽어서인지만 알려주세요.
대조가 끝난 뒤라 항목을 지목해도 오염되지 않는다.
| 답 | 집계 값 |
|---|---|
| ① 개념을 몰랐다 | `모름` / `짚었으나 틀림` 그대로 |
| ② 거기까지 못 읽었다 | **`읽지 못함`** — 학습 분포에서 빠지고 부채 항목도 만들지 않는다 |
**3번의 4번 질문("확신이 안 서는 지점")으로 대신하지 않는다.** 자기신고는 넘친 분량을 못 잡는다 — 실측에서 "확신이 안 서는 건 딱히 없음"이라 답한 항목을 같은 세션 안에서 사용자가 되물었다. 지목한 뒤에 물어야 답이 나온다.
이 분기가 없으면 원장이 **개념을 몰라 생긴 부채**와 **읽을 분량이 넘쳐 생긴 공백**을 같은 칸에 넣는다. 처방이 정반대다. 앞은 공부할 것이고, 뒤는 PR을 쪼개거나 변경 요약을 요구할 것이다.
5. **대조 결과를 적재한다.** 적재처는 `~/.claude/comprehension-debt.md` —
`senior-mentor`가 쓰는 그 파일이다. **형식은 그 파일이 기준이며 별도 원장을 만들지 않는다.**
(a) **모든 대조 결과** → `## 대조 집계`에 한 줄씩. `일치`도 남긴다(분모).
```
| 2026-08-12 | PR #47 (23f/+0.8k) | MyGame/UE5-C++ | 상태 관리 | 일치 |
| 2026-08-12 | PR #47 (23f/+0.8k) | MyGame/UE5-C++ | 세이브 스키마 | 짚었으나 틀림 |
| 2026-08-12 | PR #47 (23f/+0.8k) | MyGame/UE5-C++ | 액터 생명주기 | 모름 |
```
컬럼은 `날짜 | 출처 | 영역 | 개념 | 결과`이고 **`senior-mentor`의 모드 C
결과와 같은 표에 섞인다.** 출처만 다르다(`PR #47` vs `커밋 a1b2c3d`).
지표를 한 곳에서 보려는 것이므로 표를 나누지 않는다.
3칸 대조를 집계 값으로 옮기는 규칙:
| 대조 결과 | 집계 값 |
|---|---|
| 둘 다 짚음 | `일치` |
| AI만 짚음 (사용자가 답했으나 빗나감) | `짚었으나 틀림` |
| AI만 짚음 (사용자가 "모름") | `모름` |
| AI만 짚음 (4.5에서 "못 읽음") | `읽지 못함` |
| **사용자만 짚음** | `사용자 선행`. 사용자 부채가 아니라 **리뷰가 놓친 것**이므로 부채 항목은 (b)에서 `[리뷰 측 누락]`으로 따로 만든다 |
**`사용자만 짚음`을 집계에서 빼지 않는다.** 빼면 지표가 사용자의 약점만 세고 강점은 안 센다 — AI가 코드에서 뽑은 개념만 분모에 들어가므로, 코드 밖에서 짚은 것(합의 범위 이탈, 직전 PR 미반영)은 아무리 값나가도 기록에서 사라진다.
(b) **부채가 되는 것만 정식 항목으로** — `모름` · `짚었으나 틀림`, 그리고
**사용자만 짚음**(리뷰 측 누락). **`읽지 못함`은 항목을 만들지 않는다** —
갚을 주체가 사용자가 아니다. 형식은 `comprehension-debt.md`의
`## 부채 항목` 템플릿을 그대로 쓰고 출처에 `(PR #47)`처럼 적는다.
**`판별점` 칸을 비우지 않는다** — "이미 알던 층 → 몰랐던 층"의 경계다.
개념명만 남기면 나중 복습 질문이 알던 층을 물어 통과 도장이 된다.
두 층이 서로 다른 스택에 걸쳐 있으면 `갭 위치`도 함께 적는다
(형식·예시는 그 파일의 "판별점"·"갭 위치" 절).
**사용자만 짚음**은 `예측 상태` 대신 "왜 리뷰가 놓쳤는지 한 줄 +
`CLAUDE.md` 후보 여부"를 남기고, **`복습 체크` 칸도 두지 않는다.**
체크 조건이 "집계에 `일치`로 남는 것"인데 이 항목은 집계에 안 올라가서
닫을 근거가 생기지 않는다. 칸을 두면 영원히 미복습으로 쌓여 경고 신호가
가짜로 울린다. 사용자가 복습할 대상이 아니라 리뷰가 고칠 기록이다.
`senior-mentor`가 리뷰 시작 때 이 파일을 읽으므로, 적재한 항목은
그 소비 경로에 그대로 올라탄다.
(c) **프로젝트를 넘어 재사용되는 항목은 볼트로 승격한다.** 판정 질문과
노트 형식은 `senior-mentor`의 "볼트 승격" 절이 기준이며 여기 옮겨 적지 않는다.
`mentee-profile.md`의 "지식 볼트" 절이 "쌓지 않음"이면 건너뛴다.
6. **미복습 항목이 이번 답변에서 닫혔는지 확인한다 (수동 매칭).**
질문 네 개는 고정이라 **여기서는 겨냥하지 않는다.** 질문을 미복습 개념 쪽으로
비틀면 3번의 "토씨 그대로" 규칙이 깨지고, 지점을 지목한 순간 대조 자체가 무효다.
능동 겨냥은 `senior-mentor` 모드 C에서만 한다 — 거기는 질문을 코드에서 고르는 구조다.
대신 **받은 답을 원장의 미복습 항목과 맞춰본다.** 사용자가 스스로 그 판별점을
짚었으면 `## 대조 집계`에 `일치` 한 줄을 남기고 복습 체크를 닫는다.
- 판별점을 짚어야 닫힌다. **개념이 같아도 알던 층만 말했으면 닫지 않는다**
- 닫은 경우 대조 결과를 알릴 때 함께 밝힌다 — "4번 답이 3주 전 '상태 소유권'
항목의 판별점을 짚었습니다. 1회차가 닫혔습니다"
- 안 닫혔으면 아무 말도 하지 않는다. 어느 항목이 미복습인지 밝히면 다음 겨냥이 노출된다
7. **변경 지도를 낸다.** 대조 결과를 알릴 때, 이 PR이 새로 들여온 개념을 한 줄씩 나열한다. **결함이 없어도 낸다.**
3단계는 결함 목록이라 "이 PR이 무엇을 새로 들여왔는지"가 어디에도 안 남는다. 파일이 수십 개면 사용자가 그걸 직접 재구성할 방법이 없다. 답을 받은 뒤에 내므로 대조는 오염되지 않는다.
**비대상 PR에서는 3단계 끝에 낸다.** 거기서는 막을 이유가 없다.
**규칙**
- 3번 질문을 던진 뒤 **거기서 멈춘다.** 답을 받기 전에 4단계(에디터 확인 항목)로 넘어가지 않는다.
- 4번 "모름"은 정식 답변이며 **틀린 답보다 가치가 높다.** 초기 몇 주는
"모름"이 대부분인 것이 정상이고, 그 목록이 학습 순서를 정해준다.
- "사용자만 짚음" 칸을 비우고 넘어가지 않는다. 비어 있으면 비었다고
명시한다. 조용히 생략하면 이 절차의 절반이 죽는다.
- 사용자 답변을 본 뒤 2번 파일을 수정하지 않는다.
- **2번 파일은 세션 산출물이다.** 대조가 끝나면 역할이 끝나므로 어디에 남길지
신경 쓰지 않는다. 남는 것은 5번의 원장 항목뿐이다.
**4단계와 섞지 않는다.** 4단계는 기능 검증(에디터에서 O/X)이고 이건 이해도 검증이다. 산출물이 다르므로 같은 체크리스트에 합치지 않는다.
### 4. 사람이 확인할 항목 분리 ← 이 스킬의 핵심
코드만으로 판정할 수 없는 항목을 **별도 체크리스트로 뽑는다.** 사용자가 요구하기 전에 낸다 — 요구하게 만들면 이 스킬은 값을 못 한 것이다.
형식은 **O / X / ? + 한 줄**로 제한한다. 자유 서술로 쓰면 작성 비용이 크고 해석 오류도 생긴다.
```
# 예시 (UE 프로젝트) — 항목 내용이 아니라 입도를 참고한다
[ ] 스폰 시드가 0이 아님
[ ] QuestLogWidgetClass 할당됨
[ ] 재시작 시 골드가 0으로 리셋
[ ] 보상 화면이 1회만 뜨고 게임이 멈췄다 재개됨
```
**`?`(못 봄)는 정식 답변이다.** 다만 `?`를 받으면 **둘 중 어느 쪽인지 한 번 확인한다.** 둘을 섞으면 하네스 백로그에 없는 문제가 쌓인다.
| `?`의 종류 | 처리 |
|---|---|
| **확인할 수단이 없다** — "미니맵을 켜고 끄는 버튼 자체가 없어서 확인 못 함" | 검증 실패가 아니라 **하네스 부재**다. 따로 모아 하네스 백로그로 넘긴다. 같은 항목이 반복되면 그 부분의 디버그 도구를 먼저 만든다 |
| **수단은 있는데 못 봤다** — 시간·우선순위 | 그냥 **미검증**이다. 백로그로 넘기지 않고 "확인 안 한 것"으로만 남긴다. 머지 전에 봐야 하는 항목인지만 판단한다 |
사용자가 구분해서 답하지 않았다면 리뷰가 추측하지 않고 묻는다 — 한 줄이면 끝나고, 틀리면 백로그가 오염된다.
### 5. 코멘트
**초안을 먼저 보이고 승인을 받은 뒤에 올린다.** 리뷰 코멘트는 상대에게 나가는 글이라, 올라간 뒤의 수정은 상대가 이미 읽은 뒤다.
1. 코멘트 전문을 세션 스크래치패드에 파일로 쓴다. 복붙으로 나르지 않는다
2. **전문을 대화에 그대로 낸다.** 요약하거나 앞부분만 내지 않는다 — 안 보인 부분이 곧 확인 안 된 부분이다
3. 고칠 곳을 지목받으면 반영하고 다시 낸다
4. 승인을 받은 뒤 `gh pr comment --body-file`로 올린다
**초안을 낸 것을 승인으로 치지 않는다.** 사용자가 답하기 전에 올리면 절차가 없는 것과 같다. 6단계의 빌드 결과 코멘트도 같은 순서를 탄다 — 한 줄이라도 상대에게 나가는 것은 같다.
- 리뷰 톤은 팀원용 작업 메모. AI 티 나는 수사(클로징 문단, 과잉 볼드, 대조 구문 반복)를 쓰지 않는다
- 사용자가 직접 고치기로 한 항목은 그렇게 명시한다
- 확인 불가 항목은 "추후 확인 사항"으로 전달
- **`읽지 못함`이 나왔으면 코멘트에 남긴다.** 결함 지적이 아니라 다음 PR에 대한 요청이다 — "이번 PR은 96파일 4,600줄이라 리뷰 쪽에서 다 못 본 부분이 있다. 다음부터 ○○ 단위로 나누거나, PR 본문에 새로 들어온 개념 목록을 붙여달라." 사람이 읽을 수 있는 양을 넘긴 것은 리뷰어가 떠안을 문제가 아니다. 같은 요청이 세 번 반복되면 팀 규칙 후보로 올린다
### 6. 머지 후 컴파일 검증
머지가 끝이 아니다. **머지 대상 브랜치에서 빌드가 통과하는지 확인**하고 결과를 코멘트로 남긴다. 브랜치 이름을 가정하지 않는다 — 레포마다 `main`·`master`·`develop`이 다르다.
---
## 하지 말 것
- PR 범위를 벗어난 리팩터링 제안
- 이미 합의된 ADR을 다시 논의하자고 하는 것
- 코드로 판정 가능한 항목을 사람 확인 목록에 넣어 사용자에게 떠넘기는 것 (반대도 마찬가지)
- 사용자가 요청하지 않은 머지·push
- 승인 전에 `gh pr comment`·`gh pr review`를 실행하는 것
- **3.5 대상 PR에서 리뷰 내용을 대화에 먼저 서술하는 것** — 사용자가 읽어버리면 이해도 대조는 그 시점에 무효다
- 3.5의 질문 네 개를 발견 사항에 맞춰 다듬는 것
- **`모름`과 `읽지 못함`을 구분하지 않고 원장에 넣는 것** — 남이 만든 분량을 사용자 부채로 옮겨 적는 것이 된다
## 성공 기준 · 존재 의의
같은 폴더의 `RATIONALE.md`에 있다. **여기 옮겨 적지 않는다** — 두 벌이 되면 갈라진다.
사용자가 *"이 스킬 의도대로 작동해?"* 라고 물으면 그 파일을 읽고 이번 세션과 대조한다.
`RATIONALE.md`가 없으면 `../senior-mentor/BOOTSTRAP.md`의 생성 절차를 먼저 진행한다. 이 스킬을 새로 받은 상태다 — 두 스킬은 원장과 도입 절차를 공유한다.