Code Review

---
name: code-review
description: "코드 변경(작업 트리 diff·브랜치·PR·경로·커밋 범위)을 **읽기 전용**으로 검토해, 실제로 확인한 발견만 보고한다. '리뷰해줘·검토해줘·이 diff 봐줘·PR 봐줘·머지해도 되나·이 수정 괜찮아?·내가 고친 거 다시 봐줘' 류 요청, 그리고 스스로 수정을 마친 뒤 되짚을 때. 버그 진단('이거 왜 안 돼')에도 같은 검사 축을 쓴다. 리뷰는 독립 매니저가 먼저 혼자 읽고, 파일이 많으면 **겹치지 않는 파일 묶음**으로만 나눈다(관점·발견 수로 나누지 않는다). 발견마다 한 동작으로 확인한 뒤에만 보고하고, 고치지 않는다 — 수정은 사용자가 따로 시킬 때 별도 단계다."
---

# 코드 리뷰

리뷰는 **읽는다. 고치지 않는다.** 결과물은 «확인된 발견» 목록이다 — 확인 동작을 돌린 것만.

## A. 범위 — 먼저 한 줄로 선언한다

- 대상: 사용자가 가리킨 것(경로·PR·브랜치·커밋 범위·파일 목록). 말이 없으면
  **아직 반영 안 된 변경분** — 버전 관리가 있으면 그 미커밋 변경(`git diff` + 미추적 파일
  등), 없으면 **무엇을 볼지 한 줄로 묻는다.** ★버전 관리를 전제하지 마라: 이 스킬은 레포가
  아닌 폴더에도 쓰인다.
- 기본 범위 = **diff + 바뀐 심볼의 직접 호출부 + 그 심볼을 이름으로 부르는 검사.**
  그 밖(변경 이력·인접 모듈·설계 문서)은 사용자가 «깊게·넓게·전부·이력까지» 라고 할 때 연다.
  요청보다 좁히지 말고, 요청 없이 넓히지 마라.

## B. 누가 읽나 — 리뷰는 독립 매니저가 수행한다

작성·대화를 담당한 컨텍스트는 리뷰 범위를 정하고 `run_in_background`로 매니저에게
넘긴다. 단일 모듈·작은 diff도 같다. 목적은 작성자의 의도와 결론을 리뷰 컨텍스트에
그대로 싣지 않는 것이다. 일반 작업의 직접 처리 기본값과 리뷰의 독립성은 별개다.

이미 리뷰 매니저라면 다시 매니저를 띄우지 않고 직접 읽는다. 배정받은 서브도 자기
파일을 읽으며 재위임하지 않는다. 독립 컨텍스트가 정확성을 보장하는 것은 아니므로
§D의 확인 근거와 읽기 전용 규칙은 모든 역할에 적용한다.

### 호출자가 전달할 것

대상·보고 범위·사용자 요구·검증 가능한 우려를 전달하되, 작성자의 «이렇게 고쳤으니
맞다»는 결론을 전제로 주지 않는다. `references/review-orchestration.md` §1을 사용한다.
매니저 대신 `spawn_agent` 한 명으로 **때우지 마라**. 서브는 재위임할 수 없어 검토
면적이 커졌을 때 조율할 수 없다. 매니저 도구가 없는 환경에서는 독립 검토 미수행을
명시하고, 작성자의 자체 확인을 독립 리뷰 완료로 보고하지 않는다.

### 매니저가 정한다 — 먼저 혼자 읽고 필요한 경우만 나눈다

기본은 매니저 혼자다. 파일·모듈별 **보고 책임**을 겹치지 않게 나눌 이유가 있을 때만
팬아웃한다. 관점별로 같은 diff를 반복해서 읽히거나 발견마다 검증자를 추가하지 않는다.
필요한 테스트·호출부·같은 원인의 이웃 읽기는 묶음 밖에서도 허용한다(§C).

    사람 수 = min(겹치지 않는 파일 묶음 수, 3)

**3은 천장이지 정원이 아니다.** 묶음이 하나면 매니저가 직접 읽는다. 인원을 채우려고
쪼개지 않는다. «넓게»는 검토 범위, «빨리»는 시간 요구이며 그 말만으로 인원을 늘리지
않는다. 사용자가 별도로 인원·방식을 지정하면 그 지시를 따른다.

팬아웃할 때만 묶음별 `spawn_agent` 후 `wait_for_worker`로 합류한다. 하위 작업에는
스킬 본문을 복사하지 말고 필요한 규칙을 한 번 로드하게 한다. 매니저는 발견 근거를
검증하고 합친다. 보고에는 실제 추가한 매니저·서브 수와 담당 묶음을 적는다.

비용은 역할별 지침·도구·스킬과 실제 요청 사용량에 달려 있다. 자식의 모든 색인이
비어 있거나 공용 프리픽스가 반드시 캐시된다고 가정하지 않는다. 공통 의존성 읽기와
독립 컨텍스트 비용은 남는다. 이를 줄이려고 리뷰 독립성을 제거하지 않는다.

## C. 무엇을 보나 — 다섯 축

정확성·가독성·성능·중복은 안 적어도 본다. 아래는 **안 적으면 안 보는 것**들이다.
각 항목은 «어느 파일·어느 줄» 로 답할 수 있을 때만 발견이 된다.

★**경계는 «읽는 범위» 가 아니라 «보고하는 범위» 다.** 발견은 자기 파일에 대해서만 내되,
**읽기·grep 은 아래 축이 요구하는 만큼 나간다**(검사 파일 · 호출부 · 이웃). 읽기까지 묶으면
축 1 은 «검사 없음» 을 양산하고 축 5 는 침묵으로 닫힌다 — 고치려던 것보다 나쁘다.

1. **검사는 「있나」가 아니라 「도나」.** 바뀐 줄마다: 이 줄을 되돌리면 어느 검사가
   빨개지나 — **이름을 대라.** 못 대면 그 줄은 검사 밖이고, 그것 자체가 발견이다.
   항상 초록인 검사(단언 없음 · 설명문을 대상으로 세는 검사)는 없는 검사다.
2. **부품이 아니라 이음매.** 함수 본체보다 **부르는 쪽과의 계약**을 본다.
   시그니처·반환 형태·예외·기본값이 바뀌었으면 **호출부 전수**(grep 으로 세고 그 수를
   적어라). 조건이 뒤집히거나 가드가 생겼으면 **그 분기에 도달하는 입력 전수**.
3. **수정이 낳은 결함.** diff 가 «고치기» 라면, 고치려던 것이 고쳐졌나와 **별개로**
   그 수정에 의존하던 것이 안 깨졌나. 새로 든 값·상태는 그것을 읽는 모든 분기에 닿나.
   수정도 새 코드이므로 원래 결함보다 결함이 많기 쉽다.
4. **손으로 관리하는 목록.** 새로 생긴 이름 열거·허용 목록·분기 나열은 낡을 시계가
   시작된 것이다. 정의점에서 파생시킬 수 있으면(파일시스템·타입·설정) 그렇게 하라고 짚는다.
5. **같은 원인의 이웃.** 결함 하나를 찾았으면 **같은 패턴을 grep 으로 인접한 곳에서 한 번**
   찾는다. ★**상한은 «찾는 횟수» 지 «적는 개수» 가 아니다** — grep 은 한 번이고, 그 한 번이
   준 것은 **다 적는다.** 이미 손에 든 것을 숨기면 «리뷰했다» 가 «그건 아무도 안 봤다» 를
   덮는다. 새 패턴이 보이면 그건 다음 발견의 §D 확인 동작이지 이 축의 연장이 아니다.

## D. 발견을 세우는 법 — 주장이 아니라 확인

발견은 **한 동작으로 확인 가능한 주장**이어야 한다.

```
[결함|그물|정리] path/file.ts:LINE
주장: 한 문장 — 무엇이, 어떤 입력에서, 어떻게 틀리나
확인: 한 동작 — grep 한 줄 / 파일 한 곳 읽기 / 검사 한 번
결과: 확인됨 | 기각        ← 확인 동작을 **실제로 돌린 뒤** 적는다
근거: 등급이 요구하는 것(바로 아래) — 못 적으면 등급을 내린다
수정안: 한 줄, 코드베이스 관용구 안에서 최소. 여기서 고치지 않는다.
```

★**등급마다 근거가 다르다. 그 근거를 여기서 요구한다** — 등급은 여기서 붙는데 근거
요구가 §C 에 있으면, 관찰을 확인한 것이 곧 등급을 확인한 것처럼 읽힌다(실제로 그렇게
틀렸다: grep 으로 «그 줄이 있다» 를 확인하고 결함을 붙였는데, 그 줄에 **오늘 닿는 것이
0** 이었다).

| 등급 | 무엇인가 | 근거 줄에 적을 것 |
|---|---|---|
| **결함** | 사용자에게 닿는다 | **닿는 경로** — 오늘 **실재하는 것 하나를 이름으로**: 데이터 행 · 호출부 · 유저가 지금 할 수 있는 동작 |
| **그물** | 코드는 지금 맞지만 검사가 못 잡는다 | 그 줄을 되돌리면 **빨개졌어야 할 검사 이름**(못 대면 그게 곧 발견이다) |
| **정리** | 중복·단순화·재사용(동작 안 바뀜) | 같은 판단이 있는 **두 자리** |

★**결함의 문턱은 «이름을 댈 수 있나» 다.** «데이터가 이렇게 들어오면» · «호출부가 생기면»
처럼 **아직 없는 것**에 기대야 문장이 되면 그건 **[그물]** 이다 — 코드는 맞고 검사만
없는 상태이므로 자리가 이미 있다. 반대로 «유저가 앱을 강제 종료한다» 처럼 **오늘 가능한
동작**을 대면 그건 결함이다(조건절이 붙었는지는 상관없다 — 문법이 아니라 실물을 본다).
- ★**확인 동작을 돌리지 않은 발견은 보고하지 않는다.** 이것이 적대적 검증이다 — 사람을
  더 띄우지 않고, diff 를 다시 읽지 않고, 발견마다 동작 하나를 실행한다.
  매니저 구성이면 **매니저가 서브의 «확인» 줄을 직접 돌려** 검증하고 합친다(중복은 하나로).
- 확인 동작을 만들 수 없는 주장(경합·타이밍 등)은 **«의심»** 으로 맨 끝에 한 줄씩.
  확신도 숫자는 적지 않는다 — 자기 채점은 감사할 수 없다. 확인됨/기각/의심 셋뿐이고,
  애매하면 주장을 더 쪼개라.

## E. 보고

보고 끝에 **세 줄**을 반드시 붙인다. 셋 다 «행동을 바꾸는» 줄이다:

```
띄움: N명 (묶음: …)          ← 묶음을 못 적으면 띄울 이유가 없던 것이다
                             매니저 혼자면 «매니저 1명 / 서브 0명», 팬아웃 시 실제 수를 구분
계약: 심볼 N개 / 호출부·구현체 M곳 확인   ← 안 바뀌었으면 «계약 변경 없음»
안 고침: 확인함 (리뷰 전후 대조 — 무엇으로 쟀는지 함께)
```

★**계약 줄만 필수로 올린다**(§C-2). 다섯 축 중 **혼자만 산출물이 숫자**라, 적었는지 안
적었는지가 밖에서 보인다. 나머지 넷은 산문이라 «축을 닫았다» 가 검증되지 않는다 —
항상 초록인 검사는 없는 검사다(§C-1 이 말하는 그것). ★발견이 있어도 이 줄은 면제되지
않는다: 축 2 는 발견을 *찾는* 도구이면서 **안 본 면적을 재는** 도구다.

★**집계 숫자(제기 N·기각 N)는 안 적는다.** 확인/기각은 **발견마다** 붙는 것으로 족하고,
합계는 해석이 안 된다 — 기각 0이 «발견이 좋았다» 인지 «반증을 안 했다» 인지 못 가르고,
어느 쪽이든 할 일이 달라지지 않는다. 행동을 안 바꾸는 관측은 적지 않는다.

아래에 확인된 발견을 **결함 → 그물 → 정리** 순으로. **기각한 것은 적지 않는다** —
사용자가 물으면 목록을 준다.

★**발견 0건이면 §C 다섯 축을 «축이 요구하는 값» 으로 닫는다** — 안 봤는데 0건인 것과
보고도 0건인 것은 다르다. «봤다» 는 산문은 검증할 수 없으니, 축이 원래 시키는 **결과물**을
적는다:

    1 검사가 도나   → 바뀐 줄을 덮는 **검사 이름**(못 대면 그게 발견이다)
    2 이음매       → 계약이 바뀐 심볼과 **호출부 수**(안 바뀌었으면 «계약 변경 없음»)
    3 수정이 낳은  → 이 diff 가 고치기인가 아닌가, 맞으면 무엇에 의존하던 것을 봤나
    4 손 목록      → 새로 생긴 열거·허용 목록의 **개수**(0이면 0)
    5 이웃         → 돌린 **grep 패턴**(발견이 없었으면 «해당 없음»)

## F. 하지 않는 것

- **파일을 쓰지 않는다** — 작업 트리·stash·브랜치·임시 파일 전부.
  `Bash` 는 **읽는 명령만.** 판정은 이름 목록이 아니라 **«이 명령이 무엇을 바꾸나»** 다 —
  아무것도 안 바꾸면 써도 된다(예: `grep`·`sed -n`·`nl`·`cat`·`ls`, 버전 관리가 있으면
  `git diff/show/log/blame`) ·
  기존 검사 실행. **금지**: `>` · `>>` · `tee` · `sed -i` · `perl -i` ·
  `git checkout/stash/reset/apply/commit` · 빌드 산출물을 쓰는 명령.
  검사를 «변이로 뚫어보는» 것도 **머리로** 한다(§C-1 은 이름을 대는 것이지 고치는 게 아니다).
  ★**«안 고쳤다» 를 말로 하지 말고 대조해서 보여라** — 리뷰 **전**에 상태를 한 번 뜨고,
  **끝에** 다시 떠서 같음을 §E 에 적는다. **재는 수단은 대상이 정한다**:
  버전 관리가 있으면 그것(`git status --porcelain` 등), 없으면 대상 파일의
  크기·수정시각 목록이면 된다. **도구를 못 박지 않는 이유**는 리뷰 대상이 늘 레포인 것도
  아니고 늘 git 인 것도 아니어서다 — 못 재는 대상이면 그렇게 적어라(«대조 불가: 이유»).
  ★«못 재니까 생략» 은 안 된다. 생략하면 그 줄이 있던 이유가 사라진다.
- **같은 파일을 두 사람에게 읽히지 않는다.**

## G. 액션 (사용자가 명시했을 때만)

★리뷰 자체는 아무것도 안 고친다. 아래는 사용자가 **명시**한 경우에만, **메인이** 한다 —
서브는 이 플래그를 받지도, 스스로 판단해 고치지도 않는다.

| 플래그 | 배선 | 규칙 |
|---|---|---|
| `--fix` | `Edit`/`Write` 로 작업 트리 적용 | **확인됨만**, 파괴적이므로 적용 전 사용자 승인. 발견별 적용/스킵 선택 |
| `--comment` | github MCP 인라인 PR 코멘트(있으면) | 없으면 마크다운 폴백(§H) |
| `--commit` | `--fix` 적용 후 커밋(버전 관리가 있을 때만) | 메시지에 리뷰 근거 요약. 사용자 승인 후 |

그 수정은 **새 diff 이므로 다시 이 스킬의 대상**이다.

## H. 외부가 실패해도 리뷰는 산다

- **서브 사망** → 나머지 묶음은 그대로 진행, 보고에 «미검토 파일: X» 한 줄.
  어느 파일을 못 봤는지 **이름으로** 남겨라 — «리뷰했다» 가 «그 파일은 아무도 안 읽었다» 를
  덮으면 안 된다.
- ★**매니저를 못 띄우는 환경**(`run_in_background` 가 없는 실행기) → **판단을 먼저 적고
  직접 읽어라.** 몇 명이 필요한지·묶음을 어떻게 잘랐는지를 보고에 그대로 남기고, 읽기는
  묶음 순서대로 혼자 한다. §B 는 «오염을 피하라» 는 규칙이지 «도구가 없으면 리뷰를
  포기하라» 가 아니다 — 규칙이 길을 막으면 그건 규칙의 결함이다.
  (실사용에서 걸렸다: 매니저가 없는 실행기에서 §B 를 지키려니 어느 쪽을 골라도 위반이라
   사람이 따로 길을 내줘야 했다.)
- **MCP·외부 도구 부재** → 마크다운으로 내용을 그대로 반환한다(리뷰를 버리지 않는다).
- **확인 동작이 실패**(검사가 안 돌거나 grep 이 막힘) → 그 발견은 «의심» 으로 내린다.
  검증 실패가 발견을 **지우면** 안 된다 — 그러면 도구가 부실할수록 보고가 깨끗해 보인다.