code-review

Code Review · 버그 진단 + diff/브랜치 리뷰 방법론

★왜 빌트인인가 — 파리티다 (2026-08-30 사용자 결정). 이 스킬엔 tiguclaw 고유 지식이 거의 없다(실측: 160줄 중 2건, 그마저 "어댑터 무관" 이라는 면책 문구다). 그래서 "일반적인 방법론이니 빼도 되지 않나" 로 읽히기 쉬운데 반대다 — Claude Code 가 코드 리뷰를 빌트인으로 주므로, 없으면 1번 원칙(슈퍼셋)의 누락 = 버그다.

즉 빌트인 자격은 축이 둘이다: ①tiguclaw 고유 지식을 담거나 ②Claude Code 파리티. 이건 ②다. 고유 밀도로만 재면 틀린 결론이 나온다 — 실제로 한 번 그랬다.

두 겹으로 동작한다. 아래 §A 방법론(발견의 질)은 항상 적용되고, §B 워크플로우(리뷰의 범위·강도)는 요청에 맞춰 선택한다. 간결함을 유지하되 correctness 는 절대 놓치지 않는다.

---

A. 발견 방법론 (모든 발견이 통과해야 하는 질 기준 — 절대 보존)

솔로든 팬아웃이든, 리뷰 차원 서브든, 각 발견은 아래를 만족해야 한다.

A1. 근본 원인 진단 (증상 아닌 원인)

• 증상("모드가 Normal 로 나감")이 아니라 왜 그 값이 그렇게 되는지 메커니즘을 짚는다. 생성·전달·소비 지점을 추적해 실제 원인을 특정한다.
• "여기서 채워지고 → 저기서 재계산되어 → 값이 섞인다" 처럼 경로로 설명한다. 추측 금지 — 코드를 읽고 확정한다.

A2. ★확장 점검 (correctness — 항상 한다)

• 같은 근본 원인이 인접한 필드·경로·호출부에도 있는지 반드시 확인한다. 하나만 고치고 형제 버그를 남기지 마라.
• 예: GameMode 가 "종료 시점 재계산"이라 stale 이면 — 같은 방식으로 채워지는 Round·Level 도 stale 아닌가? 를 반드시 본다.
• 체크리스트: "이 값이 잘못됐다면, 같은 패턴으로 만들어지는 다른 값들도 같은 함정에 빠지지 않나?" — 명시적으로 훑는다. 취향이 아니라 정확성이다.

★위가 값을 따라가는 축이라면, 아래는 변경을 따라가는 축이다. 2차 결함은 대부분 여기서 난다 — A를 바꾸고 A에 의존하던 B를 안 본 것. 수정을 제안·검토할 때 「무엇을 바꿨나」에서 「무엇을 다시 봐야 하나」가 자동으로 따라 나와야 한다:

바꾼 것	전수로 다시 봐야 하는 것
계약 — 시그니처·반환값·throw 여부·에러 타입	그 함수의 호출부 전부. 특히 반환을 안 쓰던 곳, try 로 안 감싼 곳(안 던지던 게 던지기 시작하면 그 경로가 죽는다)
조건을 반전·확대했다	그 조건에 도달하는 입력 전부. ★파급이 가장 크다 — 조건이 바뀌면 거기 들어오던 모든 것의 의미가 같이 바뀐다
새 값을 만들었다 — 상태·에러 종류·로그 레벨·enum 항목	그 값을 분기·열거·필터하는 곳 전부. 열거에서 빠지면 그 값만 조용히 버려진다(에러 없이)
새 가드·검증을 달았다	같은 것을 받는 진입점 전부. 한 경로에만 달면 나머지는 그냥 통과한다

대개 grep 한 번이면 보인다 — 못 보는 게 아니라 안 보는 것이다.

• ★테스트가 초록인 것은 이 점검을 대신해주지 않는다. 검사는 만든 사람이 생각한 것만 지킨다 — 생각 못 한 것은 검사도 못 본다. 그래서 확장 점검은 스위트에 맡기지 말고 읽어서 한다(그리고 그게 B3 적대적 검증이 필요한 이유다).

A3. 최소 수정 (관용구 정합)

• 코드베이스의 기존 관용구·패턴에 맞춰 수정한다(이미 xxxCache 패턴이 있으면 그걸 따른다). 새 추상화를 함부로 들이지 않는다.
• 범위를 최소화하고 정확히 어느 파일·어느 줄을 어떻게 바꾸는지 명시한다.
• ★고치기 전에 셋을 묻는다 — 「누가 정하나 · 어디 사나 · 언제까지 사나」. 그 값·판단의 주인이 누구인지(사용자 설정인가, 코드 상수인가, 외부가 주는 값인가), 어느 계층에 살아야 하는지, 언제까지 유효한지. 하나라도 답을 못 하면 그 수정은 증상 자리에 놓인 것이고 곧 두 번째 보정을 부른다. ★방금 고친 곳을 또 만지고 있다면 패치를 하나 더 얹지 말고 A1(근본 원인)로 돌아가라 — 두 번째 보정은 이 셋을 건너뛴 신호다.