● Overview κ°œμš”

ROACH PI provides two code review modes with different depth and cost trade-offs:

ROACH PIλŠ” κΉŠμ΄μ™€ λΉ„μš© νŠΈλ ˆμ΄λ“œμ˜€ν”„κ°€ λ‹€λ₯Έ 두 가지 μ½”λ“œ 리뷰 λͺ¨λ“œλ₯Ό μ œκ³΅ν•©λ‹ˆλ‹€:

  • /review β€” single-pass review performed directly by the current agent. Fast, lightweight, no subagent overhead. ν˜„μž¬ μ—μ΄μ „νŠΈκ°€ 직접 μˆ˜ν–‰ν•˜λŠ” 단일 패슀 리뷰. λΉ λ₯΄κ³  κ°€λ²Όμš°λ©° μ„œλΈŒμ—μ΄μ „νŠΈ μ˜€λ²„ν—€λ“œ μ—†μŒ.
  • /ultrareview β€” multi-agent pipeline that dispatches 10 parallel reviewers, a verification pass, and a synthesis step. Thorough but slower. 10개의 병렬 리뷰어, 검증 패슀, μ’…ν•© 단계λ₯Ό λ””μŠ€νŒ¨μΉ˜ν•˜λŠ” 닀쀑 μ—μ΄μ „νŠΈ νŒŒμ΄ν”„λΌμΈ. μ² μ €ν•˜μ§€λ§Œ 느림.

β–Ά /review β€” Single-Pass Review β€” 단일 패슀 리뷰

Syntax ꡬ문

/review [target]

target can be a PR number, PR URL, branch name, or omitted for auto-detection. No confirmation is required β€” the review starts immediately.

target은 PR 번호, PR URL, 브랜치 이름, λ˜λŠ” μžλ™ 감지λ₯Ό μœ„ν•΄ μƒλž΅ν•  수 μžˆμŠ΅λ‹ˆλ‹€. 확인 없이 리뷰가 μ¦‰μ‹œ μ‹œμž‘λ©λ‹ˆλ‹€.

Target Validation νƒ€κ²Ÿ 검증

The target is validated against /^[a-zA-Z0-9._/:\-]+$/ before any prompt is sent. Shell metacharacters (;, |, &, >, `, $()) are rejected immediately to prevent injection into the downstream gh / git commands.

νƒ€κ²Ÿμ€ ν”„λ‘¬ν”„νŠΈ 전솑 전에 /^[a-zA-Z0-9._/:\-]+$/둜 κ²€μ¦λ©λ‹ˆλ‹€. μ…Έ λ©”νƒ€λ¬Έμž(;, |, &, >, `, $())λŠ” λ‹€μš΄μŠ€νŠΈλ¦Ό gh / git λͺ…λ Ήμ–΄λ‘œμ˜ μΈμ μ…˜μ„ λ°©μ§€ν•˜κΈ° μœ„ν•΄ μ¦‰μ‹œ κ±°λΆ€λ©λ‹ˆλ‹€.

Review Output 리뷰 좜λ ₯

The review is output directly to chat, grouped by file. Each finding includes: what, where (file:line), severity (Critical/High/Medium/Low), and a one-line suggested fix. No file is saved and no subagents are dispatched.

λ¦¬λ·°λŠ” νŒŒμΌλ³„λ‘œ κ·Έλ£Ήν™”λ˜μ–΄ μ±„νŒ…μ— 직접 좜λ ₯λ©λ‹ˆλ‹€. 각 발견 사항은 λ‚΄μš©, μœ„μΉ˜(file:line), 심각도(Critical/High/Medium/Low), ν•œ 쀄 μˆ˜μ • μ œμ•ˆμ„ ν¬ν•¨ν•©λ‹ˆλ‹€. νŒŒμΌμ€ μ €μž₯λ˜μ§€ μ•Šκ³  μ„œλΈŒμ—μ΄μ „νŠΈλ„ λ””μŠ€νŒ¨μΉ˜λ˜μ§€ μ•ŠμŠ΅λ‹ˆλ‹€.

β–  Diff Commands Diff λͺ…λ Ήμ–΄

Both /review and /ultrareview use the same target resolution logic:

/review와 /ultrareview λͺ¨λ‘ λ™μΌν•œ νƒ€κ²Ÿ ν•΄κ²° λ‘œμ§μ„ μ‚¬μš©ν•©λ‹ˆλ‹€:

Targetνƒ€κ²Ÿ Commandλͺ…λ Ήμ–΄
PR numberPR 번호 gh pr diff <number>
PR URLPR URL gh pr diff <url>
Branch name브랜치 이름 git diff main...<topic>
Auto (PR found)μžλ™ (PR 발견) gh pr list --head <branch> β†’ gh pr diff <number>
Auto (no PR)μžλ™ (PR μ—†μŒ) git diff main...HEAD + git diff + git diff --cached
πŸ’‘ NoteπŸ’‘ μ°Έκ³ 

gh accepts PR numbers and full GitHub PR URLs interchangeably β€” no special URL parsing is needed.

ghλŠ” PR λ²ˆν˜Έμ™€ 전체 GitHub PR URL을 μƒν˜Έ κ΅ν™˜μ μœΌλ‘œ ν—ˆμš©ν•©λ‹ˆλ‹€ β€” λ³„λ„μ˜ URL νŒŒμ‹±μ΄ ν•„μš” μ—†μŠ΅λ‹ˆλ‹€.

β˜… /ultrareview β€” Multi-Agent Pipeline β€” 닀쀑 μ—μ΄μ „νŠΈ νŒŒμ΄ν”„λΌμΈ

The ultrareview command dispatches a 3-stage pipeline with up to 12 subagent invocations. A confirmation dialog is required before the pipeline starts.

ultrareview λͺ…λ Ήμ–΄λŠ” μ΅œλŒ€ 12개의 μ„œλΈŒμ—μ΄μ „νŠΈ 호좜둜 3단계 νŒŒμ΄ν”„λΌμΈμ„ λ””μŠ€νŒ¨μΉ˜ν•©λ‹ˆλ‹€. νŒŒμ΄ν”„λΌμΈ μ‹œμž‘ μ „ 확인 λŒ€ν™”μƒμžκ°€ ν•„μš”ν•©λ‹ˆλ‹€.

Stage 1: Finding (10 parallel reviewers)1단계: 발견 (10개 병렬 리뷰어)

The diff is resolved once and written to a shared artifact (e.g. docs/engineering-discipline/reviews/.tmp/<date>-<topic>.diff). Then 10 subagents are dispatched in parallel β€” 5 reviewer roles Γ— 2 seeds each. Seed 2 is instructed to focus on findings seed 1 might miss.

diffλŠ” ν•œ 번 ν•΄κ²°λ˜μ–΄ 곡유 μ•„ν‹°νŒ©νŠΈ(예: docs/engineering-discipline/reviews/.tmp/<date>-<topic>.diff)에 μž‘μ„±λ©λ‹ˆλ‹€. κ·Έ ν›„ 10개의 μ„œλΈŒμ—μ΄μ „νŠΈκ°€ λ³‘λ ¬λ‘œ λ””μŠ€νŒ¨μΉ˜λ©λ‹ˆλ‹€ β€” 5개 리뷰어 μ—­ν•  Γ— μ‹œλ“œ 2개. μ‹œλ“œ 2λŠ” μ‹œλ“œ 1이 놓칠 수 μžˆλŠ” λ°œκ²¬μ— μ§‘μ€‘ν•˜λ„λ‘ μ§€μ‹œλ°›μŠ΅λ‹ˆλ‹€.

Stage 2: Verification2단계: 검증

reviewer-verifier is dispatched in single mode with the aggregated findings from all 10 reviewers. It deduplicates findings, filters false positives, and assigns final severity and confidence ratings.

10개 λ¦¬λ·°μ–΄μ˜ λͺ¨λ“  μ§‘κ³„λœ 발견과 ν•¨κ»˜ reviewer-verifierκ°€ 단일 λͺ¨λ“œλ‘œ λ””μŠ€νŒ¨μΉ˜λ©λ‹ˆλ‹€. λ°œκ²¬μ„ 쀑볡 μ œκ±°ν•˜κ³ , μœ„μ–‘μ„±μ„ ν•„ν„°λ§ν•˜λ©°, μ΅œμ’… 심각도 및 신뒰도 등급을 λΆ€μ—¬ν•©λ‹ˆλ‹€.

Stage 3: Synthesis3단계: μ’…ν•©

review-synthesis is dispatched in single mode with the verified findings. It produces a structured report and saves it to docs/engineering-discipline/reviews/<YYYY-MM-DD>-<topic>-review.md. A 5-item top-priority summary is also streamed to chat.

κ²€μ¦λœ 발견과 ν•¨κ»˜ review-synthesisκ°€ 단일 λͺ¨λ“œλ‘œ λ””μŠ€νŒ¨μΉ˜λ©λ‹ˆλ‹€. κ΅¬μ‘°ν™”λœ 리포트λ₯Ό μƒμ„±ν•˜κ³  docs/engineering-discipline/reviews/<YYYY-MM-DD>-<topic>-review.md에 μ €μž₯ν•©λ‹ˆλ‹€. μ΅œμš°μ„  5개 ν•­λͺ© μš”μ•½λ„ μ±„νŒ…μ— μŠ€νŠΈλ¦¬λ°λ©λ‹ˆλ‹€.

⚠ Guard⚠ κ°€λ“œ

No agent whose name contains "worker" is ever dispatched in this pipeline β€” only reviewer-* and review-synthesis are allowed.

이 νŒŒμ΄ν”„λΌμΈμ—μ„œλŠ” 이름에 "worker"κ°€ ν¬ν•¨λœ μ—μ΄μ „νŠΈλŠ” λ””μŠ€νŒ¨μΉ˜λ˜μ§€ μ•ŠμŠ΅λ‹ˆλ‹€ β€” reviewer-*와 review-synthesis만 ν—ˆμš©λ©λ‹ˆλ‹€.

β–  Reviewer Roles리뷰어 μ—­ν• 

Each of the 5 reviewer roles is dispatched twice (seed 1 and seed 2) for complementary coverage:

5개 리뷰어 μ—­ν•  각각이 μƒν˜Έ 보완적 컀버리지λ₯Ό μœ„ν•΄ 두 번(μ‹œλ“œ 1κ³Ό μ‹œλ“œ 2) λ””μŠ€νŒ¨μΉ˜λ©λ‹ˆλ‹€:

Roleμ—­ν•  Focus집쀑 μ˜μ—­
reviewer-bug Logic errors, boundary conditions, null/undefined, race conditions, missing error handling 논리 였λ₯˜, 경계 쑰건, null/undefined, 레이슀 μ»¨λ””μ…˜, λˆ„λ½λœ μ—λŸ¬ 핸듀링
reviewer-security Injection, auth, authorization, crypto misuse, data exposure μΈμ μ…˜, 인증, 인가, μ•”ν˜Έν™” 였용, 데이터 λ…ΈμΆœ
reviewer-performance Algorithmic complexity, unnecessary allocations, sync I/O on hot paths, cache misses μ•Œκ³ λ¦¬μ¦˜ λ³΅μž‘λ„, λΆˆν•„μš”ν•œ ν• λ‹Ή, ν•« 경둜의 동기 I/O, μΊμ‹œ 미슀
reviewer-test-coverage Missing tests, happy-path only, uncovered edge cases λˆ„λ½λœ ν…ŒμŠ€νŠΈ, ν•΄ν”Ό 패슀만 쑴재, μ»€λ²„λ˜μ§€ μ•Šμ€ 엣지 μΌ€μ΄μŠ€
reviewer-consistency Convention drift, duplication, missing reuse of existing utilities μ»¨λ²€μ…˜ λ“œλ¦¬ν”„νŠΈ, 쀑볡, κΈ°μ‘΄ μœ ν‹Έλ¦¬ν‹°μ˜ μž¬μ‚¬μš© λˆ„λ½

● Verification & Synthesis검증 및 μ’…ν•©

reviewer-verifier

Receives the aggregated output from all 10 reviewers. Performs three actions:

10개 λ¦¬λ·°μ–΄μ˜ μ§‘κ³„λœ 좜λ ₯을 λ°›μŠ΅λ‹ˆλ‹€. μ„Έ 가지 μž‘μ—…μ„ μˆ˜ν–‰ν•©λ‹ˆλ‹€:

  • Deduplicate β€” removes findings reported by multiple reviewers for the same location. 쀑볡 제거 β€” λ™μΌν•œ μœ„μΉ˜μ— λŒ€ν•΄ μ—¬λŸ¬ 리뷰어가 λ³΄κ³ ν•œ λ°œκ²¬μ„ μ œκ±°ν•©λ‹ˆλ‹€.
  • Filter false positives β€” discards findings that don't hold against the actual codebase. μœ„μ–‘μ„± ν•„ν„° β€” μ‹€μ œ μ½”λ“œλ² μ΄μŠ€μ—μ„œ μ„±λ¦½ν•˜μ§€ μ•ŠλŠ” λ°œκ²¬μ„ λ²„λ¦½λ‹ˆλ‹€.
  • Attach ratings β€” assigns severity (low / medium / high / critical) and confidence to each surviving finding. λ“±κΈ‰ λΆ€μ—¬ β€” 각 생쑴 λ°œκ²¬μ— 심각도(low / medium / high / critical)와 신뒰도λ₯Ό λΆ€μ—¬ν•©λ‹ˆλ‹€.

review-synthesis

Takes the verified findings and produces the final structured review report. Writes to docs/engineering-discipline/reviews/<YYYY-MM-DD>-<topic>-review.md. The report includes a summary, per-file findings ranked by severity, and a top-priority list streamed to chat.

κ²€μ¦λœ λ°œκ²¬μ„ λ°›μ•„ μ΅œμ’… κ΅¬μ‘°ν™”λœ 리뷰 리포트λ₯Ό μƒμ„±ν•©λ‹ˆλ‹€. docs/engineering-discipline/reviews/<YYYY-MM-DD>-<topic>-review.md에 μž‘μ„±ν•©λ‹ˆλ‹€. λ¦¬ν¬νŠΈμ—λŠ” μš”μ•½, 심각도별 μˆœμœ„μ˜ νŒŒμΌλ³„ 발견, μ±„νŒ…μ— μŠ€νŠΈλ¦¬λ°λ˜λŠ” μ΅œμš°μ„  λͺ©λ‘μ΄ ν¬ν•¨λ©λ‹ˆλ‹€.

β–Ά Choosing Between Modesλͺ¨λ“œ 선택 κ°€μ΄λ“œ

β–Ά
/review

Quick feedback on small changes. Single-pass, no subagents, instant output to chat. Ideal for PRs under ~200 lines or when you just need a second pair of eyes.

μž‘μ€ λ³€κ²½ 사항에 λŒ€ν•œ λΉ λ₯Έ ν”Όλ“œλ°±. 단일 패슀, μ„œλΈŒμ—μ΄μ „νŠΈ μ—†μŒ, μ±„νŒ…μ— μ¦‰μ‹œ 좜λ ₯. μ•½ 200쀄 미만의 PRμ΄λ‚˜ κ°„λ‹¨ν•œ κ²€ν† κ°€ ν•„μš”ν•  λ•Œ μ ν•©ν•©λ‹ˆλ‹€.

β˜…
/ultrareview

Major PRs, architectural changes, or when thorough coverage is critical. 10 parallel reviewers + verification + synthesis. Takes several minutes but produces a saved, structured report.

μ£Όμš” PR, μ•„ν‚€ν…μ²˜ λ³€κ²½, μ² μ €ν•œ 컀버리지가 μ€‘μš”ν•  λ•Œ. 10개 병렬 리뷰어 + 검증 + μ’…ν•©. λͺ‡ 뢄이 κ±Έλ¦¬μ§€λ§Œ μ €μž₯λ˜λŠ” κ΅¬μ‘°ν™”λœ 리포트λ₯Ό μƒμ„±ν•©λ‹ˆλ‹€.