Code reviewer

Code Reviewer v4 — Policy Layer + Native Engine

PR 단위 코드 리뷰 오케스트레이터. v4부터 리뷰 엔진과 정책 레이어를 분리합니다.

리뷰 요청
  │
  ├─ Step 0~1: 베이스 브랜치 + 리뷰 대상 확인
  ├─ Step 2: 엔진 선택 (CLI 감지)
  │    ├─ 경로 A: Claude  → 네이티브 code-review 스킬
  │    ├─ 경로 B: Codex   → 네이티브 codex review
  │    └─ 경로 C: 풀 경로 (네이티브 없음 — Gemini 등)
  └─ Step 3: 정책 레이어 P1~P5 (공통)
       P1 Scope Drift → P2 도메인 보강 패스 → P3 Suppressions
       → P4 Fix-First → P5 통합 보고서

설계 원칙: 네이티브 엔진이 잘하는 일반 리뷰(버그, 보안 기본기, 성능)는 중복 구현하지 않는다. 이 스킬은 네이티브가 안 하는 것만 담당한다.

적용 시점

• 명시적 리뷰 요청 시 ("코드 리뷰 해줘", "review")
• PR 생성 전 (/ship 전)
• 코드 작성 완료 시 자동 제안

---

Step 0: 베이스 브랜치 감지

# 플랫폼 감지
_REMOTE_URL=$(git remote get-url origin 2>/dev/null || echo "unknown")
# 베이스 브랜치 결정
_BASE=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||')
[ -z "$_BASE" ] && git rev-parse --verify origin/main &>/dev/null && _BASE="main"
[ -z "$_BASE" ] && git rev-parse --verify origin/master &>/dev/null && _BASE="master"
[ -z "$_BASE" ] && _BASE="main"
echo "BASE: $_BASE"
echo "BRANCH: $(git branch --show-current 2>/dev/null)"

---

Step 1: 리뷰 대상 확인

1. git branch --show-current로 현재 브랜치 확인.
2. 베이스 브랜치 위에 있으면: "베이스 브랜치에서는 리뷰할 대상이 없습니다." → 중단.
3. git fetch origin $_BASE --quiet && git diff origin/$_BASE --stat 실행.
4. diff가 없으면 동일 메시지 → 중단.

---

Step 2: 엔진 선택

환경	감지 방법	경로
Claude Code	Skill 도구 목록에 code-review 존재	A — 네이티브 위임
Codex CLI	Codex 세션에서 실행 중 (codex CLI 환경)	B — codex review
Gemini 등	위 둘 다 아님	C — 풀 경로

네이티브 엔진 호출이 실패하면 경로 C로 폴백하고, P5 보고서에 폴백 사유를 기록합니다. 사용자가 명시적으로 요청하면("풀 경로로 리뷰", "specialist 리뷰") Claude/Codex에서도 경로 C를 사용합니다.

경로 A — Claude 네이티브 엔진

1. Skill 도구로 code-review 호출 (effort high 권장. 빠른 점검만 원하면 medium)
2. --fix는 사용하지 않음 — 수정 적용은 정책 레이어 P4(Fix-First)가 AUTO-FIX/ASK 분류로 담당
3. ultra는 호출 금지 — /code-review ultra(클라우드 멀티에이전트)는 사용자 트리거 전용(과금). 스킬은 호출하지 않으며 권유 안내도 하지 않는다
4. 네이티브 발견을 정규화하여 수집: {"severity":..., "confidence":N, "path":..., "line":N, "category":..., "summary":..., "source":"native"}

경로 B — Codex 네이티브 엔진

1. codex review --base $_BASE 실행 — 베이스 브랜치 대비 diff 리뷰. 커밋 전 변경만 보려면 codex review --uncommitted (staged/unstaged/untracked 포함)
2. 자동화 파이프라인에서 구조화 출력이 필요하면 codex exec review 사용 (codex review에는 --json 옵션이 없음)
3. 발견을 경로 A와 동일 형식으로 정규화 (source: "native")

경로 C — 풀 경로 (네이티브 없음)

Scope 감지 → Critical Pass → Specialist dispatch → Adversarial Review. 풀 경로 상세 참조. 발견은 source: "full-pass"로 정규화.

경로 C의 Critical Pass는 도메인 체크리스트를 이미 포함하므로 정책 레이어 P2를 생략합니다.

---

Step 3: 정책 레이어 (P1~P5)

엔진 발견을 받아 모든 경로가 공통으로 수행합니다.

P1 — Scope Drift 감지

계획 대비 실제 구현 검증 — 빠진 것과 초과한 것을 찾습니다. 네이티브 엔진에는 없는 검사입니다.

1. 의도 소스 수집:
   • 커밋 메시지: git log origin/$_BASE..HEAD --oneline
   • PR 설명: gh pr view --json body -q .body 2>/dev/null || true
   • TODOS.md (있으면)
2. diff의 변경 파일과 의도를 대비하여 평가:

SCOPE CREEP: 의도에 없는 파일 변경, 미언급 기능/리팩토링 MISSING REQUIREMENTS: 의도에 있지만 diff에 없는 항목

출력:

Scope Check: [CLEAN / DRIFT DETECTED / REQUIREMENTS MISSING]
Intent: <1줄 요약>
Delivered: <1줄 요약>
[불일치 항목 목록]

이 단계는 정보 제공 — 리뷰를 차단하지 않습니다.

P2 — 도메인 보강 패스 (경로 A/B만)

네이티브 엔진이 다루지 않는 이 레포 고유 체크리스트만 diff에 적용합니다.

LLM 출력 신뢰 경계

• LLM 생성 값 검증 없이 DB 저장/메일러 전달
• 타입/형태 체크 없이 구조화 도구 출력 수용
• 허용 목록 없는 LLM 생성 URL fetch (SSRF)
• 소독 없이 벡터 DB 저장 (저장된 프롬프트 인젝션)

Enum & 값 완전성

새 enum 값/상태/타입 상수 추가 시:

• 모든 소비자 추적. 해당 값으로 switch/filter/표시하는 파일을 Grep → Read.
• 허용 목록/필터 배열 확인. 형제 값을 포함하는 배열에 새 값 포함 여부.
• case/if-elsif 체인. 새 값이 잘못된 기본값으로 fall-through 되는지.

비동기/동기 혼합 (Python)

• async def 안 동기 subprocess.run, open, requests.get → asyncio.to_thread 사용
• async에서 time.sleep → asyncio.sleep
• async 컨텍스트에서 run_in_executor 없는 동기 DB 호출

컬럼/필드명 안전

• ORM 쿼리(.select, .eq, .gte, .order)의 컬럼명이 실제 스키마와 일치하는지
• .get() 호출이 실제 선택된 컬럼명 사용

발견은 source: "domain"으로 정규화. 네이티브 발견과 핑거프린트 ({path}:{line}:{category})가 겹치면 최고 confidence 유지 + 1 (최대 10), "ENGINE+DOMAIN CONFIRMED" 태그.

P3 — Suppressions

checklists/suppressions.md를 읽고, 해당 패턴과 일치하는 발견은 보고하지 않습니다.

P4 — Fix-First Review

모든 발견에 조치를 취합니다 — 보고만 하지 않습니다.

분류 기준

AUTO-FIX (물어보지 않고 수정):         ASK (사람 판단 필요):
├─ 죽은 코드 / 미사용 변수              ├─ 보안 (인증, XSS, 인젝션)
├─ N+1 쿼리 (eager loading 추가)        ├─ 경쟁 조건
├─ 코드와 불일치하는 주석               ├─ 설계 결정
├─ 매직 넘버 → 명명 상수               ├─ 대규모 수정 (>20줄)
├─ LLM 출력 검증 누락                   ├─ Enum 완전성
├─ 버전/경로 불일치                     ├─ 기능 제거
├─ 할당 후 미읽는 변수                  └─ 사용자 가시 동작 변경
└─ 인라인 스타일, O(n*m) 뷰 룩업

원칙: 시니어 엔지니어가 토론 없이 적용할 수정이면 AUTO-FIX. 합리적 의견이 갈리면 ASK.

P4a: 분류

각 발견을 AUTO-FIX 또는 ASK로 분류.

P4b: AUTO-FIX 적용

[AUTO-FIXED] [file:line] 문제 → 수정 내용

P4c: ASK 일괄 질문

ASK 항목이 있으면 하나의 질문으로 일괄:

자동 수정 5건 완료. 2건은 판단이 필요합니다:

1. [CRITICAL] (confidence: 9/10) app/models/user.py:42 — 상태 전이 경쟁 조건
   수정: WHERE status = 'draft' 추가
   → A) 수정  B) 건너뛰기

2. [INFORMATIONAL] (confidence: 7/10) app/services/ai.py:88 — LLM 출력 타입 미검증
   수정: JSON 스키마 검증 추가
   → A) 수정  B) 건너뛰기

RECOMMENDATION: 모두 수정 권장 — #1은 실제 경쟁 조건, #2는 침묵 데이터 손상 방지.

P4d: 승인된 수정 적용

사용자가 "수정"을 선택한 항목 적용.

P5 — 통합 보고서

═══════════════════════════════════════
Pre-Landing Review: N issues (X critical, Y informational)
Engine: [native:claude code-review / native:codex review / full-pass]
Specialist: Z개 디스패치 (names)        ← 경로 C만
═══════════════════════════════════════

SCOPE CHECK: [CLEAN / DRIFT / MISSING]
Intent: ...
Delivered: ...

AUTO-FIXED: (K건)
- [file:line] 문제 → 수정
...

NEEDS INPUT: (M건)
- [결과 또는 "사용자 승인 완료"]

FINDINGS: (N건 — source 표기: native / domain / full-pass)
[각 발견 — confidence 순 내림차순]

ADVERSARIAL REVIEW:                     ← 경로 C만
[발견 또는 "추가 이슈 없음"]

───────────────────────────────────────
PR Quality Score: X/10
(10 - critical×2 - informational×0.5, 최소 0)
═══════════════════════════════════════

---

Confidence 점수

모든 발견에 신뢰도 점수(1-10)를 포함합니다.

점수	의미	표시 규칙
9-10	구체적 코드 읽어서 검증. 버그/취약점 입증.	정상 표시
7-8	높은 신뢰도 패턴 매치.	정상 표시
5-6	중간. 오탐 가능.	경고 표시: "중간 신뢰도, 실제 이슈인지 확인"
3-4	낮음. 의심스럽지만 괜찮을 수도.	부록에만 포함
1-2	추측.	P0 심각도일 때만 보고

발견 형식: [심각도] (confidence: N/10) file:line — 설명

---

풀 경로 상세 (경로 C)

네이티브 엔진이 없는 환경(Gemini 등) 또는 네이티브 호출 실패 시 사용합니다.

C-1: Scope 감지

# 변경된 파일 분석
_DIFF_STAT=$(git diff origin/$_BASE --stat)
_DIFF_LINES=$(echo "$_DIFF_STAT" | tail -1 | grep -oE '[0-9]+ insertion' | grep -oE '[0-9]+' || echo "0")
echo "DIFF_LINES: $_DIFF_LINES"

# 스코프 시그널
_HAS_BACKEND=false; _HAS_FRONTEND=false; _HAS_API=false
_HAS_MIGRATIONS=false; _HAS_AUTH=false
_CHANGED_FILES=$(git diff origin/$_BASE --name-only)
echo "$_CHANGED_FILES" | grep -qiE '\.(py|rb|java|go|cs|rs|kt)$' && _HAS_BACKEND=true
echo "$_CHANGED_FILES" | grep -qiE '\.(tsx?|jsx?|vue|svelte|css|scss)$' && _HAS_FRONTEND=true
echo "$_CHANGED_FILES" | grep -qiE '(controller|route|endpoint|api|handler)' && _HAS_API=true
echo "$_CHANGED_FILES" | grep -qiE '(migrat|schema|alembic|flyway)' && _HAS_MIGRATIONS=true
echo "$_CHANGED_FILES" | grep -qiE '(auth|login|session|token|permission|role)' && _HAS_AUTH=true

echo "SCOPE: backend=$_HAS_BACKEND frontend=$_HAS_FRONTEND api=$_HAS_API migrations=$_HAS_MIGRATIONS auth=$_HAS_AUTH"

C-2: Critical Pass (핵심 리뷰)

git diff origin/$_BASE의 전체 diff를 가져와 아래 카테고리를 검사합니다.

Pass 1 — CRITICAL (최고 심각도)

SQL & 데이터 안전

• 문자열 보간 SQL (.to_i/.to_f여도 파라미터화 쿼리 사용)
• TOCTOU 경쟁: check-then-set → 원자적 WHERE + update_all
• 모델 검증 우회 직접 DB 쓰기 (update_column, QuerySet.update, raw query)
• N+1 쿼리: 루프에서 사용되는 연관에 eager loading 누락

Race Condition & 동시성

• 유니크 제약/중복 키 에러 없는 read-check-write
• 유니크 DB 인덱스 없는 find-or-create
• 원자적 WHERE 없는 상태 전이
• 사용자 제어 데이터에 안전하지 않은 HTML 렌더링 (XSS)

LLM 출력 신뢰 경계

• P2 도메인 보강 패스와 동일 체크리스트 적용

Shell Injection

• subprocess.run(shell=True) + f-string 보간 → 인자 배열 사용
• os.system()에 변수 보간 → subprocess.run() 인자 배열
• LLM 생성 코드에 대한 eval()/exec() (샌드박싱 없음)

Enum & 값 완전성

• P2 도메인 보강 패스와 동일 체크리스트 적용

Pass 2 — INFORMATIONAL

비동기/동기 혼합 (Python) · 컬럼/필드명 안전

• P2 도메인 보강 패스와 동일 체크리스트 적용

타입 정의

• Python: 타입 힌트 누락 (반환/파라미터)
• TypeScript: any 사용, 명확한 인터페이스 미정의

CI/CD Pipeline

• 워크플로우 변경 시 빌드 도구 버전, 아티팩트 경로, 시크릿 사용 확인
• 버전 태그 형식 일관성 (v1.2.3 vs 1.2.3)

C-3: Specialist 병렬 Dispatch

50줄 미만 diff

"소규모 diff ($_DIFF_LINES줄) — specialist 생략." → 정책 레이어로.

Specialist 선택

Specialist	조건	파일
Testing	항상	specialists/testing.md
Maintainability	항상	specialists/maintainability.md
Security	auth 변경 또는 백엔드 > 100줄	specialists/security.md
Performance	백엔드 또는 프론트엔드	specialists/performance.md
Data Migration	마이그레이션 파일 변경	specialists/data-migration.md
API Contract	API 파일 변경	specialists/api-contract.md
Design	프론트엔드 파일 변경	specialists/design.md

Dispatch

선택된 specialist별로 Agent 도구를 사용하여 단일 메시지에 모든 subagent를 동시 호출합니다.

각 subagent 프롬프트:

[specialist name] specialist 코드 리뷰어로서 활동하세요.
아래 체크리스트를 읽고, `git diff origin/[base]`로 diff를 가져와 체크리스트를 적용하세요.

발견 시 한 줄에 하나씩 JSON 출력:
{"severity":"CRITICAL|INFORMATIONAL","confidence":N,"path":"file","line":N,"category":"[category]","summary":"설명","fix":"수정 방법","specialist":"[name]"}

발견 없으면: NO FINDINGS

체크리스트:
[체크리스트 내용]

결과 수집 & 중복 제거

1. 각 specialist 출력에서 JSON 파싱 (NO FINDINGS → 건너뛰기)
2. 핑거프린트: {path}:{line}:{category}
3. 동일 핑거프린트 → 최고 confidence 유지, confidence +1 (최대 10)
4. 태그: "MULTI-SPECIALIST CONFIRMED (specialist1 + specialist2)"

C-4: Adversarial Review (적대적 리뷰)

별도 subagent를 디스패치합니다. 체크리스트 편향 없는 신선한 시각.

프롬프트:

이 브랜치의 diff를 `git diff origin/[base]`로 읽으세요.
공격자와 카오스 엔지니어의 관점으로 이 코드가 프로덕션에서 실패할 방법을 찾으세요.
엣지 케이스, 경쟁 조건, 보안 취약점, 리소스 누수, 침묵 데이터 손상, 에러 삼킴.
칭찬 없이 문제만. 각 발견을 FIXABLE(수정 방법 알음) 또는 INVESTIGATE(사람 판단 필요)로 분류.

---

포세이돈(agent-team) 연동

agent-team Step 5(자재검사)의 reviewer teammate는 Skill 도구 접근이 보장되지 않으므로 경로 C 체크리스트(C-2 + specialist)를 teammate 프롬프트에 임베드하여 직접 적용합니다. 네이티브 엔진 위임은 메인 세션에서 이 스킬을 직접 실행할 때만 사용합니다.

---

검증 원칙

• "안전하다"고 주장하려면 → 구체적 줄 번호 인용
• "다른 곳에서 처리됨"이라면 → 해당 코드를 읽고 인용
• "테스트가 커버함"이라면 → 테스트 파일과 메서드명 명시
• "아마 처리됨", "아마 테스트됨" → 금지. 검증하거나 미확인 표시.

---

다음 단계 안내

✅ 코드 리뷰 완료! (결과: {PASS/CONDITIONAL/FAIL})
   PR Quality Score: X/10

다음 단계 (선택):
  /minos          → Playwright 자동 테스트
  security-reviewer    → 보안 전문 심층 리뷰
  /commit              → 변경사항 커밋
  /ship                → PR 생성

---

체크리스트 요약

Critical (반드시 통과)

• SQL Injection 방지 (파라미터화 쿼리)
• Race Condition 없음 (원자적 연산)
• LLM 출력 검증
• Shell Injection 방지
• Enum 값 완전성
• XSS 방지

High (강력 권장)

• 타입 힌트/인터페이스 완벽
• 단일 책임 원칙 (SRP)
• 중복 코드 제거 (DRY)

Medium (권장)

• 복잡한 로직에 "왜" 주석
• 명확한 변수/함수명
• 에러 핸들링 적절

Low (최적화)

• N+1 쿼리 방지
• 메모이제이션
• 번들 크기 최적화

---

Severity Levels

Level	표시	조치
Critical	FAIL	Merge 차단, Fix-First ASK
Major	WARN	Fix-First AUTO-FIX 또는 ASK
Minor	INFO	Fix-First AUTO-FIX
Nitpick	NOTE	Suppression 확인 후 무시 가능

---

버전: 4.0.0 (Policy Layer Edition)