AI 코드 리뷰

AI 코드 리뷰은(는) 무엇을 하나요?

CLI를 통해 세션 중간에 다른 AI 모델에 코드 리뷰를 요청합니다.

사전 요구사항

• gemini CLI 설치 (다음 명령어 실행: ${CLAUDE_SKILL_DIR}/scripts/install-dependencies.sh)
• 인증: GEMINI_API_KEY 환경 변수 (권장 — 아래 "유료 API" 참조) 또는 Google 계정 OAuth (gemini를 한 번 대화형으로 실행)
• 선택 사항: OpenAI 리뷰를 위한 codex CLI: brew install codex

중요: 리뷰를 절대 건너뛰지 마십시오

속도보다 품질. 리뷰가 요청되면 반드시 결과를 기다려야 합니다. 다음을 수행하지 마십시오:

• 속도 제한이나 타임아웃 때문에 리뷰를 건너뛰기
• 리뷰 없이 진행하고 "나중에 검토하자"고 말하기
• 외부 모델을 호출하지 않고 자신의 리뷰로 대체하기

gemini CLI는 속도 제한 재시도를 자동으로 처리합니다. 스크립트가 타임아웃(종료 코드 2)으로 종료되면 사용자에게 도움을 요청하십시오 — 조용히 계속 진행하지 마십시오.

속도 제한 (무료 티어 — Google 계정 인증)

항목	제한
분당 요청 수	60 RPM
하루 요청 수	1,000 RPD
용량(토큰/시간)	매우 낮음 — 실제 병목 구간
모델	Google에서 자동 선택 (시간이 지남에 따라 업그레이드)
비용	$0

중요: RPM/RPD 제한이 문제가 되는 경우는 드뭅니다. Google은 훨씬 더 제한적인 용량 할당량(롤링 시간 창 동안 처리된 총 토큰 수)도 시행합니다. 많은 코드와 자동 컨텍스트를 포함하는 큰 리뷰 페이로드는 단 몇 번의 요청만으로 이 할당량을 소진시켜 몇 시간(보통 1-3시간) 동안 재설정되는 TerminalQuotaError를 유발할 수 있습니다. 이는 특히 새로운 자동 선택 모델(예: Gemini 2.5 Pro)에서 매우 제한적입니다.

할당량 압력을 줄이려면:

• 작고 집중된 리뷰에는 --no-context를 사용하여 토큰 사용량을 줄이십시오.
• 큰 리뷰는 더 작은 덩어리로 나누십시오.
• 용량 제한을 완전히 피하려면 유료 API 키를 사용하십시오(아래 참조).

CLI는 분당 속도 제한(초 단위로 재설정)에 도달하면 자동으로 재시도합니다. 용량 할당량은 재시도하지 않습니다 — 재설정 기간을 기다려야 합니다. 스크립트에는 1시간 타임아웃이 있습니다 — 이를 초과하면 스크립트가 중단되며, 사용자에게 도움을 요청해야 합니다.

유료 API (정기 사용에 권장)

무료 티어의 용량 할당량은 세션당 몇 번 이상의 리뷰를 수행하기 어렵게 만듭니다. 유료 API 키는 최소한의 비용으로 이 병목 현상을 제거합니다.

설정

1. Google AI Studio에서 키를 받습니다.
2. 연결된 Google Cloud 프로젝트에서 청구를 활성화합니다. — 청구가 없으면 API 키는 여전히 무료 티어 용량 제한(OAuth와 동일한 병목 현상)을 사용합니다. AI Studio: 설정 → 결제, 또는 Google Cloud Console에서 수행합니다.
3. gemini CLI가 API 키 인증을 사용하도록 구성합니다:

   # gemini 설정(~/.gemini/settings.json)에서 인증 유형 설정
   # gemini를 한 번 대화형으로 실행하면 인증 방법을 선택하라는 메시지가 표시됩니다.
   # 메시지가 표시되면 "Gemini API Key"를 선택하십시오.
   

4. 환경 변수를 설정합니다:

   export GEMINI_API_KEY="your-key-here"
   

   새 셸에서 이 변수를 사용할 수 있도록 셸 프로필에 추가하십시오. 이미 실행 중인 세션(예: Claude Code)에 있으면 파일을 소싱하거나 세션을 다시 시작해야 합니다.
5. 작동 확인: gemini -p "hello" — OAuth 프롬프트나 할당량 오류 없이 응답해야 합니다.

비용 추정 (Gemini 2.5 Pro)

	토큰	비용
리뷰당 입력(컨텍스트 + diff)	~8-12K	~$0.01-0.015
리뷰당 출력	~1-2K	~$0.01-0.02
리뷰당 총계		~$0.02-0.04

사용 수준	월 리뷰 수	예상 비용
가벼움(주에 몇 번)	~20	~$0.50
보통(하루에 몇 번)	~60	~$1.50
많음(하루에 여러 번)	~150	~$4.00

사용량 추적

• AI Studio → 대시보드 → 사용량 탭(요청, 토큰, 비용)
• Google Cloud Console → APIs & Services → 대시보드 → "Generative Language API"
• 결제 보고서 → SKU별 그룹화하여 모델별 분석
• 팁: 동일한 프로젝트에 여러 키를 생성하여 AI 리뷰 사용량을 대화형 gemini CLI 사용량과 분리하십시오.

사용 방법

1단계: 리뷰할 항목 결정

컨텍스트에 따라 선택합니다:

상황	보낼 내용
방금 코드를 작성함	변경된 특정 파일
기능 개발 중	git diff (언스테이징 변경사항)
커밋 전	git diff --cached (스테이징 변경사항)
브랜치 리뷰	git diff main...HEAD
특정 우려 사항	단일 파일 또는 함수

2단계: 리뷰 실행

${CLAUDE_SKILL_DIR}/scripts/review.sh 경로에 있는 리뷰 스크립트를 사용하십시오. 이 경로는 현재 작업 디렉토리에 관계없이 스킬의 자체 디렉토리로 확인됩니다. 절대 ./scripts/review.sh를 사용하지 마십시오(현재 작업 디렉토리를 기준으로 하므로 다른 저장소에서는 실패합니다). 절대 gemini나 codex에 직접 코드를 파이프로 전달하지 마십시오 — 항상 리뷰 스크립트를 사용하십시오.

# 언스테이징 변경사항 리뷰 (기본값)
${CLAUDE_SKILL_DIR}/scripts/review.sh

# 스테이징 변경사항 리뷰
${CLAUDE_SKILL_DIR}/scripts/review.sh --staged

# 특정 파일 리뷰
${CLAUDE_SKILL_DIR}/scripts/review.sh path/to/file1.swift path/to/file2.swift

# main 브랜치와의 diff 리뷰
${CLAUDE_SKILL_DIR}/scripts/review.sh --branch

# 원격 브랜치와의 diff 리뷰 (main에서 직접 작업 중일 때)
REVIEW_BASE_BRANCH=origin/main ${CLAUDE_SKILL_DIR}/scripts/review.sh --branch

# 더 나은 리뷰를 위한 추가 컨텍스트 문자열
${CLAUDE_SKILL_DIR}/scripts/review.sh --context "SwiftUI 앱, iOS 18+, Swift 6" path/to/file.swift

# 특정 계획 파일과 함께 리뷰
${CLAUDE_SKILL_DIR}/scripts/review.sh --plan PLAN.md path/to/file.swift

# 자동 컨텍스트 건너뛰기 (코드/diff만 전송)
${CLAUDE_SKILL_DIR}/scripts/review.sh --no-context --staged

3단계: 피드백에 따른 조치

리뷰를 받은 후:

1. ERROR 심각도 문제는 즉시 해결합니다.
2. WARNING 항목을 고려합니다 — 좋은 이유가 없다면 수정합니다.
3. INFO 항목은 제안 사항입니다 — 판단하여 적용합니다.
4. 리뷰가 확실하지 않은 질문을 제기하면 사용자와 논의합니다.

오류 처리

종료 코드	의미	조치
0	성공	리뷰 피드백에 따라 조치
1	리뷰할 코드 없음 / 잘못된 인수	인수 확인
2	타임아웃 (1시간 이상 차단됨)	사용자에게 도움 요청 — 리뷰를 건너뛰지 마십시오

자동 컨텍스트

리뷰 스크립트는 모든 리뷰에 프로젝트 컨텍스트를 자동으로 추가하여 리뷰어가 규칙, 아키텍처 및 의도를 이해할 수 있도록 합니다. CLAUDE.md에 수동으로 "Code Review Context" 섹션을 추가할 필요가 없습니다.

자동 포함 (순서대로):

1. 구현 계획 — 다음 중 첫 번째로 발견된 항목: --plan 플래그, 저장소 루트의 PLAN.md, 가장 최근의 .claude/plans/*.md
2. 프로젝트 지침 — 다음 중 첫 번째로 발견된 항목: 저장소 루트의 CLAUDE.md, GEMINI.md, AGENTS.md
3. 파일 트리 — 깊이 3의 저장소 구조

이를 건너뛰려면 --no-context를 사용하십시오(예: 매우 큰 페이로드의 경우).

--context 플래그는 자동 컨텍스트 위에 추가 인라인 컨텍스트 문자열을 추가합니다.

제공자 구성

기본 제공자는 gemini입니다. 세션별로 재정의:

# 대신 OpenAI 사용
REVIEW_PROVIDER=codex ${CLAUDE_SKILL_DIR}/scripts/review.sh

중요 참고 사항

• 리뷰는 참고용입니다 — 두 번째 모델이 오탐지를 생성할 수 있습니다.
• 큰 diff(50KB 초과)는 잘릴 수 있습니다. 필요한 경우 더 작은 리뷰로 나누십시오.
• 리뷰 모델은 프롬프트 모드(-p)에서 실행되며 저장소를 탐색할 수 없습니다. 프로젝트 컨텍스트가 이를 보완하기 위해 자동으로 포함됩니다 — 위의 "자동 컨텍스트"를 참조하십시오.