AI PR Review Toolkit — 시작 가이드

이 페이지 위쪽의 경로 선택기와 두 가지 동작 방식 흐름도에서 본인 상황에 맞는 시작 방식을 먼저 확인하세요. Windows 앱 한 번 설치로 끝낼지, CLI로 자동화까지 갈지를 정한 뒤 아래 단계에서 자세한 절차를 따라가면 됩니다. 두 방식 모두 동일한 Claude Sonnet 분석 엔진을 사용하며, 첫 PR 리뷰까지 약 5분이 걸립니다.

---

1. Windows 앱으로 시작 (권장)

1-1. 다운로드 및 설치

EV 코드 서명된 Windows v1.0.1 — 설치 시 SmartScreen 경고가 뜨지 않습니다.

파일	사이즈	권장 상황
MSI 설치 파일 (권장)	~12 MB	일반 사용자, 그룹 정책 환경, 자동 업데이트 채널
EXE 설치 파일 (대체)	~11 MB	MSI 차단 정책이 있는 PC, 1회성 설치

• MSI 직접 다운로드: https://github.com/ssallem/ai-pr-review-app/releases/download/v1.0.1/AI_PR_Review_Toolkit_1.0.1_x64_en-US.msi
• EXE 직접 다운로드: https://github.com/ssallem/ai-pr-review-app/releases/download/v1.0.1/AI_PR_Review_Toolkit_1.0.1_x64-setup.exe
• 통합 다운로드 페이지(체크섬·서명 정보 포함): https://ai-review-kit.pages.dev/download

설치 단계 3단계:

1. 위 링크에서 MSI 또는 EXE 파일 다운로드
2. 받은 파일 더블클릭 → 안내 따라 다음/다음/설치
3. Windows 시작 메뉴에서 “AI PR Review” 검색 → 실행

1-2. 인증 방식 선택 (Claude Max / Anthropic API 키)

페이지 위쪽 흐름도에서 본 두 가지 방식 중 하나를 앱 첫 화면에서 선택합니다.

Claude Max 방식 — Claude.ai Max 구독자용

• 조건: Claude.ai Max 구독 + 본인 PC에 Claude Code CLI 설치 완료
  • Claude Code 설치 가이드: https://code.claude.com/docs
  • 설치 후 PowerShell에서 claude --version이 동작해야 함
• 절차: 앱 첫 화면 → “Claude Max” 모드 선택 → 끝 (API 키 입력 없음)
• 장점: 추가 비용 없음 (본인 Claude 구독료 외)
• 단점: 대화형 모드라 GitHub Actions 등 무인 자동화는 어려움

Anthropic API 키 방식 — 종량제, 자동화 가능

API 키 발급 단계:

1. https://console.anthropic.com/ 로그인 → 좌측 Settings → API Keys 진입
2. Create Key 버튼 → 이름 입력(예: pr-review-windows) → sk-ant-... 형식 키 생성·복사
3. (처음 사용 시) Billing 메뉴에서 결제 정보 등록 후 첫 $5 충전

앱 절차:

1. 앱 첫 화면 → “API Key” 모드 선택
2. 복사한 sk-ant-... 키를 입력란에 붙여넣기
3. 키는 Windows 자격 증명 관리자(wincred) 에 안전하게 저장됨 — 평문 파일에 남지 않음

장점: GitHub Actions·스크립트 등 자동화 호환. 단점: PR당 약 ₩200~500 종량제 비용.

선택 기준 한눈에:

본인 상황	권장 방식
Claude Pro/Max 이미 구독 중	Claude Max
자동화·CI에서 사용 예정	API 키
처음 써보고 비용 부담 없이 시작	Claude Max

1-3. GitHub 인증

private repo PR을 가져오려면 GitHub classic Personal Access Token이 필요합니다 (공개 repo만 사용한다면 생략 가능).

1. https://github.com/settings/tokens 진입 → Generate new token (classic)
2. Scope 항목에서 repo 체크 (private repo 포함). 공개 repo만 쓸 거면 public_repo만 체크해도 됨
3. 만료 기간 선택 후 생성 → ghp_... 형식 토큰 복사
4. 앱 우측 상단 Settings → GitHub Token 입력란에 붙여넣기

토큰도 Anthropic 키와 동일하게 wincred에 저장됩니다.

1-4. 첫 PR 리뷰 실행

1. 앱 메인 화면 → 리포지터리 드롭다운에서 PR을 분석할 repo 선택
2. 열린 PR 목록에서 대상 PR 클릭, 또는 PR URL을 직접 입력 (https://github.com/<org>/<repo>/pull/<번호>)
3. 리뷰 시작 버튼 클릭 → 약 3~5분 대기 (Claude Sonnet이 diff를 분석)
4. 우측 패널에 한국어 마크다운 리뷰가 출력됨 → 복사해서 PR 댓글로 붙여넣기

---

2. Claude Code CLI / Python CLI 방식 (개발자용)

자동화·CI/CD에 적합한 방식입니다. Windows 앱 대신 명령줄에서 직접 실행하거나, GitHub Action으로 PR이 열릴 때마다 자동 리뷰 댓글이 달리도록 만들 수 있습니다.

2-1. Python CLI 설치

요구 사항: Python 3.10+, Git.

PowerShell:

git clone https://github.com/ssallem/ai-pr-review-bot.git
Set-Location ai-pr-review-bot
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

bash:

git clone https://github.com/ssallem/ai-pr-review-bot.git
cd ai-pr-review-bot
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

설치 후 pr-review --help, pr-describe --help로 정상 동작 확인.

2-2. 환경 변수 설정

PowerShell:

Copy-Item .env.example .env
notepad .env

bash:

cp .env.example .env
${EDITOR:-vi} .env

.env에 채울 값:

• ANTHROPIC_API_KEY=sk-ant-... (필수) — 1-2절의 Anthropic 콘솔에서 발급
• GITHUB_TOKEN=ghp_... (선택, PR 댓글 작성 시 필수) — 1-3절의 classic PAT
• CLAUDE_MODEL=claude-sonnet-4-6 (선택, 기본값. 다른 모델로 바꿀 때만 지정)

2-3. CLI 명령 예시

# 로컬 diff 파일 리뷰
pr-review --from-file changes.diff

# stdin 즉시 리뷰 (마크다운 출력)
git diff main..HEAD | pr-review --from-stdin --output md

# GitHub PR 직접 가져와 리뷰 + 댓글 자동 작성
pr-review --pr ssallem/ai-pr-review-app#42 --post

# JSON 출력 (다른 도구·스크립트 연계)
pr-review --from-file changes.diff --output json

# PR 본문·체인지로그 자동 생성
pr-describe --branch feature/login --base main

2-4. GitHub Actions 자동화

매 PR마다 자동으로 한국어 리뷰가 댓글로 달리게 하려면:

1. 사용할 리포지터리에 .github/workflows/ 폴더가 없으면 생성하고, ai-pr-review-bot repo의 templates/pr-review.yml을 복사해 넣기
2. 그 리포지터리의 Settings → Secrets and variables → Actions → New repository secret
   • Name: ANTHROPIC_API_KEY
   • Value: 본인이 발급받은 sk-ant-... 키
3. GITHUB_TOKEN은 GitHub Actions 런타임이 자동으로 주입하므로 별도 설정 불필요
4. 이후 PR이 새로 열리거나 갱신될 때마다 워크플로우가 트리거되어 한국어 리뷰 댓글이 자동으로 달림

---

3. 자주 묻는 질문

Q. Claude Max와 Anthropic API 키, 어느 쪽이 나은가요? A. 이미 Claude.ai를 구독 중이면 Max 방식이 추가 비용 0입니다. 자동화(GitHub Actions)나 무인 백그라운드 실행이 필요하면 API 키 방식이 맞습니다. 리뷰 품질은 둘 다 동일합니다.

Q. 비용은 얼마나 드나요? A. API 키 방식 기준 평균 PR(약 300800줄 diff) 1회당 ₩200500입니다. Anthropic이 prompt caching을 적용해, 동일 PR을 재분석할 때는 추가 비용이 거의 0에 가깝습니다. Claude Max 방식은 본인 구독료 외 추가 비용이 없습니다.

Q. 한국어 리뷰 품질이 괜찮나요? A. 시스템 프롬프트가 한국어로 작성되어 있고, Claude Sonnet 4-6은 한국어 코드 리뷰에 강합니다. 변수명·주석은 영어 원문을 그대로 인용하고 설명만 한국어로 출력되어, 코드 가독성을 해치지 않습니다.

Q. Windows 앱에서 private repo도 됩니까? A. 됩니다. 1-3절 GitHub PAT 발급 시 repo scope를 포함하면 private repo의 PR도 정상적으로 가져옵니다.

Q. macOS/Linux 빌드는 언제 나오나요? A. v0.2에서 추가 예정입니다. 그동안은 2절의 Python CLI 방식 사용을 권장합니다 (macOS/Linux에서 동일하게 동작).

---

4. 문제 해결

ModuleNotFoundError: No module named 'pr_reviewer'

• 원인: editable install이 패키지를 못 찾는 케이스
• 해결: pyproject.toml의 [tool.setuptools.packages.find] 섹션에 다음 줄을 추가하고 재설치

  include = ["pr_reviewer*", "pr_describer*"]
  

  이후 python -m pip install -e ".[dev]" 재실행

Windows 앱에서 “API 키가 인식되지 않음”

• 원인: wincred 권한 또는 키 앞뒤에 보이지 않는 공백/줄바꿈
• 해결: 앱 Settings → Reset API Key 클릭 → 메모장에 키를 붙여넣고 공백 정리 후 다시 입력

GitHub Token으로 PR을 못 가져옴 (403 Forbidden)

• 원인: token scope 부족 또는 organization repo의 SAML SSO 미인증
• 해결: token 생성 시 repo scope가 체크돼 있는지 확인. organization repo라면 token 페이지에서 Configure SSO → 해당 org Authorize 클릭

리뷰가 3분 넘게 안 나옴

• 원인: 너무 큰 PR (5000줄 이상) 또는 Anthropic API의 일시적 정체
• 해결: PR을 기능 단위로 작게 쪼개 다시 시도하거나 잠시 후 재시도. 앱 진행 표시 화면에서 현재 단계(diff 수집 / 분석 중 / 결과 포맷팅)를 확인 가능

---

5. 더 알아보기

• GitHub — Windows 앱 소스: https://github.com/ssallem/ai-pr-review-app
• GitHub — Python CLI / GitHub Action 템플릿: https://github.com/ssallem/ai-pr-review-bot
• 데모 — 실제 리뷰 결과 예시: https://ai-review-kit.pages.dev/demo
• 다운로드 — Windows v1.0.1 직접 받기: https://ai-review-kit.pages.dev/download
• 문의 — 버그 제보·기능 제안: ssallem@kakao.com