Open Code Review가 하는 일: 바뀐 코드에 줄 단위 리뷰 달기

코드리뷰를 AI에게 맡겨 본 사람이라면 한 번쯤 겪는 일이 있습니다. 바뀐 파일이 스무 개쯤 되면 에이전트가 앞쪽 몇 개만 꼼꼼히 보고 나머지는 대충 넘기거나, 지적한 줄 번호가 실제 코드와 몇 줄씩 어긋나는 일입니다. 같은 요청을 다시 넣어도 결과가 매번 다르게 나오기도 합니다.

Open Code Review(줄여서 OCR)는 이 문제를 겨냥해 알리바바가 공개한 코드리뷰 명령줄 도구입니다. README에 따르면 알리바바 그룹 안에서 2년 동안 공식 AI 코드리뷰 도우미로 쓰였고, 수만 명의 개발자가 쓰면서 수백만 건의 코드 결함을 찾아냈다고 합니다. 그걸 오픈소스로 꺼낸 것이 지금 저장소이고, 라이선스는 Apache-2.0이라 회사 프로젝트에도 무료로 쓸 수 있습니다.

동작은 단순합니다. 깃(Git)에서 바뀐 부분을 읽고, 바뀐 파일을 설정한 언어 모델에 보내서, 몇 번째 줄에 어떤 문제가 있는지 구조화된 코멘트로 돌려줍니다. 모델은 바뀐 줄만 보는 게 아니라 파일 전체를 읽고 저장소 안을 검색하며 다른 변경 파일도 맥락으로 봅니다. 변경분이 없는 낯선 코드는 ocr scan으로 파일 전체를 훑을 수도 있습니다.

이 도구가 다른 점은 어디까지를 모델에게 맡기지 않느냐입니다. 어떤 파일을 리뷰할지, 어떤 파일끼리 묶어서 볼지, 파일마다 어떤 규칙을 적용할지는 모델이 아니라 프로그램 코드가 정합니다. 모델은 그렇게 정해진 범위 안에서 판단만 합니다. 앞에서 말한 대충 넘기기와 줄 번호 어긋남을 구조로 막겠다는 설계입니다.

근거 [1]

Open Code Review 설치 방법: npm 한 줄, Git 2.41 이상

설치는 npm 한 줄입니다. 설치하면 ocr 명령이 생깁니다. 미리 필요한 건 Git 2.41 이상 하나인데, 바뀐 부분을 뽑고 코드를 검색하는 일을 전부 깃에 기대기 때문입니다. 우분투 24.04 기본 깃은 2.43이라 따로 올릴 필요가 없었습니다.

우분투 24.04에서 빈 폴더에 설치해 보니 패키지 두 개가 12초 만에 들어왔습니다. npm 패키지 안에는 운영체제별 실행 파일이 따로 나뉘어 있어서 리눅스, 맥, 윈도우의 인텔과 ARM 버전 가운데 내 환경에 맞는 하나만 받습니다. ocr --version을 치면 open-code-review v1.13.12 linux/amd64가 나옵니다. 1.13.12는 한국 시간 11월 18일 낮에 올라온 버전입니다.

클로드 코드를 쓴다면 플러그인으로 넣는 길도 있습니다. 클로드 코드 안에서 마켓플레이스를 추가하고 플러그인을 설치하면 /open-code-review:review와 /open-code-review:delegate-review 두 명령이 생깁니다. 다른 에이전트는 npx skills add로 스킬을 받아 쓰는 방식이 공식 안내입니다.

bash · 플러그인을 넣으면 일반 리뷰와 위임 리뷰 명령 두 개가 생긴다.
# 1. 설치 (Git 2.41 이상 필요)
npm install -g @alibaba-group/open-code-review
ocr --version

# 2. 클로드 코드 플러그인으로 넣을 때 (클로드 코드 안에서 입력)
/plugin marketplace add alibaba/open-code-review
/plugin install open-code-review@open-code-review

# 3. 다른 코딩 에이전트에 스킬로 넣을 때
npx skills add alibaba/open-code-review

근거 [1] [4]

API 키 없이 쓰는 위임 모드: 리뷰할 파일 목록 뽑기

OCR에는 리뷰 방식이 두 가지 있습니다. 일반 모드는 OCR이 직접 모델을 불러 리뷰까지 끝내는 방식이고, 위임 모드는 OCR이 파일 선택과 규칙 정리만 하고 실제 리뷰는 지금 쓰는 코딩 에이전트가 하는 방식입니다. 위임 모드에서는 OCR이 모델을 부르지 않기 때문에 OCR 쪽에 API 키나 모델 설정을 넣지 않아도 됩니다.

공식 문서는 위임 모드를 구독형 코딩 에이전트를 쓰는 사람을 위한 길로 소개합니다. 클로드 코드나 코덱스, 커서를 월 구독으로 쓰고 있다면 그 사용량을 그대로 코드리뷰에 쓰는 셈입니다. 다만 키가 필요 없다는 건 OCR 쪽 이야기일 뿐이고, 에이전트 쪽 로그인과 사용 한도, 요금은 그대로 들어갑니다.

직접 해 보려고 작은 예제 저장소를 만들었습니다. main 브랜치에 익스프레스 서버 파일 하나를 두고, feature 브랜치에서 사용자 이름을 받아 DB를 조회하는 경로를 추가했습니다. 일부러 이름을 문자열로 이어 붙여 SQL 문을 만들고, 결과를 HTML에 그대로 넣고, DB 비밀번호를 코드에 적었습니다. 영어 번역 파일 하나와 package-lock.json도 같이 바꿨습니다.

여기서 ocr delegate preview --from main을 치면 아래처럼 나옵니다. 바뀐 파일 네 개 가운데 세 개만 리뷰 대상이고, package-lock.json은 기본 제외 경로라 줄이 그어진 채 빠졌습니다. 잠금 파일처럼 사람이 보지 않아도 되는 파일을 모델이 읽느라 사용량을 쓰지 않게 걸러 주는 단계입니다.

터미널에서 ocr delegate preview --from main을 실행한 결과. Files 3 reviewable / 4 total, mode range, from main, to HEAD, total_insertions 11, total_deletions 1, locales/en.json modified, package-lock.json added excluded default_path, src/db.js added, src/server.js modified
바뀐 파일 4개 중 package-lock.json은 기본 제외로 빠지고 3개만 리뷰 대상에 남는다.BlueBWorks · 원문

근거 [2] [1]

파일마다 붙는 리뷰 규칙: ocr delegate rule 결과

다음 단계는 ocr delegate rule입니다. 미리 보기에서 나온 파일 경로를 넘기면 파일마다 적용할 리뷰 규칙을 돌려주는데, 같은 규칙을 쓰는 파일끼리 묶어서 보여 줍니다. 예제에서는 자바스크립트 파일 두 개가 첫 번째 묶음, 번역 JSON 파일이 두 번째 묶음으로 나뉘었습니다.

자바스크립트 묶음에는 오타, 죽은 코드, 코드 품질, 리액트 사용법, 비동기 처리, 보안 항목이 들어 있습니다. 보안 항목에는 사용자 입력을 제대로 이스케이프했는지 보는 XSS 방지, innerHTML에 사용자 입력을 바로 넣지 말라는 규칙, API 키나 민감한 값이 코드에 드러났는지 보라는 규칙이 적혀 있습니다. 예제에 일부러 넣은 HTML 직접 출력과 하드코딩한 비밀번호가 바로 이 항목에 걸리는 종류입니다.

JSON 묶음 규칙은 한 줄뿐입니다. 키 이름의 오타만 보고 값 내용은 무시하라는 것입니다. 번역 파일의 문장까지 모델이 붙잡고 지적하지 않게 하려는 규칙이라, 여러 언어 파일을 다루는 팀이라면 반가운 부분입니다. 이 규칙들은 리뷰 규칙 문서대로 경로별로 바꾸거나 더할 수 있습니다.

위임 모드에서는 이 규칙 묶음이 에이전트의 체크리스트가 됩니다. 공식 문서의 순서는 미리 보기, 규칙 가져오기, 깃으로 파일별 변경분 가져오기, 파일별 리뷰, 심각도별 보고입니다. 보고서에는 전체 파일 수, 리뷰한 파일 수, 건너뛴 파일 수와 비율을 넣으라고 되어 있어서, 에이전트가 몇 개를 건너뛰었는지 숨길 수 없게 만들어 둔 셈입니다.

터미널에서 ocr delegate rule 결과를 grep으로 줄인 화면. Rule Group 1은 ts, js 계열 파일 규칙으로 src/server.js와 src/db.js에 적용되고 Code Security Checks 아래 XSS Protection, innerHTML Safety, Sensitive Information 항목이 있다. Rule Group 2는 json 파일 규칙으로 locales/en.json에 적용되고 키 이름 오타만 보라는 문장이 있다
자바스크립트 파일 두 개와 JSON 파일 하나가 서로 다른 규칙 묶음으로 나뉜다.BlueBWorks · 원문

근거 [2]

ocr review가 바로 안 될 때: 모델 주소와 키 설정

설치하자마자 ocr review --from main을 치면 리뷰 대신 오류가 나옵니다. 쓸 수 있는 모델 주소가 설정되지 않았다는 내용이고, OCR_LLM_URL, OCR_LLM_TOKEN, OCR_LLM_MODEL 환경변수나 설정 파일, 또는 ANTHROPIC_BASE_URL 계열 환경변수 중 하나를 넣으라고 알려 줍니다. 일반 모드는 모델이 있어야만 돌아가니 당연한 결과입니다.

가장 쉬운 길은 ocr config provider로 메뉴를 띄워 고르는 것입니다. 문서에 실린 내장 공급자는 Anthropic, OpenAI, OpenRouter, Gemini, DeepSeek, Kimi, xAI와 중국 클라우드 여러 곳까지 스무 곳이 넘고, 대부분은 각 회사 API 키가 필요합니다. 메뉴를 쓸 수 없는 CI 환경에서는 ocr config set으로 같은 값을 넣습니다.

챗GPT 요금제가 있다면 미리보기로 열린 ChatGPT 로그인 방식도 있습니다. ocr auth login으로 로그인하면 키 없이 챗GPT 요금제 사용량으로 리뷰를 돌립니다. OCR이 따로 돈을 받지는 않지만, 어떤 계정과 지역, 모델을 쓸 수 있는지는 OpenAI가 정한다고 문서에 적혀 있습니다. 미리보기 기능이라 계정에 따라 안 될 수 있다는 뜻입니다.

이 글에서는 모델 키를 넣지 않았기 때문에 일반 모드의 실제 리뷰 결과는 싣지 않았습니다. 키가 없는 상태라면 위임 모드부터 써 보는 게 공식 안내와도 맞습니다.

터미널에서 ocr --version은 open-code-review v1.13.12 linux/amd64를 보여 주고, 이어서 ocr review --from main을 실행하자 no valid LLM endpoint configured 오류와 OCR_LLM_URL, OCR_LLM_TOKEN, OCR_LLM_MODEL, ~/.opencodereview/config.json, ANTHROPIC_BASE_URL 계열 환경변수 중 하나를 설정하라는 문장이 빨간 글씨로 나온다
모델을 설정하기 전에는 ocr review가 오류로 멈추고 필요한 환경변수 이름을 알려 준다.BlueBWorks · 원문
bash · 설정은 ~/.opencodereview/config.json에 저장된다. 키는 환경변수에서 읽게 두는 편이 안전하다.
# 메뉴로 고르기
ocr config provider
ocr config model

# CI처럼 메뉴가 없는 곳 (리눅스, 맥)
ocr config set provider anthropic
ocr config set providers.anthropic.api_key "$ANTHROPIC_API_KEY"

# 윈도우 PowerShell이라면 키 부분만
ocr config set providers.anthropic.api_key "$env:ANTHROPIC_API_KEY"

# 챗GPT 요금제 로그인 (미리보기)
ocr auth login --provider chatgpt
ocr config set provider chatgpt

# 리뷰 실행
ocr review --from main

근거 [3] [5]

클로드 코드 코드리뷰와 차이: 덜 찾는 대신 덜 틀린다

README에는 같은 모델을 쓴 클로드 코드와 비교한 수치가 있습니다. 인기 오픈소스 저장소 50곳의 실제 풀 리퀘스트 200개, 10개 언어로 만든 평가 세트에서, OCR은 지적한 것 중 진짜 결함 비율(정밀도)과 종합 점수가 더 높고 토큰은 9분의 1 정도만 썼다고 합니다. 대신 실제 결함 중 찾아낸 비율은 클로드 코드보다 낮다고 README가 직접 밝힙니다.

이 숫자는 알리바바가 만든 평가 세트로 알리바바가 잰 결과입니다. 평가 세트 자체는 허깅페이스에 공개돼 있지만, 내 프로젝트에서도 같은 차이가 날지는 직접 돌려 봐야 압니다. 다만 방향은 분명합니다. 오탐을 줄여서 리뷰 코멘트를 읽는 사람의 피로를 덜자는 쪽입니다. 보안 점검처럼 하나도 놓치면 안 되는 일이라면 이 도구 하나에만 기대지 않는 편이 낫습니다.

쓰는 감각도 다릅니다. 클로드 코드에 리뷰를 시키는 건 말로 부탁하는 방식이라 프롬프트를 조금만 바꿔도 결과가 흔들립니다. OCR은 파일 선택과 규칙이 코드로 고정돼 있어서 같은 변경에 같은 규칙이 붙습니다. 위임 모드로 클로드 코드와 같이 쓰면 판단은 클로드 코드가 하되 범위는 OCR이 정하는 구조가 됩니다.

근거 [1] [6]

회사 코드에 쓰기 전에 볼 것: 코드가 어디로 가나

일반 모드에서는 바뀐 파일과 필요하면 파일 전체가 설정한 모델 회사로 전송됩니다. 회사 코드라면 어떤 공급자를 고를지가 곧 코드를 어디로 보낼지를 정하는 일입니다. 사내 게이트웨이가 있다면 custom_providers로 사내 주소를 붙이는 방법이 설정 문서에 있습니다.

사용 기록을 밖으로 보내는 텔레메트리는 기본으로 꺼져 있습니다. 켜면 리뷰 시간, 토큰 수, 도구 호출 같은 지표를 내가 정한 수집 서버로 보내는 방식이라, 켜지 않으면 신경 쓸 일이 없습니다. 위임 모드는 OCR이 모델을 부르지 않으니 코드가 어디로 가는지는 쓰는 코딩 에이전트의 정책을 따릅니다.

CI에 붙이는 길도 열려 있습니다. GitHub Actions, GitLab CI, Gerrit 연동 문서가 있고, 결과를 JSON 파일로 저장하는 옵션도 있어 다른 도구와 엮기 쉽습니다. 처음이라면 내 컴퓨터에서 위임 모드로 미리 보기와 규칙을 한 번 뽑아 보고, 걸러지는 파일과 규칙이 우리 팀 코드에 맞는지부터 보는 순서를 권합니다.

근거 [3] [7] [1]