Open Code Review – AI 기반 코드 리뷰 CLI 도구

오픈 소스 AI 코드 리뷰 에이전트.

English | 简体中文

Open Code Review는 AI 기반 코드 리뷰 CLI (Command Line Interface) 도구입니다. 이 도구는 Alibaba Group의 내부 공식 AI 코드 리뷰 어시스턴트로 시작되었습니다. 지난 2년 동안 수만 명의 개발자에게 서비스를 제공했으며 수백만 개의 코드 결함을 식별했습니다. 대규모 검증을 거친 후, 커뮤니티를 위해 오픈 소스 프로젝트로 육성되었습니다. 모델 엔드포인트(model endpoint)를 설정하기만 하면 바로 시작할 수 있습니다.

이 도구는 Git diff를 읽고, 도구 사용(tool-use) 능력을 갖춘 에이전트(agent)를 통해 변경된 파일을 설정 가능한 LLM (Large Language Model)으로 전송하며, 라인 단위의 정밀도를 가진 구조화된 리뷰 코멘트를 생성합니다. 에이전트는 파일 전체 내용을 읽고, 코드베이스(codebase)를 검색하며, 문맥 파악을 위해 다른 변경된 파일들을 검사하여 단순한 표면적 diff 피드백이 아닌 심층적인 리뷰를 수행할 수 있습니다.

만약 코드 리뷰를 위해 Skills 기능이 포함된 Claude Code와 같은 범용 에이전트를 사용해 보셨다면, 다음과 같은 문제점들을 경험했을 가능성이 높습니다:

불완전한 커버리지 (Incomplete coverage)— 규모가 큰 변경 사항(changeset)의 경우, 에이전트는 일부 파일만 선택적으로 리뷰하고 다른 파일은 놓치는 등

and message_zh.properties가 함께 번들링됩니다). 각 번들은 격리된 컨텍스트(isolated context)를 가진 서브 에이전트(sub-agent)로 실행됩니다. 이는 매우 큰 변경 사항(changeset)에서도 안정성을 유지하고 자연스럽게 병렬 리뷰(concurrent review)를 지원하는 분할 정복(divide-and-conquer) 전략입니다. 세밀한 규칙 매칭 (Fine-grained rule matching)— 리뷰 규칙을 각 파일의 특성에 맞게 매칭하여, 모델의 주의력(attention)을 날카롭게 집중시키고 정보 노이즈를 근본적으로 제거합니다. 순수하게 언어 기반의 규칙 가이드와 비교했을 때, 템플릿 엔진 기반의 규칙 매칭은 더 안정적이고 예측 가능합니다. 외부 위치 지정 및 반영 모듈 (External positioning and reflection modules)— 독립적인 코멘트 위치 지정(comment-positioning) 및 코멘트 반영(comment-reflection) 모듈은 AI 피드백의 위치 정확도와 내용 정확도를 체계적으로 향상시킵니다.

에이전트 (Agent) — 동적 의사결정 (Dynamic Decision-Making)

에이전트의 강점은 가장 중요한 부분, 즉 동적 의사결정(dynamic decisions)과 동적 컨텍스트 검색(dynamic context retrieval)에 집중되어 있습니다:

시나리오 최적화 프롬프트 (Scenario-tuned prompts)— 코드 리뷰를 위해 깊이 최적화된 프롬프트 템플릿으로, 토큰 소비를 줄이면서 효과를 높입니다. 시나리오 최적화 도구 세트 (Scenario-tuned toolset)— 호출 빈도 분포, 도구별 반복률, 새로운 도구가 전체 호출 체인에 미치는 영향 등 대규모 프로덕션 데이터의 도구 호출 추적(tool-call traces)에 대한 심층 분석을 통해 정제되었습니다. 그 결과, 일반적인 에이전트 도구 모음보다 코드 리뷰에 더 안정적이고 예측 가능한 목적 맞춤형 도구 세트를 제공합니다.

NPM을 통한 설치 (권장)

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

설치 후, ocr 명령어를 전역적으로 사용할 수 있습니다.

GitHub Release를 통한 설치

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
...

소스 코드를 통한 설치

git clone https://github.com/alibaba/open-code-review.git
cd open-code-review
make build
...

1. LLM 설정

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

# Option A: 대화형 설정 (Interactive config)
oer config set llm.url https://api.anthropic.com/v1/messages
oer config set llm.auth_token your-api-key-here
...

설정(Config)은 ~/.opencodereview/config.json에 저장됩니다.

또한 Claude Code 환경 변수(ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_MODEL)와도 호환되며, 해당 export 설정을 위해 ~/.zshrc / ~/.bashrc를 파싱합니다.

CC-Switch 사용자 참고 사항: 라우팅 서비스(routing service)가 활성화된 상태로 CC-Switch를 사용하는 경우, 추가 설정 없이 llm.url을 CC-Switch 프록시 주소로 지정할 수 있습니다:

• Claude provider의 경우: llm.url을 http://127.0.0.1:15721로 설정
• CodeX provider의 경우: llm.url을 http://127.0.0.1:15721/v1로 설정
• 제공자(provider) 설정에 따라 llm.model을 설정하세요.
• llm.auth_token은 어떤 값이라도 상관없습니다.
• extra_body 설정은 여전히 적용됩니다.

2. 연결 테스트 (Test Connectivity)

ocr llm test

3. 리뷰 (Review)

cd your-project
# 워크스페이스 모드 (Workspace mode) — 스테이징(staged), 스테이징되지 않은(unstaged), 추적되지 않은(untracked) 모든 변경 사항을 리뷰합니다.
oer review
...

OCR은 AI 코딩 에이전트(AI coding agents)에 슬래시 명령어(slash command)로 매끄럽게 통합되어, 에이전트 워크플로 내에서 직접 코드 리뷰를 수행할 수 있습니다.

npx를 사용하여 프로젝트에 OCR 스킬(skill)을 설치하세요:

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

이 명령은 스킬 레지스트리(skills registry)에서 open-code-review 스킬을 설치하며, 이를 통해 코딩 에이전트가 코드 리뷰를 위해 ocr을 호출하는 방법, 이슈를 우선순위에 따라 분류하는 방법, 그리고 선택적으로 수정 사항을 적용하는 방법을 학습하게 됩니다.

Claude Code의 경우, Claude Code 내에서 다음 명령어를 통해 커맨드 플러그인(command plugin)을 설치하세요:

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

이를 통해 OCR을 실행하고 이슈를 자동으로 필터링 및 수정하는 /open-code-review:review 슬래시 명령어가 등록됩니다.

패키지 관리자 없이 빠르게 설정하려면, 명령 파일(command file)을 단순히 복사하여 Claude Code에서 /open-code-review 슬래시 명령어를 사용하면 됩니다.

프로젝트 레벨 (Project-level) (git을 통해 팀과 공유):

mkdir -p .claude/commands
curl -o .claude/commands/open-code-review.md \

사용자 레벨 (User-level) (모든 프로젝트에서 개인적으로 전역 사용):

mkdir -p ~/.claude/commands
curl -o ~/.claude/commands/open-code-review.md \

전제 조건: 모든 통합 방법은 ocr CLI가 설치되어 있고 LLM (Large Language Model)이 설정되어 있어야 합니다. 상단의 'LLM 설치 및 설정' 섹션을 참조하세요.

OCR은 CI/CD 파이프라인에 통합되어 Merge Request / Pull Request에 대한 코드 리뷰를 자동화할 수 있습니다.

CI 통합을 위한 핵심 명령어:

ocr review \
--from "origin/main" \
--to "origin/feature-branch" \
...

--format json 플래그는 CI 스크립트에서 파싱하기 적합한 기계 판독 가능 (machine-readable) 결과를 출력합니다.

통합 예시는 examples/ 디렉토리를 참조하세요:

github_actions/ — GitHub Actions 통합 예시
gitlab_ci/ — GitLab CI 통합 예시

명령어	별칭 (Alias)	설명
ocr review	ocr r	코드 리뷰 시작
ocr rules check <file>	—	특정 파일 경로에 어떤 리뷰 규칙이 적용되는지 미리 보기
ocr config set <key> <value>	—	설정 값 설정
ocr llm test	—	LLM 연결 테스트
ocr viewer	ocr v	localhost:5483에서 WebUI 세션 뷰어 실행
ocr version	—	버전 정보 표시

플래그 (Flag)	약어 (Shorthand)	기본값 (Default)	설명 (Description)
--repo	—	현재 디렉토리 (current dir)	Git 저장소 루트 (Git repository root)
--from	—	—	소스 참조 (Source ref, 예: main)
--to	—	—	대상 참조 (Target ref, 예: feature-branch)
--commit	-c	—	리뷰할 단일 커밋 (Single commit to review)
--preview	-p	false	LLM을 실행하지 않고 리뷰될 파일들을 미리 보기 (Preview which files will be reviewed without running the LLM)
--format	-f	text	출력 형식 (Output format): text 또는 json
--concurrency	—	8	최대 동시 파일 리뷰 수 (Max concurrent file reviews)
--timeout	—	10	동시 작업 타임아웃 (분 단위) (Concurrent task timeout in minutes)
--audience	—	human	human (진행 상황 표시) 또는 agent (요약만 표시)
--rule	—	—	사용자 정의 JSON 리뷰 규칙 경로 (Path to custom JSON review rules)
--max-tools	—	내장됨 (built-in)	파일당 최대 도구 호출 라운드 (Max tool call rounds per file); 템플릿 기본값보다 클 경우에만 적용됨
--tools	—	—	사용자 정의 JSON 도구 설정 경로 (Path to custom JSON tools config)

# 리뷰될 파일 미리 보기 (LLM 호출 없음)
ocr review --preview
ocr review -c abc123 -p
...

뷰어(Viewer)는 HTTP를 통해 세션 JSONL 콘텐츠(LLM 요청 메시지 및 응답)를 제공합니다. 모든 요청에 대해 Host 헤더 허용 목록(allowlist)을 강제합니다: 루프백 이름(localhost, 127.0.0.0/8, ::1)과 실제 바인딩된 호스트는 항상 허용됩니다. 와일드카드 바인딩(--addr :3000, --addr 0.0.0.0:3000) 및 기타 비-루프백 호스트 이름(Hostnames)은 OCR_VIEWER_ALLOWED_HOSTS 환경 변수(쉼표로 구분)를 통해 추가해야 합니다:

OCR_VIEWER_ALLOWED_HOSTS=review.internal,ocr.lan ocr viewer --addr :3000

이는 로컬 뷰어를 대상으로 하는 DNS 리바인딩(DNS-rebinding) 공격을 차단합니다.

OCR은 4단계 우선순위 체인을 사용하여 리뷰 규칙을 결정합니다. 각 단계는 '선착순 일치(first-match-wins)' 방식을 사용합니다: 파일 경로가 패턴과 일치하면 해당 규칙을 사용하며, 그렇지 않으면 다음 단계로 넘어갑니다.

우선순위	출처	경로	설명
1 (가장 높음)	--rule 플래그	사용자가 지정한 경로	CLI 명시적 오버라이드 (explicit override)
2	프로젝트 설정 (Project config)	<repoDir>/.opencodereview/rule.json	프로젝트별 규칙, git에 커밋 가능
3	글로벌 설정 (Global config)	~/.opencodereview/rule.json	사용자 전역 개인 설정
4 (가장 낮음)	시스템 기본값 (System default)	내장된 system_rules.json	일반적인 언어 및 파일 형식을 다루는 내장 규칙

레이어 1~3은 동일한 JSON 형식을 공유합니다:

{
"rules": [
{
...

path는 재귀적 매칭 (recursive matching) 및 {java,kt} 중괄호 확장 (brace expansion)을 지원합니다.

• 각 레이어 내에서 규칙은 선언된 순서대로 평가됩니다 — 첫 번째 일치 항목이 승리합니다 (first-match-wins).
• 규칙 파일이 존재하지 않으면 조용히 건너뜁니다.

설정 파일: ~/.opencodereview/config.json

키 (Key)	타입 (Type)	예시 (Example)
llm.url	string	https://api.openai.com/v1/chat/completions
llm.auth_token	string	sk-xxxxxxx
llm.model	string	claude-opus-4-6
llm.use_anthropic	boolean	true
language	string	English
telemetry.enabled	boolean	true
telemetry.exporter	string	console
telemetry.otlp_endpoint	string	OTLP 수집기(collector) 주소
telemetry.content_logging	boolean	텔레메트리(telemetry)에 프롬프트 포함 여부

환경 변수 (Environment variables)는 설정 파일보다 우선순위가 높습니다.

변수 (Variable)	용도 (Purpose)
OCR_LLM_URL	LLM API 엔드포인트(endpoint) URL
OCR_LLM_TOKEN	API 키 / 인증 토큰 (auth token)
OCR_LLM_MODEL	모델 이름 (Model name)
OCR_USE_ANTHROPIC	true = Anthropic, false = OpenAI

관측 가능성 (observability)를 위한 OpenTelemetry 통합 (스팬(spans), 메트릭(metrics)). 기본적으로 비활성화되어 있습니다.

ocr config set telemetry.enabled true
ocr config set telemetry.exporter otlp
ocr config set telemetry.otlp_endpoint localhost:4317

내보내는 데이터에 LLM 프롬프트와 응답을 포함하려면 telemetry.content_logging을 설정하세요.

개발 환경 설정, 코딩 가이드라인 및 Pull Request (PR) 제출 방법에 대한 자세한 내용은 CONTRIBUTING.md를 참조하세요.

Apache-2.0 — Copyright 2026 Alibaba