코드 리뷰·버그 진단·diff/브랜치/PR 리뷰 방법론. (1) '이 버그 왜 나지', '이거 왜 안 돼', '원인 찾아줘' 류 디버깅, (2) '코드 리뷰해줘', '이 수정 괜찮아?', '더 나은 방법 있어?' 류 단건 리뷰, (3) '이 diff 리뷰해줘', '브랜치 리뷰', 'PR 리뷰해줘', '이 커밋들 봐줘', '변경 전체 체계적으로 리뷰' 류 diff/브랜치 전체 리뷰, (4) '꼼꼼히/딥하게/멀티에이전트로 리뷰' 류 고강도 적대적 검증 리뷰. 단건 버그는 솔로로 근본 원인→인접 확장→최소 수정을 짚고, 넓은 diff/브랜치는 correctness·simplification·efficiency·test-coverage 4차원을 서브에이전트 팬아웃으로 리뷰한 뒤 회의론자 서브가 각 발견을 반증(다수 반증이면 폐기)해 심각도 순으로 구조화 보고한다. --fix/--comment/--commit 액션 지원.
Scanned 9/3/2026
Install to Claude Code
Skills Directorynpx -y skills add tigu77/tiguclaw --skill code-review --agent claude-codeInstalls into .claude/skills of the current project.
Are you the author of Code Review?
Add the live security badge to your README — it updates automatically with every re-scan.
[](https://www.skillsdirectory.com/skills/tigu77-code-review)More formats (shields.io, HTML) on the badges page.
---
name: code-review
description: "코드 리뷰·버그 진단·diff/브랜치/PR 리뷰 방법론. (1) '이 버그 왜 나지', '이거 왜 안 돼', '원인 찾아줘' 류 디버깅, (2) '코드 리뷰해줘', '이 수정 괜찮아?', '더 나은 방법 있어?' 류 단건 리뷰, (3) '이 diff 리뷰해줘', '브랜치 리뷰', 'PR 리뷰해줘', '이 커밋들 봐줘', '변경 전체 체계적으로 리뷰' 류 diff/브랜치 전체 리뷰, (4) '꼼꼼히/딥하게/멀티에이전트로 리뷰' 류 고강도 적대적 검증 리뷰. 단건 버그는 솔로로 근본 원인→인접 확장→최소 수정을 짚고, 넓은 diff/브랜치는 correctness·simplification·efficiency·test-coverage 4차원을 서브에이전트 팬아웃으로 리뷰한 뒤 회의론자 서브가 각 발견을 반증(다수 반증이면 폐기)해 심각도 순으로 구조화 보고한다. --fix/--comment/--commit 액션 지원."
context-menu:
- on: activity
label: "이 활동 코드리뷰 실행"
group: skills
---
# 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(근본 원인)로 돌아가라 — 두 번째 보정은 이 셋을 건너뛴 신호다.
### A4. 견고한 방향 (짧게 — 옵션)
- 최소 수정과 *별개로* 재발을 줄이는 방향을 1~3줄로 절제해 덧붙인다: 진실 소스 정합 / 검증 위치(클라 vs 서버) / 흩어진 상태를 한 컨텍스트로 묶기 등.
- ⚠️ **분량 절제.** 최소 패치를 원하는 사용자에겐 장문 구조 제안이 소음이다. correctness(A1·A2)는 항상, 깊이(A4)는 짧게.
---
## B. 리뷰 워크플로우 (범위·강도 선택 — effort 게이팅)
### B0. 대상 수집 (Bash)
리뷰 대상 diff 를 먼저 확정한다. 어댑터(claude/codex/openai) 무관, 전부 `Bash`.
- 단건/워킹트리: `git diff`, `git diff --staged`
- 커밋 범위/브랜치: `git log --oneline <base>..HEAD`, `git diff <base>...HEAD`
- 특정 커밋: `git show <sha>`
- PR: base 브랜치 대비 `git diff <base>...<head>` (github MCP 있으면 PR 메타도 조회)
변경 규모(파일 수·헝크 수)와 요청 문구로 **effort 레벨을 판정**한다(B1).
### B1. ★effort 게이팅 — 언제 솔로, 언제 팬아웃
| effort | 트리거 | 실행 형태 | 리뷰 차원 서브 | 회의론자/발견 |
|---|---|---|---|---|
| **solo** (기본·low·medium) | effort 무언급, "빠르게", 단건 버그, 작은 diff(≲2파일) | **메인이 직접**(팬아웃 0) | 0 | 0 |
| **high** | "high/꼼꼼히/제대로", 넓은 diff·브랜치·PR(다파일) | **매니저에게 넘겨 팬아웃** | 차원별 1명(§B2) | 2명(§B3) |
| **ultra** | "ultra/딥/멀티에이전트/샅샅이" | **매니저에게 넘겨 와이드 팬아웃** | 차원 × 영역 분할(4~8명) | 3~5명, 2라운드 옵션 |
- **기본은 솔로다.** effort 명시·넓은 범위·명시 요청이 없으면 절대 팬아웃하지 마라 — 매 리뷰 과잉 오케스트레이션은 낭비 게이트 위반.
- solo 는 메인이 §A 방법론으로 직접 읽고 보고한다(발견 1~수개, 고확신만).
- 범위가 넓은데 effort 무언급이면 "넓은 변경입니다. 꼼꼼히(high) 갈까요?" 한 줄로 확인 후 결정한다.
### B2. 차원 팬아웃 (high/ultra) — `spawn_agent`
4개 리뷰 차원을 **병렬 서브에이전트**로 나눈다.
> ★**반드시 `spawn_agent(name="code-review", …)` 로 띄운다.** 범용/`quick`/`general` 등 다른 서브에이전트로 위임하지 마라 — 그러면 **high(opus) 티어와 §A 방법론 자동 로드를 잃는다**(리뷰 품질 직결). 차원별로 **프롬프트(모드)만** 바꾸고 `name` 은 항상 `"code-review"` 로 고정.
차원별 프롬프트 템플릿(name 고정, 모드만 변경) → `references/review-orchestration.md`.
- `correctness` — 로직 오류·엣지케이스·회귀·§A2 인접 형제버그
- `simplification` / reuse — 중복·재발명·불필요 추상화·기존 유틸 재사용 여지
- `efficiency` — 불필요 재계산·N+1·핫경로 낭비·컨텍스트 위생
- `test-coverage` — 새 경로에 테스트 공백, 회귀 위험 지점
각 차원 서브에게: 대상 diff 범위(git 명령), 담당 차원, "§A 방법론(근본원인·인접확장·관용구 최소수정)을 지켜 발견을 구조화 findings 로 반환하라". 프롬프트 템플릿 → `references/review-orchestration.md`.
ultra 는 대상이 크면 차원을 **영역(파일 그룹)별로 더 쪼개** 서브 수를 늘린다.
### B3. ★적대적 검증 (high/ultra) — 회의론자 팬아웃
차원 서브가 모은 **각 발견마다** 독립 회의론자 서브 N명을 띄워 *반증을 시도*시킨다. 회의론자도 **반드시 `spawn_agent(name="code-review", …)`** — 프롬프트만 "이 발견을 반증하라" 모드(범용 서브 금지, 위 ★규칙 동일).
- 회의론자 프롬프트: "다음 발견이 **틀렸음을 입증하라**(그럴듯하지만 거짓인 발견 제거가 목적). 코드를 직접 읽어 반례를 찾아라. 반증 성공 또는 불확실하면 `refuted: true`, 발견이 견고하면 `refuted: false`. 이유 1~2줄." → `references/review-orchestration.md`
- **집계**: 발견별 회의론자 표결. **과반이 `refuted:true` → 발견 폐기.** 살아남으면 verdict 부여:
- refute 0표 → `CONFIRMED`
- refute 소수(과반 미만) → `PLAUSIBLE`
- 폐기된 발견은 최종 보고에서 뺀다(원하면 "검토 중 기각: N건" 한 줄만 남긴다).
### B4. 집계·랭킹·보고 (메인)
살아남은 발견을 **심각도 순**으로 정렬해 구조화 마크다운으로 보고한다(§C). 심각도 = correctness > 나머지, 그 안에서 파급·데이터손실·회귀 위험 순.
> ★**팬아웃이 필요하면 먼저 매니저에게 넘긴다** (2026-08-24 지침 검토). 헌법이 못박은
> 판정은 하나다 — **한 작업에 서브에이전트가 2명 이상 필요하면 `run_in_background` 로
> 매니저에게 통째로 넘기고, 팬아웃은 그 안에서 한다.** 종전엔 이 줄이 "오케스트레이션은
> **메인 턴이 직접** 수행한다" 였는데, 그건 **그 규칙이 태어난 사고 그 자체**다:
> 2026-08-08 에 전경 10명 팬아웃으로 대화가 **8분 37초** 멈췄다. 이 스킬은 그 사고
> **이전**(2026-07-19)에 쓰였고, 규칙이 생긴 뒤 아무도 대조하지 않았다.
> ★depth 1 제약은 그대로다: 서브에이전트는 다시 spawn 못 하므로, **매니저**가 차원·회의론자
> 팬아웃과 집계를 한다. 서브에게 "네가 회의론자를 또 띄워라" 는 여전히 금지.
---
## C. 구조화 findings 포맷 (채널 무관 — 대시보드·텔레그램 동형)
발견당 아래 필드. 표(overview) + 리스트(상세) 병용. 텔레그램은 리스트가 더 읽힌다.
```
### 🔴 #1 correctness · CONFIRMED
- **file:line** — src/foo.ts:42
- **summary** — 한 줄 요지(근본 원인, 증상 아님)
- **failure_scenario** — 구체 입력/상태 → 오작동. 예: "resume 세션 jsonl 에 처리불가 이미지 tool_result 가 있으면 이후 모든 턴 400"
- **fix** — 관용구 정합 최소 수정(어느 줄 어떻게). §A3
- (옵션) **hardening** — 재발 방지 1~2줄. §A4
```
- category: `correctness | simplification | efficiency | test-coverage`
- verdict: `CONFIRMED | PLAUSIBLE`(적대적 검증 거친 경우만; solo 는 verdict 생략 또는 CONFIRMED)
- severity 아이콘: 🔴 correctness/데이터손실 · 🟡 회귀위험 · 🔵 개선(simpl/eff) · ⚪ 테스트공백
- 맨 위 1줄 요약: "N건(🔴x · 🟡y · 🔵z), 기각 m건".
세부 스키마·JSON 형태 → `references/review-orchestration.md`.
---
## D. 액션 (요청 시)
| 플래그 | 배선 | 규칙 |
|---|---|---|
| `--fix` | **file-ops** `Edit`/`Write` 로 워킹트리 적용 | **CONFIRMED 만**, 파괴적이므로 적용 전 사용자 승인. 발견별로 적용/스킵 선택 가능 |
| `--comment` | **github MCP** 인라인 PR 코멘트(있으면) | MCP 부재 시 **마크다운 폴백**(§E) — 리뷰 본문을 그대로 반환 |
| `--commit` | `--fix` 적용 후 `Bash` `git commit` | 커밋 메시지에 리뷰 근거 요약. 사용자 승인 후 |
---
## E. Graceful degradation (외부 실패가 리뷰를 죽이지 않게)
- **github MCP 부재/실패** → `--comment` 는 마크다운 findings 로 폴백. 리뷰 자체는 성공.
- **회의론자 서브 사망/에러** → 그 표만 빼고 남은 표로 집계 계속. 표가 전멸하면 발견을 `PLAUSIBLE` 로 남기고 "검증 불가" 주석.
- **차원 서브 사망** → 다른 차원은 그대로 진행, 보고에 "미검토 차원: X" 한 줄.
- **git 대상 모호**(base 불명 등) → 추측 말고 사용자에게 base/범위 한 줄 확인.
---
## 요약 원칙
> **질(§A)**: 근본 원인 정확히 → 인접 필드/경로 확장 점검(필수) → 관용구 최소 수정 → 견고한 방향 짧게.
> **범위(§B)**: 기본은 솔로. 넓은 diff·high/ultra·명시 요청일 때만 차원 팬아웃 + 회의론자 적대 검증(과반 반증이면 폐기).
> 간결하되 형제 버그를 남기지 않고, 그럴듯하지만 틀린 발견을 흘리지 않는다.
Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.
No comments yet. Be the first to comment!
