code-review

코드 리뷰

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

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 확인 동작이지 이 축의 연장이 아니다.