alibaba/open-code-review

Open Code Review란 무엇인가?

Open Code Review는 AI 기반 코드 리뷰 CLI 도구입니다. 알리바바 그룹의 공식 내부 AI 코드 리뷰 어시스턴트로 시작되어, 지난 2년간 수만 명의 개발자에게 서비스를 제공하고 수백만 개의 코드 결함을 식별했습니다. 대규모 환경에서 철저히 검증된 후, 커뮤니티를 위해 오픈소스 프로젝트로 전환되었습니다. 모델 엔드포인트만 구성하면 바로 사용할 수 있습니다.

Git diff를 읽고, 변경된 파일을 도구 사용이 가능한 에이전트를 통해 구성 가능한 LLM에 전송하여 라인 수준의 정밀한 구조화된 리뷰 코멘트를 생성합니다. 에이전트는 전체 파일 내용을 읽고, 코드베이스를 검색하고, 컨텍스트를 위해 다른 변경된 파일을 검사하여 표면적인 diff 피드백 이상의 심층 리뷰를 생성할 수 있습니다. diff 리뷰 외에도 ocr scan은 전체 파일을 리뷰하여 의미 있는 diff가 없는 익숙하지 않은 코드베이스나 디렉토리를 감사하는 데 사용됩니다.

벤치마크

범용 에이전트(Claude Code)와 비교하여 Open Code Review는 동일한 기본 모델로 훨씬 더 높은 정밀도(Precision)와 F1 점수를 달성하면서도 약 1/9의 토큰만 소비하고 더 빠르게 리뷰를 완료합니다. 재현율(Recall)은 범용 에이전트보다 낮은데, 이는 노이즈보다 정밀도를 우선시하는 의도적인 트레이드오프입니다.

50개의 인기 오픈소스 저장소, 200개의 실제 Pull Request, 10개의 프로그래밍 언어로 구성된 실제 코드 리뷰 벤치마크로, 80명 이상의 시니어 엔지니어가 교차 검증했습니다(1,505개의 주석이 달린 정답 이슈).

왜 Open Code Review인가?

범용 에이전트의 문제점

코드 리뷰를 위해 Skills와 함께 Claude Code와 같은 범용 에이전트를 사용해 본 적이 있다면 다음과 같은 문제점을 경험했을 것입니다:

• 불완전한 커버리지 — 변경 사항이 큰 경우 에이전트가 '지름길'을 선택하여 일부 파일만 선택적으로 리뷰하고 다른 파일은 놓치는 경향이 있습니다.
• 위치 오류 — 보고된 이슈가 실제 코드 위치와 일치하지 않는 경우가 많으며, 줄 번호나 파일 참조가 빗나갑니다.
• 불안정한 품질 — 자연어 기반 Skills는 디버깅이 어렵고, 사소한 프롬프트 변형에도 리뷰 품질이 크게 변동합니다.

근본 원인: 순수 언어 기반 아키텍처는 리뷰 프로세스에 대한 하드 제약 조건이 부족합니다.

핵심 설계: 결정론적 엔지니어링 × 에이전트 하이브리드

Open Code Review의 핵심 철학은 결정론적 엔지니어링과 에이전트를 결합하여 각각이 가장 잘하는 부분을 처리하는 것입니다.

결정론적 엔지니어링 — 하드 제약 조건

절대 실패해서는 안 되는 리뷰 단계의 경우, 언어 모델이 아닌 엔지니어링 로직이 정확성을 보장합니다:

• 정확한 파일 선택 — 리뷰가 필요한 파일과 필터링해야 할 파일을 정확히 결정하여 중요한 변경 사항을 놓치지 않도록 합니다.
• 스마트 파일 번들링 — 관련 파일을 단일 리뷰 단위로 그룹화합니다(예: messageen.properties와 messagezh.properties가 함께 번들링됨). 각 번들은 격리된 컨텍스트를 가진 하위 에이전트로 실행됩니다. 이는 분할 정복 전략으로, 매우 큰 변경 사항에서도 안정적으로 유지되며 자연스럽게 동시 리뷰를 지원합니다.
• 세분화된 규칙 매칭 — 각 파일의 특성에 리뷰 규칙을 매칭하여 모델의 주의를 예리하게 집중시키고 정보 노이즈를 원천적으로 제거합니다. 순수 언어 기반 규칙 안내와 비교하여 템플릿 엔진 기반 규칙 매칭은 더 안정적이고 예측 가능합니다.
• 외부 위치 지정 및 반영 모듈 — 독립적인 코멘트 위치 지정 및 코멘트 반영 모듈은 AI 피드백의 위치 정확도와 내용 정확도를 체계적으로 개선합니다.

에이전트 — 동적 의사 결정

에이전트의 강점은 동적 의사 결정과 동적 컨텍스트 검색이 가장 중요한 부분에 집중됩니다:

• 시나리오에 맞춘 프롬프트 — 코드 리뷰에 깊이 최적화된 프롬프트 템플릿으로, 효과성을 높이면서 토큰 소비를 줄입니다.
• 시나리오에 맞춘 도구 세트 — 대규모 프로덕션 데이터의 도구 호출 추적에 대한 심층 분석(호출 빈도 분포, 도구별 반복률, 새로운 도구가 전체 호출 체인에 미치는 영향 포함)을 통해 추출되어, 범용 에이전트 도구 키트보다 코드 리뷰에 더 안정적이고 예측 가능한 목적에 맞게 구축된 도구 세트를 제공합니다.

사용 방법

CLI

설치

NPM을 통해 (권장)

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

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

GitHub Release에서 설치

한 줄 명령어로 OS/아키텍처에 맞는 최신 바이너리를 설치합니다 (macOS / Linux):

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

스크립트는 올바른 릴리스 바이너리를 선택하고, SHA-256 체크섬을 확인한 후 /usr/local/bin에 ocr로 설치합니다. OCRINSTALLDIR로 대상을 재정의하거나 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)"

<details> <summary>수동 다운로드 (Windows 포함 모든 플랫폼)</summary>

GitHub Releases에서 플랫폼에 맞는 바이너리를 다운로드하세요:

# 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

</details>

소스에서 빌드

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

빠른 시작

1. LLM 구성

코드 리뷰 전에 LLM을 반드시 구성해야 합니다.

OCR은 통합 Provider 시스템을 통해 LLM 구성을 관리합니다. 많은 인기 있는 내장 프로바이더를 제공하며, 비공개 배포나 기타 호환 엔드포인트에 연결하기 위해 사용자 정의 프로바이더를 추가하는 것도 지원합니다. 구성은 ~/.opencodereview/config.json에 저장됩니다.

옵션 A: 대화형 설정 (권장)

ocr config provider          # 내장 프로바이더 선택 또는 사용자 정의 프로바이더 추가
ocr config model             # 활성 프로바이더의 모델 선택

대화형 UI는 프로바이더 선택, API 키 입력, 모델 구성을 안내한 후 자동으로 연결을 테스트합니다.

ocr llm providers를 실행하여 모든 내장 프로바이더를 확인하세요. 내장 프로바이더는 사전 설정된 API URL과 프로토콜을 제공하므로 API 키만 제공하면 시작할 수 있습니다. 해당 환경 변수(예: ANTHROPICAPIKEY, OPENAIAPIKEY)가 이미 설정된 경우 API 키가 자동으로 감지됩니다.

사용자 정의 프로바이더는 대화형 UI를 통해 추가할 수 있으며, 이름, API URL, 프로토콜 유형(anthropic 또는 openai), API 키를 제공해야 합니다.

옵션 B: CLI 설정 (CI/CD 및 비대화형 환경용)

ocr config set을 사용하여 프로바이더 구성을 직접 작성할 수 있으며, 스크립트 및 자동화에 적합합니다.

내장 프로바이더 사용:

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

사용자 정의 프로바이더 사용 (비공개 게이트웨이 또는 기타 호환 엔드포인트):

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

url과 protocol은 사용자 정의 프로바이더에 필수입니다. 지원되는 프로토콜: anthropic, openai.

선택적 설정:

2. 리뷰 실행

# 현재 브랜치의 변경 사항 리뷰 (기본 브랜치와 비교)
ocr review

# 특정 브랜치와 비교
ocr review --base main

# 특정 커밋 범위 리뷰
ocr review --commit-range HEAD~3..HEAD

# 전체 파일 스캔 (diff 없음)
ocr scan./src

3. 출력 이해

OCR은 표준 출력에 구조화된 리뷰 결과를 생성합니다. 각 이슈에는 다음이 포함됩니다:

• 파일 경로 — 이슈가 발견된 파일
• 줄 번호 — 정확한 코드 위치
• 심각도 — critical, warning, suggestion
• 범주 — correctness, security, performance, style, best-practice
• 설명 — 이슈에 대한 자세한 설명
• 제안 — 문제 해결을 위한 구체적인 코드 제안

출력 예시:

{
  "file": "src/main/java/com/example/UserService.java",
  "line": 42,
  "severity": "critical",
  "category": "security",
  "description": "Potential SQL injection vulnerability: user input is directly concatenated into SQL query.",
  "suggestion": "Use parameterized queries or prepared statements instead of string concatenation."
}

4. CI/CD 통합

OCR은 CI/CD 파이프라인에 쉽게 통합될 수 있습니다. 다음은 GitHub Actions 예시입니다:

name: Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install OCR
        run: |
          curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh | sh
      - name: Run Code Review
        run: |
          ocr review --base ${{ github.event.pull_request.base.ref }} \
            --format github-annotation \
            --output annotations.json
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
      - name: Post Annotations
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const annotations = JSON.parse(fs.readFileSync('annotations.json', 'utf8'));
            // GitHub Check Run API를 사용하여 어노테이션 게시

아키텍처

Open Code Review는 다음과 같은 주요 구성 요소로 구성됩니다:

1. Diff 파서 — Git diff를 구문 분석하고 변경된 파일과 줄 번호를 추출합니다.
2. 파일 선택기 — 리뷰할 파일을 결정하고 불필요한 파일을 필터링합니다.
3. 번들러 — 관련 파일을 단일 리뷰 단위로 그룹화합니다.
4. 규칙 엔진 — 파일 특성에 리뷰 규칙을 매칭합니다.
5. 에이전트 — LLM과 상호 작용하여 리뷰를 생성합니다.
6. 위치 지정 모듈 — 코멘트 위치의 정확성을 보장합니다.
7. 반영 모듈 — 코멘트 내용의 정확성을 검증합니다.

내장 규칙

OCR은 일반적인 코드 결함을 탐지하기 위해 미세 조정된 내장 규칙 세트와 함께 제공됩니다:

• Null Pointer Exception (NPE) — 잠재적인 null 역참조 탐지
• Thread Safety — 동시성 문제 식별
• Cross-Site Scripting (XSS) — XSS 취약점 탐지
• SQL Injection — SQL 인젝션 취약점 탐지
• 리소스 누수 — 닫히지 않은 리소스 식별
• 코드 스타일 — 코딩 표준 위반 플래그 지정

지원되는 플랫폼

• Windows
• macOS
• Linux

지원되는 에이전트

• Claude Code
• Codex
• Cursor

라이선스

Apache-2.0