review-assistant

name	review-assistant
description	PR/diff를 기능 단위로 재구성하고, 기능별 리뷰 축을 병렬로 펼쳐 리뷰 포인트를 발굴한 뒤, 각 포인트를 코드/테스트/런타임 증거로 검증해 확정 finding을 만든다. Triggers: - "리뷰해줘" - "PR 리뷰" - "코드리뷰" - "전반적으로 리뷰 포인트 잡아줘" - "기능 단위로 리뷰해줘" - "review assistant"

Review Assistant

Purpose

이 스킬은 단순히 변경 파일을 훑는 리뷰가 아니라, PR/diff를 기능 단위로 재구성한 뒤 각 기능에 대해 correctness, performance, concurrency, synchronization, consistency, tests, rules 등을 병렬적으로 검토해 리뷰 포인트를 발굴한다.

각 리뷰 포인트는 deep review 이후 반드시 검증 단계를 거쳐야 한다. 코드만 보고 추측한 내용은 finding으로 확정하지 않는다.

Core Rules

• 리뷰 요청은 기본적으로 read-only다. 사용자가 명시적으로 "고쳐줘", "반영해줘"라고 하지 않으면 코드를 수정하지 않는다.
• 사용자가 명시적으로 "PR에 남겨줘", "GitHub에 코멘트 달아줘"라고 하지 않으면 외부에 리뷰를 게시하지 않는다.
• changed file 목록을 그대로 리뷰하지 않는다. 먼저 기능 단위로 재구성한다.
• finding은 검증 가능한 문제만 올린다. 취향, 추측, 약한 가능성은 question 또는 note로 낮춘다.
• no findings일 때도 어떤 기능/축을 확인했는지 남긴다.

Phase 1. Scope Lock

리뷰 기준을 먼저 고정한다.

• current branch 확인
• base branch는 기본적으로 origin/develop으로 둔다.
• PR 번호가 있으면 PR title/body/base branch/changed files 확인
• PR의 base가 develop이 아닌 경우에만 명시적으로 기록하고 그 기준을 따른다.
• origin/develop...HEAD 또는 PR merge-base 기준으로 diff 범위 확정
• merge-base SHA를 기록한다.
• 삭제된 파일의 이전 내용, 삭제 전 import, 삭제 전 symbol은 origin/develop:path가 아니라 merge-base snapshot에서 확인한다. PR이 이미 merge되었거나 origin/develop이 이동한 경우 origin/develop:path는 삭제 전 파일을 보장하지 않는다.
• 관련 AGENTS.md, package-level guide, docs 확인
• 리뷰-only인지, 게시까지 원하는지, 수정까지 원하는지 구분

Phase 2. Feature Decomposition

파일 단위가 아니라 기능 단위로 변경을 묶는다.

각 기능마다 다음을 적는다:

• 사용자 경로
• 서버/API 경로
• 상태/store/storage 경로
• DB/transaction 경로
• analytics/history/experiment 경로
• observability/logging/metrics 경로
• 배포/generated artifact 경로
• 테스트 경로

예시:

Feature A: PDF translation font size setting
- UI: translation font size control
- Storage: translationFontSize / translationFontSizeEnabled
- Sync: fontSizeChanged listener
- Risk: global font size path와 분리 여부

Phase 3. Change-Type Impact Pass

기능별 matrix를 돌리기 전에 변경 유형별 영향도를 먼저 본다.

3.1 삭제 변경: Too Much / Too Little 양방향 검토

삭제 리뷰는 두 방향을 모두 확인한다.

Deleted Code Safety Check

삭제된 코드가 아직 필요한 경로에서 쓰이던 것은 아닌지 확인한다.

• 정적 import/export
• 동적 import
• string-based route/action/event key
• feature flag / experiment branch
• i18n key
• CSS selector / DOM selector
• background job / cron / webhook
• generated bundle / public artifact

Orphaned Dead Code Sweep

삭제된 코드와 연결되어 있었지만 함께 삭제되지 않아 이제 아무 곳에서도 쓰이지 않는 고아 코드가 남았는지 확인한다.

확인 대상:

• helper function
• component
• hook/context
• constant/type
• CSS class
• asset
• i18n key
• analytics/history event
• experiment branch
• route/API helper
• DB query helper
• mock/test fixture
• barrel export/index export
• generated/public artifact

검토 방식:

• 삭제된 symbol/key/class/event 이름에서 연결된 주변 symbol을 추출한다.
• rg로 exact usage를 찾는다.
• import/export graph를 확인한다.
• string key 기반 사용처는 별도 검색한다.
• 남은 코드가 실제 entrypoint에서 reachable한지 확인한다.
• 삭제 전 코드 내용은 merge-base snapshot에서 읽는다.
• reachable하지 않으면 orphaned dead code finding 후보로 올린다.
• 테스트 전용 fixture나 문서 예시는 목적이 있으면 dead code로 보지 않는다.

3.2 추가 변경: Connected Feature Impact

새 코드가 기존 기능에 끼어드는 지점을 찾는다.

• shared util
• global state
• middleware
• provider
• listener
• API client
• DB write
• analytics event
• experiment assignment
• browser/extension runtime hook

확인할 영향:

• 기존 사용자 플로우 변화
• 기존 상태 동기화 변화
• 성능/비용 증가
• race window
• 권한/보안 경계 변화
• analytics/history 오염
• 테스트 커버리지 누락
• web/chrome/server/mobile 간 영향

Phase 4. Parallel Review Point Mapping

기능별로 아래 축을 병렬로 검토한다. 가능하면 독립 축은 subagent로 나눠 동시에 수행한다.

각 축은 반드시 다음 중 하나를 남긴다:

• finding 후보
• question 후보
• no issue 판단 근거
• 해당 없음 사유

Review axes:

• Correctness: 기능 요구사항이 실제로 만족되는가
• Performance/Cost: 불필요한 반복 호출, 렌더링, DB/API 비용이 생기는가
• Concurrency: race, 중복 실행, transaction boundary 문제가 있는가
• Synchronization: UI/store/storage/server 상태가 어긋날 수 있는가
• Data Consistency: DB 상태, cache, billing, subscription, generated data가 정합적인가
• Error/Recovery: 실패, rollback, retry, partial success 경로가 안전한가
• Security/Auth: 권한, 직접 접근, browser-direct path, presigned URL, tenant boundary가 안전한가
• Observability: 로그/metric이 너무 시끄럽거나 cardinality가 높거나 debug value를 잃지 않는가
• Tests: 핵심 경로, regression, edge case가 테스트로 잠겨 있는가
• Project Rules: AGENTS.md, docs, i18n, analytics, experiment, coding style을 지키는가
• Deployment Artifacts: generated bundle/public artifact가 실제 배포 경로와 일치하는가

Phase 5. Review Point Merge

병렬 결과를 합친다.

• 중복 후보 병합
• 같은 root cause를 하나로 묶기
• blocking / non-blocking / question / no-issue로 분류
• 증거가 약한 후보는 finding으로 올리지 않기
• 기능별로 빠진 축이 없는지 확인

Phase 6. Deep Review Per Point

각 후보 포인트를 세부 검토한다.

• 관련 call site 추적
• caller/callee 계약 확인
• 변경 전후 diff 비교
• 상태 전파 순서 확인
• async ordering 확인
• transaction/rollback boundary 확인
• feature flag/experiment 분기 확인
• 브라우저 직접 경로와 서버 경로를 둘 다 확인
• 테스트가 실제 위험을 커버하는지 확인
• 문서/룰과 대조

Phase 7. Validation Gate

deep review 후 바로 finding으로 내지 않는다. 각 후보는 검증을 통과해야 한다.

검증 방법:

• 코드 경로 직접 확인
• rg/import graph로 reachability 확인
• shell에서 [ ] ( ) 등 glob/meta 문자가 포함된 경로는 반드시 quote한다.
• broad rg는 generated bundle이나 dist가 신호를 덮지 않도록 기본적으로 제외한다. 단, Deployment Artifacts 축을 검증할 때는 generated/public artifact를 명시적으로 포함한다.
• targeted test 실행
• typecheck/lint/static check 실행
• 필요 시 local server 실행
• 이미 떠 있는 local server를 재사용할 때는 프로세스 cwd/branch가 리뷰 대상 작업트리와 일치하는지 확인한다. 다른 worktree의 서버이거나 응답이 없으면 runtime 검증 증거로 쓰지 않는다.
• local server가 포트 충돌, 무응답, 환경 변수 문제로 확인되지 않으면 다른 포트를 쓰거나 verification gap으로 명시한다.
• 필요 시 browser로 실제 재현
• DB query 또는 migration 상태 확인
• analytics/log/metric payload 확인
• generated artifact 실제 배포 경로 확인

판정:

• 검증됨: finding으로 승격
• 증거 약함: question으로 낮춤
• 반박됨: no issue로 폐기
• 실행 불가: verification gap으로 명시

Phase 8. Finding Admission Rule

finding은 아래를 포함해야 한다.

• severity: P0/P1/P2/P3
• file/line
• 문제가 되는 기능 경로
• 실제로 깨지는 이유
• 검증 증거
• 재현 또는 확인 방법

Severity 기준:

• P0: 즉시 장애, 데이터 손상, 보안 사고, 결제/권한 치명 오류
• P1: 주요 기능 회귀, 실제 사용자 플로우 중단, 운영상 큰 문제
• P2: 제한된 조건의 버그, 누락된 edge case, 유지보수/관측성 문제
• P3: non-blocking 개선, 명확성, 작은 정리, 취향에 가까운 제안

형식:

[P1] 제목
파일/라인:
문제:
왜 실제 문제인지:
검증:
제안:

Phase 9. Output Format

출력은 findings를 먼저 둔다. 각 finding에는 심각도를 반드시 붙인다.

## Findings
- [P1] 제목
  - 파일/라인:
  - 문제:
  - 왜 실제 문제인지:
  - 검증:
  - 제안:

## Questions
- finding으로 확정하기엔 증거가 부족하지만 확인이 필요한 항목

## Reviewed Matrix
- 기능별로 어떤 축을 봤는지 요약

## Discarded Candidates
- 검토했지만 문제 아니라고 판단한 후보와 이유

## Verification
- 실행한 명령, 브라우저 검증, 코드 확인 범위

## Gaps
- 못 돌린 테스트, 접근 불가한 환경, 남은 불확실성

finding이 없으면 이렇게 답한다:

확정 finding은 없습니다.

확인한 범위:
- Feature A: correctness/performance/sync/tests 확인
- Feature B: deletion orphan sweep 확인
- Feature C: analytics/observability 확인

남은 한계:
- local runtime은 띄우지 못함
- external API 실제 응답은 mock 기준으로만 확인

Parallelization Guidance

병렬화가 유효한 경우:

• 기능이 2개 이상으로 분리될 때
• UI/analytics/server/test 축이 독립적일 때
• 삭제 dead-code sweep과 runtime behavior review가 분리될 때
• security/observability/performance 축이 독립적으로 검토 가능할 때

병렬화가 부적절한 경우:

• 같은 파일을 같은 관점으로 중복 검토하는 경우
• merge-base/diff 범위가 아직 고정되지 않은 경우
• 한 축의 결론이 다른 축의 입력이 되는 경우

Leader는 병렬 결과를 반드시 통합하고, 중복/충돌/증거 부족을 정리한 뒤 finding을 확정한다.