OpenCodeReview

English | 简体中文 | 日本語 | 한국어 | Русский

Open Code Review란?

Open Code Review는 AI 기반 코드 리뷰 CLI 도구입니다. Alibaba Group의 내부 공식 AI 코드 리뷰 어시스턴트에서 시작했으며, 지난 2년 동안 수만 명의 개발자에게 제공되어 수백만 건의 코드 결함을 찾아냈습니다. 대규모 환경에서 충분히 검증한 뒤 커뮤니티를 위해 오픈 소스 프로젝트로 공개했습니다. 모델 endpoint만 설정하면 바로 사용할 수 있습니다.

이 도구는 Git diff를 읽고, 변경 파일을 tool-use 기능을 가진 agent를 통해 설정 가능한 LLM으로 전달한 뒤, 라인 단위 위치 정보가 포함된 구조화된 리뷰 코멘트를 생성합니다. agent는 전체 파일 내용 읽기, 코드베이스 검색, 다른 변경 파일 확인 등을 통해 맥락을 확보하고 표면적인 diff 피드백이 아닌 깊이 있는 리뷰를 수행할 수 있습니다. diff 리뷰 외에도 ocr scan은 전체 파일을 리뷰할 수 있어, 익숙하지 않은 코드베이스를 감사하거나 의미 있는 diff가 없는 디렉터리를 검토하는 데 유용합니다.

자세한 내용은 공식 웹사이트를 참조하세요.

벤치마크

범용 Agent(Claude Code)와 비교할 때, Open Code Review는 동일한 기반 모델에서 유의미하게 높은 정밀도(Precision)와 F1 점수를 달성하며, 토큰 소비량은 약 1/9 수준이고 리뷰 속도도 더 빠릅니다. 다만 재현율(Recall)은 범용 Agent보다 낮습니다 — 이는 노이즈를 줄이고 정밀도를 우선하는 설계적 트레이드오프입니다.

실제 코드 리뷰 기반 벤치마크. 50개 인기 오픈소스 저장소에서 200개 실제 Pull Request를 엄선하고, 10개 프로그래밍 언어를 커버 — 80명 이상의 시니어 엔지니어가 교차 검증(1,505개 어노테이션된 결함).

왜 Open Code Review인가?

범용 Agent의 문제

Claude Code Skills 같은 범용 agent로 코드 리뷰를 해봤다면 다음 문제를 경험했을 수 있습니다.

• 불완전한 커버리지: 큰 changeset에서는 일부 파일만 선택적으로 리뷰하고 중요한 파일을 놓치기 쉽습니다.
• 위치 드리프트: 지적된 문제가 실제 코드 위치와 맞지 않거나 라인 번호와 파일 참조가 어긋나는 일이 자주 발생합니다.
• 불안정한 품질: 자연어 기반 Skill은 디버깅이 어렵고, 작은 prompt 변화에도 리뷰 품질이 크게 흔들릴 수 있습니다.

근본 원인은 순수 언어 중심 아키텍처가 리뷰 프로세스에 강한 제약을 제공하지 못한다는 점입니다.

핵심 설계: 결정적 엔지니어링과 Agent의 하이브리드

Open Code Review의 핵심 철학은 결정적 엔지니어링과 agent를 결합해 각자가 가장 잘하는 일을 맡기는 것입니다.

결정적 엔지니어링: 강한 제약

반드시 정확해야 하는 리뷰 단계는 언어 모델이 아니라 엔지니어링 로직이 보장합니다.

• 정확한 파일 선택: 어떤 파일을 리뷰하고 어떤 파일을 필터링할지 결정해 중요한 변경이 누락되지 않도록 합니다.
• 스마트 파일 번들링: 관련 파일을 하나의 리뷰 단위로 묶습니다. 예를 들어 message_en.properties와 message_zh.properties를 함께 묶습니다. 각 번들은 독립된 context를 가진 sub-agent로 실행되며, 대규모 changeset에서도 안정적인 divide-and-conquer 전략과 동시 리뷰를 지원합니다.
• 세밀한 rule 매칭: 각 파일의 특성에 맞는 리뷰 rule을 매칭해 모델의 주의를 집중시키고 정보 노이즈를 줄입니다. 순수 자연어 기반 rule 안내보다 template engine 기반 rule 매칭이 더 안정적이고 예측 가능합니다.
• 외부 위치 지정 및 reflection 모듈: 독립적인 comment positioning과 comment reflection 모듈이 AI 피드백의 위치 정확도와 내용 정확도를 체계적으로 개선합니다.

Agent: 동적 의사결정

agent의 강점은 동적 판단과 동적 context 검색이 중요한 지점에 집중됩니다.

• 시나리오 최적화 prompt: 코드 리뷰에 깊이 최적화된 prompt template으로 효과를 높이고 token 사용량을 줄입니다.
• 시나리오 최적화 toolset: 대규모 production 데이터의 tool-call trace를 분석해 도출했습니다. 호출 빈도 분포, tool별 반복률, 신규 tool이 전체 call chain에 미치는 영향 등을 반영해 범용 agent toolkit보다 코드 리뷰에 더 안정적이고 예측 가능한 전용 toolset을 제공합니다.

사용 방법

사전 요구 사항

• Git >= 2.41 — Open Code Review는 diff 생성, 코드 검색, 저장소 작업에 Git을 사용합니다.

CLI

설치

NPM 사용(권장)

npm install -g @alibaba-group/open-code-review

설치 후 ocr 명령을 전역에서 사용할 수 있습니다.

GitHub Release 사용

명령 한 번으로 사용 중인 OS/아키텍처에 맞는 최신 binary를 설치합니다 (macOS / Linux):

curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh | sh

이 스크립트는 알맞은 릴리스 binary를 선택하고 SHA-256 체크섬을 검증한 뒤 ocr로 /usr/local/bin에 설치합니다. 설치 위치는 OCR_INSTALL_DIR로, 릴리스 버전은 OCR_VERSION으로 재정의할 수 있습니다:

OCR_INSTALL_DIR="$HOME/.local/bin" OCR_VERSION=v1.3.13 \
  sh -c "$(curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh)"

수동 다운로드 (Windows 포함 모든 플랫폼)

GitHub Releases에서 사용 중인 플랫폼의 binary를 다운로드합니다.

# macOS (Apple Silicon)
curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-arm64
chmod +x ocr && sudo mv ocr /usr/local/bin/ocr

# macOS (Intel)
curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-amd64
chmod +x ocr && sudo mv ocr /usr/local/bin/ocr

# Linux (x86_64)
curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-amd64
chmod +x ocr && sudo mv ocr /usr/local/bin/ocr

# Linux (ARM64)
curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-arm64
chmod +x ocr && sudo mv ocr /usr/local/bin/ocr

# Windows (x86_64): ocr.exe를 PATH에 포함된 디렉터리로 이동하세요
curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-amd64.exe

# Windows (ARM64): ocr.exe를 PATH에 포함된 디렉터리로 이동하세요
curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-arm64.exe

소스에서 빌드

git clone https://github.com/alibaba/open-code-review.git
cd open-code-review
make build
sudo cp dist/opencodereview /usr/local/bin/ocr

Quick Start

1. LLM 설정

코드 리뷰를 실행하기 전에 반드시 LLM을 설정해야 합니다.

OCR은 통합 Provider 시스템으로 LLM 설정을 관리합니다. 다양한 주요 provider가 내장되어 있으며, 프라이빗 배포 또는 기타 호환 엔드포인트에 연결하기 위한 커스텀 provider 추가도 지원합니다. 설정은 ~/.opencodereview/config.json에 저장됩니다.

Option A: 대화형 설정 (권장)

ocr config provider          # built-in provider 선택 또는 custom provider 추가
ocr config model             # 활성 provider의 model 선택

대화형 UI가 provider 선택, API key 입력, model 설정을 안내하며, 완료 후 자동으로 연결 테스트를 수행합니다.

ocr llm providers를 실행하면 모든 built-in provider를 확인할 수 있습니다. Built-in provider에는 API URL과 프로토콜이 사전 설정되어 있어 API key만 제공하면 바로 사용할 수 있습니다. 해당 환경 변수(예: ANTHROPIC_API_KEY, OPENAI_API_KEY)가 이미 설정되어 있으면 API key가 자동으로 읽힙니다.

커스텀 provider도 대화형 UI에서 추가할 수 있습니다 — provider 이름, API URL, 프로토콜 타입(anthropic 또는 openai), API key를 입력합니다.

Option B: CLI 설정 (CI/CD 등 비대화형 환경용)

ocr config set 명령으로 provider 설정을 직접 작성합니다. 스크립트 및 자동화에 적합합니다.

Built-in provider 사용:

ocr config set provider anthropic
ocr config set providers.anthropic.api_key your-api-key-here
ocr config set providers.anthropic.model claude-sonnet-4-6

커스텀 provider 사용 (프라이빗 게이트웨이 또는 기타 호환 엔드포인트):

ocr config set provider my-gateway
ocr config set custom_providers.my-gateway.url https://my-llm-gateway.internal/v1
ocr config set custom_providers.my-gateway.protocol openai
ocr config set custom_providers.my-gateway.api_key your-api-key-here
ocr config set custom_providers.my-gateway.model gpt-4o

커스텀 provider에서는 url과 protocol이 필수입니다. 지원 프로토콜: anthropic, openai.

선택 설정:

extra_headers (선택사항): 모든 LLM API 요청에 커스텀 HTTP 헤더를 추가합니다. 프록시, 게이트웨이, 추가 헤더가 필요한 엔터프라이즈 엔드포인트(조직 ID, 트레이싱 ID 등)에 유용합니다. 형식은 쉼표로 구분된 key=value 쌍입니다. 쉼표가 포함된 값은 큰따옴표로 묶으세요:

ocr config set llm.extra_headers "X-Org-ID=org-123,X-Forwarded-For=\"1.2.3.4,5.6.7.8\""

provider 별로 추가 헤더를 설정할 수도 있습니다:

ocr config set providers.anthropic.extra_headers "X-Org-ID=org-123"

환경 변수 (가장 높은 우선순위)

환경 변수는 설정 파일의 값을 덮어씁니다. 설정 파일 작성이 불편한 CI/CD 시나리오에 적합합니다:

export OCR_LLM_URL=https://api.anthropic.com/v1/messages
export OCR_LLM_TOKEN=your-api-key-here
export OCR_LLM_MODEL=claude-opus-4-6
export OCR_USE_ANTHROPIC=true

Claude Code 환경 변수(ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_MODEL)와도 호환되며, ~/.zshrc / ~/.bashrc의 export도 파싱합니다.

CC-Switch 사용자 참고: CC-Switch를 routing service와 함께 사용한다면, provider의 url을 CC-Switch proxy 주소로 지정하여 추가 설정 없이 사용할 수 있습니다: - Claude provider: providers.anthropic.url을 http://127.0.0.1:15721로 설정 - Codex provider: 해당 provider의 url을 http://127.0.0.1:15721/v1로 설정 - api_key는 아무 값이나 사용 가능, extra_body 설정은 그대로 적용됨

2. 연결 테스트

ocr llm test

3. 리뷰 실행

cd your-project

# Workspace mode: staged, unstaged, untracked 변경을 모두 리뷰
ocr review

# Branch range: 두 ref 비교
ocr review --from main --to feature-branch

# 단일 commit
ocr review --commit abc123

# 전체 파일 스캔 — diff 대신 파일 전체를 리뷰 (git 이력 불필요)
ocr scan                          # 전체 repository 스캔
ocr scan --path internal/agent    # 디렉터리 또는 특정 파일 스캔

Coding Agent와 통합

OCR은 AI coding agent에 slash command로 자연스럽게 통합할 수 있으며, agent workflow 안에서 바로 코드 리뷰를 실행할 수 있습니다.

Option 1: Skill로 설치

npx로 OCR skill을 프로젝트에 설치합니다.

npx skills add alibaba/open-code-review --skill open-code-review

이 명령은 skills registry의 open-code-review skill을 설치합니다. 이 skill은 coding agent가 ocr을 호출해 코드 리뷰를 수행하고, issue를 우선순위별로 분류하며, 필요한 경우 fix를 적용하는 방법을 알려줍니다.

Option 2: Claude Code Plugin으로 설치

Claude Code에서는 Claude Code 안에서 다음 명령으로 command plugin을 설치합니다.

/plugin marketplace add alibaba/open-code-review
/plugin install open-code-review@open-code-review

이렇게 하면 OCR을 실행하고 issue를 자동으로 필터링 및 수정하는 /open-code-review:review slash command가 등록됩니다.

Option 3: Codex Plugin으로 설치

local Codex에서는 이 repository에서 Open Code Review plugin을 설치합니다.

codex plugin marketplace add alibaba/open-code-review
codex
/plugins

local checkout이나 fork에서는 다음을 사용할 수 있습니다.

codex plugin marketplace add .
codex
/plugins

Open Code Review를 설치하고 활성화한 뒤, 새 Codex thread를 시작해 명시적으로 호출합니다.

@Open Code Review review my current changes
@Open Code Review review this branch against main
@Open Code Review review and fix high-confidence issues

이 plugin은 local OCR CLI를 실행하는 Codex skill을 등록합니다.

ocr review --audience agent

이 통합은 OCR의 내부 LLM backend를 변경하지 않으며 Codex용 OpenAI Responses API endpoint 설정을 요구하지 않습니다. OCR 자체는 CLI 설정 섹션에 설명된 대로 ocr CLI 설치와 설정이 필요합니다.

한국어 가이드: plugins/open-code-review/CODEX.ko-KR.md

Option 4: Cursor Plugin으로 설치

Cursor에서는 이 repository에서 Open Code Review plugin을 설치합니다:

cursor-plugin marketplace add alibaba/open-code-review

수동으로 marketplace를 추가할 수도 있습니다. Cursor에서 /plugins를 열고 Open Code Review를 검색하여 설치합니다.

local checkout이나 fork에서는 다음을 사용할 수 있습니다:

cursor-plugin marketplace add .

설치 후, Cursor에서 다음과 같이 호출합니다:

@Open Code Review review my current changes
@Open Code Review review this branch against main
@Open Code Review review and fix high-confidence issues

이 plugin은 local OCR CLI를 실행하는 Cursor skill을 등록합니다:

ocr review --audience agent

이 통합은 OCR의 내부 LLM backend를 변경하지 않습니다. OCR 자체는 CLI 설정 섹션에 설명된 대로 ocr CLI 설치와 설정이 필요합니다.

Option 5: Command 파일 직접 복사

package manager 없이 빠르게 설정하려면 command 파일을 복사해 Claude Code에서 /open-code-review slash command를 사용할 수 있습니다.

Project-level(git으로 팀과 공유):

mkdir -p .claude/commands
curl -o .claude/commands/open-code-review.md \
  https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/commands/review.md

User-level(여러 프로젝트에서 개인 전역 사용):

```bash mkdir -p ~/.claude/commands curl -o ~/.claude/commands/open-code-review.md \ https://raw.githubusercontent.com/alibaba/open-code-rev