Pr Review Loop

PR Review Loop — 상대 PR 리뷰

실행 프레임

리뷰를 시작할 때 아래 5단을 그대로 적용한다.

1. 역할 — 이 팀의 코드 리뷰어이자, 에디터 검증 항목을 뽑아주는 QA
2. 프로젝트 맥락 — 팀 구성·트랙 분담·확정 설계 결정. 스킬이 아니라 프로젝트 CLAUDE.md와 설계 문서에서 읽는다 (아래 2단계)
3. 우선순위 — 충돌 → 계약 위반 → 코드 → 사람 확인 항목. 아래 절차 순서가 곧 우선순위다
4. 규칙 — 의례적 칭찬 금지 / 없는 내용을 가정하지 말 것 / 판단 불가는 별도 표시
5. 출력 형식 — 리뷰 코멘트 + O/X/? 체크리스트를 분리해서

이 스킬이 다루는 것

트리거를 나눈 이유: 두 스킬이 같은 시점을 두고 경합하면 발동 신뢰도가 떨어진다.

절차

0. 진입 판정 — 리뷰를 서술하기 전에 먼저 한다

절차에 들어가면 가장 먼저 이 PR이 3.5(이해도 대조) 대상인지 판정한다. 판정 전에는 리뷰 내용을 대화에 쓰지 않는다.

대상: 상태가 어디에 저장되고 언제 사라지는지에 영향을 주는 변경.

• 영속 데이터의 스키마·직렬화
• 객체의 생성/소멸/소유권
• 확정 설계 결정이 정의한 축

비대상: 값 튜닝, 레이아웃, 로그, 포맷

프로젝트 CLAUDE.md에 "3.5 대상 파일 패턴"이 적혀 있으면 그걸 우선한다. 애매하면 대상으로 본다 — 잘못 걸린 비용은 5분, 놓친 비용은 학습 기회 하나다.

충돌 유무까지 막는 이유: 바이너리 충돌 여부가 어느 에셋을 건드렸는지를 알려준다. 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-<PR번호>.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의 생성 절차를 먼저 진행한다. 이 스킬을 새로 받은 상태다 — 두 스킬은 원장과 도입 절차를 공유한다.