PR 자동 리뷰어 에이전트
90분 안에 붙이는 라인별 자동 리뷰

Session 10 · 라인별 PR 자동 리뷰어 에이전트

Python 300줄 · GitHub REST · Anthropic Messages API · GitHub Actions · 최소권한

🎨 이미지 프롬프트: "Editorial illustration on dark navy #0f1722 background showing a split scene: on the left a GitHub Pull Request page with three inline review comments pinned to code lines, on the right a friendly python robot icon holding a magnifying glass. Between them a large GitHub Actions gear icon connecting both sides with arrows. Warm orange gradient accents on the top-right. Clean editorial illustration style, teal #00b894 and purple #6c5ce7 accents, 16:9. CRITICAL: All visible text MUST be in English ONLY (no Korean characters). Each label appears EXACTLY ONCE — no duplicates. No mirrored or reversed text."

PART 1

왜 PR 자동 리뷰어인가

세션 목표 · 리뷰 병목 · AI 페어 리뷰의 강점·한계 · 사람과의 분업 설계.

세션 목표 — 열린 PR 에 AI 가 먼저 붙는다

이 세션이 끝나면 참여자 리포에 세 가지가 붙어 있다.

리뷰가 병목이 되는 세 지점

개발 팀에서 코드 리뷰가 병목이 되는 지점은 대체로 세 곳이다.

AI 리뷰어 — 강점과 한계 5축

분업 — AI 는 라인, 사람은 PR

분업이 코드로 굳어지려면 규약이 리포 안에 명시돼야 한다. 이 세션에서는 두 원칙만 못박는다.

PART 2

아키텍처 — 5단계 파이프라인

파이프라인 5단계 · GitHub Actions 트리거 · diff 파싱 · 청크 분할 · 인라인 코멘트 API · Anthropic 프롬프트 설계.

리뷰어 5단계 — 함수 구성과 1:1 대응

🎨 이미지 프롬프트: "Editorial illustration on dark navy #0f1722 background showing a horizontal pipeline of five stages connected by arrows. From left to right, five rounded boxes labeled 'Trigger', 'Fetch Diff', 'Filter Chunks', 'LLM Review', 'Post Comments'. The middle 'LLM Review' box is highlighted with a warm orange glow. A GitHub octopus icon on the far left and a chat bubble icon on the far right. Clean editorial illustration style, teal #00b894 and purple #6c5ce7 accents, 16:9. CRITICAL: All visible text MUST be in English ONLY (no Korean characters). Each label appears EXACTLY ONCE — no duplicates. No mirrored or reversed text."

리뷰어 5단계 — 함수 구성과 1:1 대응

GitHub Actions 트리거 — 무엇을 잡을까

pull_request 이벤트 안에도 세부 액션 타입이 여러 개다. 다 잡으면 워크플로가 과도하게 돈다.

diff 파싱 — GitHub REST 응답 모양

GitHub REST API 는 PR 의 파일별 변경을 이렇게 반환한다.

[
  {
    "filename": "backend/app/main.py",
    "status": "modified",
    "additions": 12,
    "deletions": 3,
    "patch": "@@ -10,3 +10,12 @@ def handler():\n ..."
  }
]

청크 분할 — 파일 단위 우선, 크면 헝크

파일 하나의 patch 가 500줄이라면 그대로 LLM 에 넣기에는 너무 크다. 청크로 자른다.

인라인 코멘트 — 두 API 중 두 번째만 사용

GitHub REST API 는 PR 코멘트를 게시하는 두 가지 경로를 제공한다. 이 세션에서 쓰는 것은 두 번째.

📖 GitHub REST · Create a review for a pull request · GitHub REST · List pull request files

리뷰 게시 요청 — 핵심 필드 3개

{
  "commit_id": "abc123...",
  "event": "COMMENT",
  "body": "AI Reviewer 총평",
  "comments": [
    {
      "path": "backend/app/main.py",
      "line": 42,
      "side": "RIGHT",
      "body": "print 대신 logger.info 를 권장합니다."
    }
  ]
}

LLM 프롬프트 설계 — 세 축을 지킨다

LLM 호출부는 프롬프트가 반이다. 시스템 프롬프트 카드 하나가 이 리뷰어의 정체성이 된다.

출력 스키마 예시.

[
  {
    "line": 42,
    "severity": "warning",
    "category": "logging",
    "message": "print 대신 logger.info 를 권장합니다."
  }
]

PART 3

Python 구현 — 5개 모듈

프로젝트 구성 · github_api.py · diff.py · llm.py · prompts.py · __main__.py · pytest 단위 테스트.

프로젝트 트리 — demos/pr_reviewer/

pr_reviewer/
├── reviewer/
│   ├── __init__.py
│   ├── __main__.py          # python -m reviewer 진입점
│   ├── github_api.py        # PR 조회·리뷰 게시
│   ├── diff.py              # patch 파싱·청크 분할
│   ├── llm.py               # Anthropic 호출
│   └── prompts.py           # SYSTEM_PROMPT 등 상수
├── tests/
│   ├── test_diff.py
│   └── fixtures/
│       └── sample_patch.diff
├── pyproject.toml
├── .github/
│   └── workflows/
│       └── ai-review.yml
└── README.md

github_api.py ① — GitHubClient 스캐폴드

GitHub API 호출은 httpx 로 직접 부른다. PyGithub 도 좋지만 리뷰 API 는 파라미터가 특수해서 직접 부르는 편이 명확하다.

import os
from typing import Any

import httpx

GITHUB_API = "https://api.github.com"


class GitHubClient:
    def __init__(self, token: str, repo: str) -> None:
        self.token = token
        self.repo = repo  # "owner/name" 형태
        self.headers = {
            "Authorization": f"Bearer {token}",
            "Accept": "application/vnd.github+json",
            "X-GitHub-Api-Version": "2022-11-28",
        }

    async def get_pr(self, pr_number: int) -> dict[str, Any]:
        url = f"{GITHUB_API}/repos/{self.repo}/pulls/{pr_number}"
        async with httpx.AsyncClient() as c:
            r = await c.get(url, headers=self.headers, timeout=30)
            r.raise_for_status()
            return r.json()

github_api.py ② — list_pr_files 페이지네이션

    async def list_pr_files(self, pr_number: int) -> list[dict[str, Any]]:
        url = f"{GITHUB_API}/repos/{self.repo}/pulls/{pr_number}/files"
        files: list[dict[str, Any]] = []
        async with httpx.AsyncClient() as c:
            page = 1
            while True:
                r = await c.get(
                    url,
                    params={"per_page": 100, "page": page},
                    headers=self.headers,
                    timeout=30,
                )
                r.raise_for_status()
                batch = r.json()
                if not batch:
                    break
                files.extend(batch)
                if len(batch) < 100:
                    break
                page += 1
        return files

github_api.py ③ — post_review 리뷰 게시

    async def post_review(
        self,
        pr_number: int,
        commit_sha: str,
        body: str,
        comments: list[dict[str, Any]],
    ) -> dict[str, Any]:
        url = f"{GITHUB_API}/repos/{self.repo}/pulls/{pr_number}/reviews"
        payload = {
            "commit_id": commit_sha,
            "event": "COMMENT",
            "body": body,
            "comments": comments,
        }
        async with httpx.AsyncClient() as c:
            r = await c.post(url, json=payload, headers=self.headers, timeout=60)
            r.raise_for_status()
            return r.json()

diff.py ① — 상수와 should_review

patch 파싱은 정규식 한두 개면 충분하다. 라이브러리 안 쓰고 직접 짜는 편이 이해가 쉽다.

import re
from dataclasses import dataclass, field

ALLOWED_EXT = {".py", ".ts", ".tsx", ".js", ".go", ".java", ".kt", ".rb", ".rs"}
MAX_PATCH_LINES = 3000
HUNK_HEADER = re.compile(r"^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@")

@dataclass
class Chunk:
    path: str
    language: str
    patch: str
    line_map: dict[int, int] = field(default_factory=dict)


def should_review(file_entry: dict) -> bool:
    if file_entry.get("status") == "removed":
        return False
    if file_entry.get("patch") is None:
        return False
    if file_entry.get("changes", 0) > MAX_PATCH_LINES:
        return False
    path = file_entry["filename"]
    ext = "." + path.rsplit(".", 1)[-1] if "." in path else ""
    return ext in ALLOWED_EXT

diff.py ② — build_line_map (안전핀)

def build_line_map(patch: str) -> dict[int, int]:
    """patch 안 상대 라인 -> 대상 파일의 실제 라인 번호."""
    line_map: dict[int, int] = {}
    file_line = 0
    for idx, raw in enumerate(patch.splitlines(), start=1):
        m = HUNK_HEADER.match(raw)
        if m:
            file_line = int(m.group(2))
            continue
        if raw.startswith("+") and not raw.startswith("+++"):
            line_map[idx] = file_line
            file_line += 1
        elif raw.startswith("-") and not raw.startswith("---"):
            continue
        else:
            # 공통 컨텍스트 라인
            file_line += 1
    return line_map

diff.py ③ — language_of · to_chunks

def language_of(path: str) -> str:
    return {
        ".py": "python",
        ".ts": "typescript",
        ".tsx": "typescript",
        ".js": "javascript",
        ".go": "go",
        ".java": "java",
        ".kt": "kotlin",
        ".rb": "ruby",
        ".rs": "rust",
    }.get("." + path.rsplit(".", 1)[-1], "text")

def to_chunks(files: list[dict]) -> list[Chunk]:
    chunks: list[Chunk] = []
    for f in files:
        if not should_review(f):
            continue
        patch = f["patch"]
        chunks.append(
            Chunk(
                path=f["filename"],
                language=language_of(f["filename"]),
                patch=patch,
                line_map=build_line_map(patch),
            )
        )
    return chunks

prompts.py ① — SYSTEM_PROMPT (프롬프트 카드)

SYSTEM_PROMPT = """너는 시니어 코드 리뷰어다.
주어진 diff 를 읽고, 개선이 필요한 라인만 골라 JSON 배열로 반환한다.

리뷰 원칙.
1. 추가된 줄 (patch 에서 + 로 시작) 만 지적한다. 삭제·컨텍스트 라인은 무시.
2. 다음 카테고리에 해당하는 것만 남긴다.
   - naming (변수·함수·클래스 명명이 컨벤션과 어긋남)
   - error_handling (except 남용, silent failure, 광범위 catch)
   - logging (print 대신 logger 권장, 로그 레벨 오용)
   - security (하드코딩 시크릿, SQL 인젝션 여지, 안전하지 않은 역직렬화)
   - performance (명백한 O(n^2) 반복, 불필요 재계산)
   - readability (5줄 이상 중첩, 매직 상수, 이름과 실제 동작 불일치)
3. 스타일 취향은 지적하지 않는다 (탭 vs 스페이스, 함수 순서, 컴마 위치).
4. 확실하지 않으면 지적하지 않는다. False positive 가 미검출보다 나쁘다.

출력 스키마.
반드시 JSON 배열 하나만 반환. 배열 밖 텍스트 금지.
각 원소는 다음 필드.

{
  "line": <patch 안 상대 라인 번호 (1부터)>,
  "severity": "info" | "warning" | "critical",
  "category": "naming" | "error_handling" | "logging" | "security" | "performance" | "readability",
  "message": "한국어로 2문장 이내. 어떻게 고칠지 짧게 제안 포함."
}

지적할 것이 없으면 빈 배열 [] 반환."""

프롬프트 — 세 장치의 효과

USER_TEMPLATE (청크마다 채워 보냄).

USER_TEMPLATE = """파일: {path}
언어: {language}
PR 제목: {pr_title}
PR 본문(발췌): {pr_body}

--- diff ---
{patch}
--- end ---

위 diff 를 리뷰해줘."""

llm.py ① — ReviewComment 데이터클래스 · 상수

import asyncio
import json
import logging
from dataclasses import dataclass

from anthropic import APIError, AsyncAnthropic

from .diff import Chunk
from .prompts import SYSTEM_PROMPT, USER_TEMPLATE

logger = logging.getLogger(__name__)

MODEL = "claude-sonnet-5"
MAX_TOKENS = 2048


@dataclass
class ReviewComment:
    path: str
    line: int
    severity: str
    category: str
    message: str

llm.py ② — Reviewer 클래스 · 프롬프트 조립

class Reviewer:
    def __init__(self, api_key: str) -> None:
        self.client = AsyncAnthropic(api_key=api_key)

    async def review_chunk(
        self, chunk: Chunk, pr_title: str, pr_body: str
    ) -> list[ReviewComment]:
        user_msg = USER_TEMPLATE.format(
            path=chunk.path,
            language=chunk.language,
            pr_title=pr_title,
            pr_body=(pr_body or "")[:800],
            patch=chunk.patch,
        )
        # 다음 슬라이드에서 재시도·파싱

llm.py ③ — 3회 재시도 + 방어 파싱

        for attempt in range(3):
            try:
                resp = await self.client.messages.create(
                    model=MODEL,
                    max_tokens=MAX_TOKENS,
                    system=SYSTEM_PROMPT,
                    messages=[{"role": "user", "content": user_msg}],
                )
                text = resp.content[0].text.strip()
                items = json.loads(_extract_json_array(text))
                return _to_comments(chunk, items)
            except (APIError, json.JSONDecodeError) as exc:
                logger.warning(
                    "chunk %s attempt %d failed: %s", chunk.path, attempt + 1, exc
                )
                await asyncio.sleep(2**attempt)

        logger.error("chunk %s: giving up after 3 attempts", chunk.path)
        return []


def _extract_json_array(text: str) -> str:
    """LLM 이 앞뒤에 코드펜스를 붙여도 JSON 배열만 뽑아냄."""
    start = text.find("[")
    end = text.rfind("]")
    if start == -1 or end == -1:
        return "[]"
    return text[start : end + 1]

llm.py ④ — _to_comments line_map 필터

def _to_comments(chunk: Chunk, items: list[dict]) -> list[ReviewComment]:
    out: list[ReviewComment] = []
    for it in items:
        rel_line = int(it.get("line", 0))
        real_line = chunk.line_map.get(rel_line)
        if real_line is None:
            # LLM 이 삭제 라인이나 컨텍스트 라인 지적 시 무시
            continue
        out.append(
            ReviewComment(
                path=chunk.path,
                line=real_line,
                severity=str(it.get("severity", "info")),
                category=str(it.get("category", "readability")),
                message=str(it.get("message", "")).strip(),
            )
        )
    return out

📖 Anthropic Python SDK · GitHub · Anthropic API · Messages

__main__.py ① — 환경변수 · 조립

지금까지 만든 세 조각 (github_api · diff · llm) 을 한 진입점에서 조립.

import asyncio, logging, os, sys

from .diff import to_chunks
from .github_api import GitHubClient
from .llm import ReviewComment, Reviewer

logger = logging.getLogger("reviewer")


async def main() -> int:
    token = os.environ["GITHUB_TOKEN"]
    api_key = os.environ["ANTHROPIC_API_KEY"]
    repo = os.environ["GITHUB_REPOSITORY"]  # "owner/name"
    pr_number = int(os.environ["PR_NUMBER"])

    gh = GitHubClient(token=token, repo=repo)
    reviewer = Reviewer(api_key=api_key)

    pr = await gh.get_pr(pr_number)
    files = await gh.list_pr_files(pr_number)
    chunks = to_chunks(files)

    logger.info("PR #%d: %d files, %d chunks", pr_number, len(files), len(chunks))

__main__.py ② — Semaphore + gather 병렬 리뷰

    # 청크별 병렬 리뷰 (동시성 4)
    sem = asyncio.Semaphore(4)

    async def run(chunk):
        async with sem:
            return await reviewer.review_chunk(
                chunk, pr_title=pr["title"], pr_body=pr.get("body") or ""
            )

    results = await asyncio.gather(*(run(c) for c in chunks))
    comments: list[ReviewComment] = [c for group in results for c in group]

    logger.info("total comments: %d", len(comments))

    if not comments:
        logger.info("nothing to review")
        return 0

__main__.py ③ — post_review 게시 · 엔트리

    api_comments = [
        {"path": c.path, "line": c.line, "side": "RIGHT",
         "body": f"**[{c.category}] {c.severity}** {c.message}"}
        for c in comments
    ]
    body = (
        f"AI Reviewer 가 diff 를 훑고 {len(comments)}개의 라인 코멘트를 남겼습니다. "
        "판단이 필요한 최종 승인은 사람 리뷰어에게 맡깁니다."
    )
    await gh.post_review(
        pr_number=pr_number,
        commit_sha=pr["head"]["sha"],
        body=body,
        comments=api_comments,
    )
    return 0


if __name__ == "__main__":
    sys.exit(asyncio.run(main()))

pytest ① — line_map 매핑 검증

LLM 호출부는 통합 테스트로 미룬다. diff 파서는 단위 테스트가 반드시 필요. line_map 이 어긋나면 인라인 코멘트가 엉뚱한 줄에 붙기 때문.

from reviewer.diff import build_line_map, should_review

SAMPLE = """@@ -10,3 +10,6 @@ def handler(req):
     return req
+
+def new_helper(x):
+    print(x)
+    return x + 1"""


def test_build_line_map_maps_added_lines():
    m = build_line_map(SAMPLE)
    # 상대 라인 3 (첫 + 라인) -> 파일 라인 11
    assert m[3] == 11
    # 상대 라인 5 (print 줄) -> 파일 라인 13
    assert m[5] == 13

pytest ② — should_review 필터 세 케이스

def test_should_review_skips_removed():
    assert should_review({"status": "removed", "patch": "x", "filename": "a.py"}) is False


def test_should_review_skips_binary():
    assert should_review({"status": "added", "patch": None, "filename": "a.py"}) is False


def test_should_review_skips_markdown():
    assert (
        should_review(
            {"status": "modified", "patch": "x", "changes": 5, "filename": "README.md"}
        )
        is False
    )

PART 4

GitHub Actions 배포 — workflow yaml · 최소권한

workflow yaml 전체 · GITHUB_TOKEN 권한 · 시크릿 관리 · 큰 PR 분할 · 첫 실배포 · 트러블슈팅.

.github/workflows/ai-review.yml ① — 트리거 · 권한 · 동시성

name: AI PR Reviewer

on:
  pull_request:
    types: [opened, synchronize, ready_for_review]
    paths:
      - "**/*.py"
      - "**/*.ts"
      - "**/*.tsx"
      - "**/*.js"
      - "**/*.go"

permissions:
  contents: read
  pull-requests: write

concurrency:
  group: ai-review-${{ github.event.pull_request.number }}
  cancel-in-progress: true

.github/workflows/ai-review.yml ② — jobs · steps

jobs:
  review:
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: Checkout
        uses: actions/checkout@v5

      - name: Setup Python
        uses: actions/setup-python@v6
        with:
          python-version: "3.12"
          cache: pip

      - name: Install reviewer
        run: pip install -e ./tools/pr_reviewer

      - name: Run AI review
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: python -m reviewer

📖 GitHub Actions · Workflow syntax

workflow yaml — 여섯 핵심 세팅

GITHUB_TOKEN — 왜 최소권한

GitHub Actions 워크플로에는 기본으로 GITHUB_TOKEN 이 주입된다. 이 토큰의 스코프는 워크플로 파일의 permissions 블록으로 정한다.

📖 GitHub Actions · Permissions for GITHUB_TOKEN

시크릿 관리 — 리포 시크릿 · .env

시크릿은 두 개다.

.gitignore 라인.

.env
.env.local
*.pem

큰 PR — 분할 · 병렬 · 안전판

PR 하나가 많은 파일로 커지는 경우 (마이그레이션 · 대규모 리팩토링) 를 어떻게 다룰까.

# reviewer/diff.py 상단에 함께 정의
MAX_CHUNKS_PER_PR = 30

# __main__.py 에서 청크 목록 조립 직후
if len(chunks) > MAX_CHUNKS_PER_PR:
    skipped = [c.path for c in chunks[MAX_CHUNKS_PER_PR:]]
    chunks = chunks[:MAX_CHUNKS_PER_PR]
    body_prefix = (
        f"[알림] PR 규모가 커서 상위 {MAX_CHUNKS_PER_PR}개 "
        f"파일만 리뷰했습니다."
    )

첫 실배포 — 순서와 확인 포인트

첫 실행 실패 시 자주 나오는 원인.

PART 5

실전 · 확장 — 스멜 시연 · 튜닝 · 로드맵

5종 스멜 실시연 · false positive 억제 3 튜닝 · 확장 아이디어 4개 · 도입 로드맵.

5종 스멜 — 샌드박스 리포에 심어둔 것

강사는 사전에 준비한 vibecoding-review-sandbox 리포를 열어 보인다. 파이썬 파일 하나에 다섯 종 코드 스멜이 심어져 있다.

import os

DB_PASSWORD = "hunter2"                       # ① security

def process(items):
    for i in range(len(items)):               # ② readability (파이썬 관용구 위배)
        for j in range(len(items)):           # ③ performance (O(n^2))
            if items[i] == items[j]:
                print(items[i])                # ④ logging (print 대신 logger)

    try:
        do_something()
    except:                                   # ⑤ error_handling (bare except)
        pass

5종 스멜 — 예상 지적 vs 실측 카드

false positive 억제 — 3 실전 튜닝

첫 배포 후 며칠 돌려 보면 false positive 가 반드시 나온다. 실전에서 이걸 줄이는 세 가지.

심각도별 게시 정책 예시.

SEVERITY_ALLOW = {"warning", "critical"}

api_comments = [
    {"path": c.path, "line": c.line, "side": "RIGHT",
     "body": f"**[{c.category}] {c.severity}** {c.message}"}
    for c in comments
    if c.severity in SEVERITY_ALLOW
]

확장 아이디어 4 — 하나만 골라 자기 리포에

이 리뷰어는 시작점이다. 자기 리포로 가져가 확장할 네 방향.

도입 로드맵 — 조용히 시작 · 확신 후 확산

실전 팀에 이 리뷰어를 붙이는 3단계 로드맵.

PART 6

정리 — 한 문장 · 사이클 5축

세션 소감 한 문장 · 마무리 · 사이클 5축 회수.

세션 소감 — 한 문장으로 남긴다

이 세션이 끝났다. 참여자 리포에 300줄 남짓의 파이썬 · 40줄 남짓의 workflow yaml 이 붙었고, 열린 PR 하나에 AI 가 라인별 코멘트를 실제로 남겼다.

마무리 — 자기 리포로 가져갈 것

🎨 이미지 프롬프트: "Editorial illustration on dark navy #0f1722 background of a checklist scroll unrolling to the right, showing five checked items labeled 'Trigger', 'Diff', 'Filter', 'LLM', 'Review'. Beside the scroll a small python robot icon smiles and holds a green checkmark badge. A warm orange gradient accent on the top-right corner similar to the cover slide. Clean editorial illustration style, teal #00b894 and purple #6c5ce7 accents, 16:9. CRITICAL: All visible text MUST be in English ONLY (no Korean characters). Each label appears EXACTLY ONCE — no duplicates. No mirrored or reversed text."

리뷰어 사이클 5축 — 그림 한 장으로 회수