OpenCodeReview를 Ollama Cloud와 같이 쓰기

AI 코드 리뷰 도구는 이제 너무 많다. Claude Code에게 “현재 변경사항 리뷰해줘”라고 말할 수도 있고, Codex나 Cursor에서도 비슷한 일을 시킬 수 있다. 문제는 그 다음이다. 리뷰라는 작업은 생각보다 귀찮게 정확해야 한다. 어떤 파일을 봐야 하는지, 어느 라인에 코멘트를 달아야 하는지, 큰 변경에서 일부 파일만 보고 넘어가지는 않았는지, 오탐이 너무 많아서 사람이 결국 무시하게 되지는 않는지 같은 문제가 계속 따라온다.

OpenCodeReview는 이 지점을 꽤 노골적으로 겨냥한 도구다. Alibaba 내부에서 쓰던 AI 코드 리뷰 CLI를 오픈소스로 공개한 프로젝트이고, README에 따르면 지난 2년 동안 수만 명의 개발자가 사용했고 수백만 건의 코드 결함을 찾아냈다고 한다. 이런 숫자는 당연히 마케팅 문장처럼 읽힐 수 있다. 하지만 내가 흥미로웠던 부분은 숫자보다 구조 쪽이었다.

OpenCodeReview는 단순히 “LLM에게 diff를 던지고 리뷰해달라고 하는 도구”가 아니라, 코드 리뷰라는 작업을 조금 더 단단한 파이프라인으로 나눈다. 리뷰 대상 파일을 고르고, 관련 파일을 묶고, 파일 특성에 맞는 규칙을 적용하고, 위치가 어긋난 코멘트를 줄이는 부분은 결정적인 로직으로 처리한다. 반대로 맥락을 읽고 판단하는 부분은 에이전트와 LLM에게 맡긴다.

이 조합이 마음에 들었다. 요즘 에이전트 도구를 쓰다 보면 모든 것을 자연어 프롬프트로 해결하려는 유혹이 생기는데, 코드 리뷰처럼 반복적이고 결과 위치가 중요한 작업은 오히려 강한 제약이 있는 편이 낫다. 자유로운 에이전트가 아니라, 제한된 레일 위에서 필요한 만큼만 움직이는 에이전트에 가깝다.

OpenCodeReview가 하려는 일

OpenCodeReview의 기본 작업 단위는 Git diff다. ocr review를 실행하면 현재 작업 공간의 staged, unstaged, untracked 변경을 읽고 리뷰한다. 특정 브랜치 범위를 비교할 수도 있고, 단일 커밋만 리뷰할 수도 있다.

# 현재 작업 공간의 변경 리뷰
ocr review

# main과 feature-branch 비교
ocr review --from main --to feature-branch

# 특정 커밋 리뷰
ocr review --commit abc123

diff가 없거나, 익숙하지 않은 코드베이스를 통째로 훑고 싶을 때는 ocr scan을 쓴다. 이 명령은 Git 변경사항이 아니라 파일 자체를 대상으로 리뷰한다.

# 저장소 전체 스캔
ocr scan

# 특정 디렉터리만 스캔
ocr scan --path internal/agent

# 먼저 어떤 파일을 볼지 확인
ocr scan --preview

여기까지만 보면 그냥 코드 리뷰 CLI다. 하지만 README에서 강조하는 차이는 범용 에이전트와의 비교에 있다. 범용 에이전트는 큰 변경에서 파일을 놓치거나, 라인 번호가 어긋나거나, 프롬프트가 조금만 바뀌어도 리뷰 품질이 흔들릴 수 있다. OpenCodeReview는 이런 부분을 “언어 모델이 잘 알아서 하겠지”에 맡기지 않고, 리뷰 프로세스 바깥에 결정적인 구조를 둔다.

README에 나온 벤치마크도 이 방향을 보여준다. 50개 인기 오픈소스 저장소, 200개 실제 Pull Request, 10개 언어, 80명 이상의 시니어 엔지니어 검증, 1,505개 어노테이션된 결함을 기준으로 비교했다고 한다. 결론은 범용 에이전트보다 정밀도와 F1이 높고, 토큰은 약 1/9 수준으로 쓴다는 것이다. 대신 재현율은 낮다.

나는 이 트레이드오프가 꽤 현실적이라고 본다. 코드 리뷰에서 모든 결함을 다 잡는 것은 이상적인 목표지만, 실제 팀에서는 오탐이 너무 많으면 리뷰 도구 자체를 안 보게 된다. “가끔 놓치더라도, 말한 것은 꽤 믿을 만하다”는 성질이 자동 리뷰에서는 생각보다 중요하다.

설치하기

OpenCodeReview는 ocr이라는 CLI로 설치된다. 사전 요구사항은 Git 2.41 이상이다. diff 생성, 코드 검색, 저장소 작업에 Git을 사용하기 때문이다.

가장 간단한 설치 방법은 npm이다.

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

설치가 끝나면 ocr version으로 확인한다.

ocr version

내가 확인한 시점의 npm 최신 버전은 1.7.2였고, 리눅스 환경에서 다음처럼 출력됐다.

TXT

open-code-review v1.7.2 (39eb0f3) linux/arm64
built at: 2026-07-06T12:46:45Z
https://github.com/alibaba/open-code-review

macOS나 Linux에서는 GitHub Release 설치 스크립트도 사용할 수 있다.

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

이 스크립트는 OS와 아키텍처에 맞는 바이너리를 선택하고 SHA-256 체크섬을 검증한 뒤 /usr/local/bin/ocr에 설치한다. 전역 디렉터리에 쓰기 권한이 애매하거나, 특정 버전을 고정하고 싶다면 설치 위치와 버전을 지정할 수 있다.

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)"

개인적으로는 Node 프로젝트를 많이 다루는 환경이면 npm 설치가 제일 단순하고, 서버나 CI 이미지처럼 Node 전역 패키지를 늘리고 싶지 않은 환경이면 릴리스 바이너리 설치가 더 깔끔할 것 같다.

LLM provider 설정하기

OpenCodeReview는 설치만으로는 동작하지 않는다. 리뷰를 실행하기 전에 LLM provider를 설정해야 한다. 설정 파일은 기본적으로 다음 위치에 저장된다.

TXT

~/.opencodereview/config.json

대화형으로 설정하려면 아래 명령을 쓰면 된다.

ocr config provider
ocr config model
ocr llm test

ocr config provider는 내장 provider를 고르거나 커스텀 provider를 추가하는 흐름을 제공한다. 내장 provider 목록은 ocr llm providers로 볼 수 있다. 내가 확인한 버전에서는 anthropic, openai, dashscope, deepseek, z-ai, kimi, minimax 같은 provider가 포함되어 있었다.

하지만 자동화 환경이나, 특정 OpenAI 호환 엔드포인트를 쓰려면 ocr config set으로 직접 설정하는 편이 낫다.

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

여기서 중요한 것은 custom_providers.<name>.url과 custom_providers.<name>.protocol이다. 프로토콜은 openai 또는 anthropic을 쓴다. OpenAI 호환 API라면 대개 openai로 두면 된다.

Ollama Cloud로 설정하기

Ollama Cloud도 OpenAI 호환 엔드포인트를 제공하므로 커스텀 provider로 붙일 수 있다. 예를 들어 glm-5.2:cloud 모델을 쓴다면 다음처럼 설정한다.

export OLLAMA_API_KEY="YOUR_API_KEY"

ocr config set provider ollama-cloud
ocr config set custom_providers.ollama-cloud.url https://ollama.com/v1
ocr config set custom_providers.ollama-cloud.protocol openai
ocr config set custom_providers.ollama-cloud.api_key "$OLLAMA_API_KEY"
ocr config set custom_providers.ollama-cloud.model "glm-5.2:cloud"

이 명령들을 실행하면 ~/.opencodereview/config.json에 대략 다음 구조가 생긴다. 실제 API key는 파일에 저장되므로 블로그나 로그에 그대로 출력하면 안 된다.

JSON

{
  "provider": "ollama-cloud",
  "custom_providers": {
    "ollama-cloud": {
      "url": "https://ollama.com/v1",
      "protocol": "openai",
      "api_key": "...",
      "model": "glm-5.2:cloud"
    }
  }
}

한 가지 사소하지만 자주 걸리는 점이 있다. OLLAMA_API_KEY를 같은 줄의 임시 환경 변수처럼 넘기면서 "$OLLAMA_API_KEY"를 쓰면, 셸 확장 순서 때문에 빈 값이 들어갈 수 있다. 안전하게 하려면 먼저 export한 다음 별도 명령으로 ocr config set ... "$OLLAMA_API_KEY"를 실행하는 편이 낫다.

설정이 끝나면 연결을 테스트한다.

ocr llm test

그리고 실제 리뷰 전에 --preview로 대상 파일을 먼저 확인한다.

ocr review --preview

나는 이런 류의 도구에서 --preview를 꽤 중요하게 본다. AI 리뷰 비용은 모델 호출 비용만이 아니라, 잘못된 파일을 리뷰하고 나온 결과를 사람이 다시 읽는 비용까지 포함한다. 먼저 파일 목록을 확인하고, 필요하면 --exclude나 rule을 조정한 뒤 실행하는 편이 좋다.

기본 사용 패턴

가장 자주 쓸 흐름은 세 가지 정도다. 그냥 ocr review 한 번으로 끝낼 수도 있지만, 실제로는 “언제 실행하느냐”에 따라 명령 조합이 조금 달라진다. 나는 로컬 작업 공간 리뷰, PR 전 브랜치 리뷰, 코드베이스 스캔을 서로 다른 용도로 보는 편이 낫다고 생각한다.

1. 로컬 작업 공간 리뷰

첫 번째는 커밋하기 전에 현재 작업 공간을 훑는 흐름이다. staged, unstaged, untracked 변경을 모두 보고, 지금 손에 들고 있는 변경이 너무 이상한 방향으로 가지 않았는지 확인하는 용도에 가깝다.

ocr review --preview
ocr review

여기서 --preview를 먼저 붙이는 습관이 좋다. 리뷰 대상 파일을 확인한 뒤 실제 LLM 호출을 하는 흐름이다. 생성 파일, lockfile, 빌드 산출물처럼 리뷰할 가치가 낮은 파일이 섞여 있다면 제외 패턴을 붙인다.

ocr review --exclude '**/generated/**,**/*.lock,dist/**'

작업의 의도가 코드만 보고는 잘 드러나지 않는다면 --background를 같이 주는 편이 낫다. 예를 들어 로그인 API에 rate limiting을 추가했다면, 모델에게 그 맥락을 알려주는 것이다.

ocr review --background "로그인 API에 rate limiting을 추가했다. 우회 가능성과 기존 로그인 실패 처리와의 충돌을 중점적으로 봐줘."

이 흐름은 “내가 놓친 실수 찾기”에 가깝다. 그래서 결과를 너무 거창하게 받아들이기보다, 커밋 전 마지막 자기 검열 장치로 두는 것이 좋다.

2. PR 전 브랜치 리뷰

두 번째는 PR을 만들기 전에 기준 브랜치와 현재 브랜치의 차이를 보는 흐름이다. 로컬 작업 공간 리뷰가 지금 손에 든 변경을 보는 것이라면, 브랜치 리뷰는 “PR에 실제로 올라갈 변경 전체”를 보는 쪽에 가깝다.

ocr review --from main --to HEAD --preview
ocr review --from main --to HEAD

팀에서 develop, dev, master 같은 기준 브랜치를 쓴다면 그 이름에 맞추면 된다. 원격 기준으로 더 명확히 보고 싶다면 origin/main을 쓴다.

ocr review --from origin/main --to HEAD

PR 코멘트 자동화나 다른 도구 연동을 생각한다면 JSON 출력이 편하다.

ocr review --from origin/main --to HEAD --format json --audience agent

--audience agent는 사람이 읽는 진행 로그보다 에이전트나 스크립트가 읽기 좋은 요약에 가깝게 출력한다. Codex나 Claude Code 같은 코딩 에이전트에게 결과를 넘겨서 “high-confidence 이슈만 고쳐라” 같은 후속 작업을 시킬 때도 이쪽이 낫다.

나는 이 흐름을 CI 바로 전 단계로 두는 것이 좋아 보인다. 로컬에서는 빠르게 실수를 줄이고, CI에서는 같은 기준을 더 자동화된 방식으로 반복한다.

3. 코드베이스 스캔

세 번째는 ocr scan을 쓰는 흐름이다. 이건 일반적인 PR 리뷰와 성격이 다르다. diff를 보는 것이 아니라 파일 전체를 보므로, 새로 맡은 코드베이스를 읽거나 레거시 디렉터리를 점검하거나 마이그레이션 전에 위험한 부분을 찾는 데 더 잘 맞는다.

ocr scan --path src/legacy --preview
ocr scan --path src/legacy --max-tokens-budget 500000

ocr scan은 비용이 커지기 쉽다. 그래서 먼저 --preview로 파일 목록을 보고, 그 다음 --max-tokens-budget으로 상한을 두는 편이 안전하다. 특정 파일이나 디렉터리만 보고 싶으면 --path를 좁히고, 테스트 fixture나 생성 파일은 제외한다.

ocr scan \
  --path src/legacy,src/shared \
  --exclude '**/*.test.ts,**/fixtures/**,**/generated/**' \
  --max-tokens-budget 500000

속도를 우선해야 하는 상황이라면 일부 후처리를 끌 수도 있다.

ocr scan --path src/legacy --no-plan --no-dedup --no-summary

다만 이 옵션들은 결과 품질이나 읽기 편의성을 줄일 수 있다. 처음 보는 코드라면 기본값으로 한 번 돌리고, 너무 무겁다고 느낄 때만 줄이는 쪽이 낫다. README 기준으로 ocr scan은 --batch none, --batch by-language, --batch by-directory 같은 배치 전략도 지원한다. 큰 저장소에서는 언어별 또는 디렉터리별로 묶는 것이 결과를 읽기에도 편하다.

리뷰 규칙을 프로젝트에 넣기

OpenCodeReview에서 rule은 “이 파일을 리뷰할 때 무엇을 특히 봐야 하는가”를 적어두는 지시문이다. 조금 더 거칠게 말하면, 모델에게 매번 반복해서 설명하기 귀찮은 팀의 리뷰 기준을 파일 경로와 연결해두는 장치다.

예를 들어 모든 파일에 똑같은 기준을 적용하는 것은 별로 좋은 리뷰가 아니다. React 컴포넌트에서는 접근성, 상태 위치, 서버/클라이언트 경계가 중요할 수 있고, API 라우트에서는 인증, 에러 처리, 입력 검증이 더 중요할 수 있다. SQL mapper 파일에서는 SQL injection이나 파라미터 누락을 봐야 하고, 다국어 메시지 파일에서는 key 누락이나 번역 불일치를 봐야 한다. 이런 차이를 매번 자연어로 설명하지 않고 rule.json에 박아두는 것이다.

rule의 우선순위

OpenCodeReview는 리뷰 규칙을 네 계층으로 읽는다. 우선순위는 위에서 아래로 내려간다.

--rule 플래그로 넘긴 파일
프로젝트의 <repo>/.opencodereview/rule.json
전역 ~/.opencodereview/rule.json
내장 시스템 규칙

이 구조 때문에 개인 취향과 팀 규칙을 분리할 수 있다. 내가 모든 프로젝트에서 공통으로 보고 싶은 기준은 전역 rule에 둘 수 있고, 특정 프로젝트에서 팀 전체가 공유해야 하는 기준은 .opencodereview/rule.json에 넣어 저장소에 커밋하면 된다. 특정 실험이나 임시 리뷰에서는 --rule custom.json처럼 명령어에서 바로 덮어쓸 수도 있다.

rule 파일의 기본 구조

rule 파일의 기본 형태는 단순하다.

JSON

{
  "rules": [
    {
      "path": "**/*mapper*.xml",
      "rule": "Check SQL for injection risks, parameter errors, and missing closing tags"
    },
    {
      "path": "**/*.go",
      "rule": "shared/go-concurrency.md"
    }
  ]
}

각 항목에서 path는 어떤 파일에 이 규칙을 적용할지 정하는 패턴이다. ** 재귀 매칭과 {java,kt} 같은 brace expansion을 지원한다. rule은 실제 리뷰 지시문이다. 짧은 규칙이면 문자열로 바로 적고, 길거나 팀 문서처럼 관리하고 싶으면 .md, .txt, .markdown 파일 경로를 넣을 수 있다. 상대 경로는 프로젝트 루트 기준으로 해석된다.

프론트엔드 프로젝트의 rule 예시

조금 더 프론트엔드 프로젝트답게 쓰면 이런 식이 될 수 있다.

JSON

{
  "rules": [
    {
      "path": "app/**/*.{ts,tsx}",
      "rule": "Check Next.js App Router boundaries. Pay attention to server/client component separation, accidental client bundle growth, and data fetching location."
    },
    {
      "path": "components/**/*.{ts,tsx}",
      "rule": "Check component API readability, accessibility, unnecessary state, and whether the component is reusable without hiding domain logic."
    },
    {
      "path": "**/*.test.{ts,tsx}",
      "rule": "Check whether tests cover observable behavior instead of implementation details. Avoid brittle snapshots unless they add real value."
    }
  ]
}

이 예시는 완성된 정답이라기보다 출발점에 가깝다. 중요한 것은 “프론트엔드 코드를 잘 봐줘”처럼 넓게 말하지 않는 것이다. 모델은 넓은 지시를 받으면 넓게 말한다. 반대로 “서버/클라이언트 경계”, “불필요한 상태”, “접근성”, “구현 세부사항에 묶인 테스트”처럼 팀이 실제로 신경 쓰는 축을 좁혀주면 코멘트도 그쪽으로 모인다.

긴 규칙은 Markdown 파일로 빼기

규칙이 길어지면 별도 Markdown 파일로 빼는 편이 낫다.

JSON

{
  "rules": [
    {
      "path": "app/**/*.{ts,tsx}",
      "rule": "docs/review-rules/nextjs-app-router.md"
    },
    {
      "path": "packages/ui/**/*.{ts,tsx}",
      "rule": "docs/review-rules/design-system.md"
    }
  ]
}

이렇게 하면 리뷰 규칙도 코드처럼 리뷰할 수 있다. PR에서 “이번에 디자인 시스템 컴포넌트 규칙을 강화했다”라고 말할 수 있고, 팀원이 규칙 자체에 의견을 달 수 있다. AI 리뷰 도구를 팀에 넣을 때 은근히 중요한 부분이다. 모델의 출력만 리뷰하는 것이 아니라, 모델에게 주는 기준도 리뷰해야 한다.

rule 매칭 확인하기

규칙을 적용하기 전에 어떤 파일에 어떤 rule이 걸리는지 확인할 수 있다.

ocr rules check src/main/resources/mapper/UserMapper.xml
ocr rules check --rule custom.json src/main/java/com/example/Foo.java

이 명령은 실제 LLM 리뷰를 돌리기 전에 rule 매칭을 디버깅하는 용도다. rule이 예상과 다르게 걸리면 리뷰 결과도 엉뚱해진다. 특히 **/*.ts와 components/**/*.{ts,tsx}처럼 겹치는 패턴이 많아질수록 먼저 확인하는 편이 안전하다.

구체적인 규칙을 앞에 두기

OpenCodeReview의 rule은 같은 계층 안에서 선언 순서대로 평가되고, 먼저 매칭된 rule이 선택된다. README 표현으로는 first-match-wins 방식이다. 따라서 더 구체적인 규칙을 앞에 두고, 넓은 규칙을 뒤에 두는 편이 낫다.

JSON

{
  "rules": [
    {
      "path": "components/forms/**/*.{ts,tsx}",
      "rule": "Check form validation, error messages, accessibility labels, and controlled/uncontrolled input mistakes."
    },
    {
      "path": "components/**/*.{ts,tsx}",
      "rule": "Check component API readability, accessibility, and unnecessary state."
    }
  ]
}

위 예시에서 components/forms/LoginForm.tsx는 첫 번째 규칙에 먼저 걸린다. 만약 넓은 components/**/* 규칙을 앞에 두면 form 전용 규칙까지 도달하지 못할 수 있다. 이런 작은 순서 문제가 리뷰 품질을 꽤 바꾼다.

내장 규칙과 합치기

내장 시스템 규칙과 사용자 규칙을 함께 쓰고 싶을 때는 merge_system_rule을 사용할 수 있다.

JSON

{
  "rules": [
    {
      "path": "**/*.ts",
      "rule": "In addition to the default TypeScript checks, pay extra attention to unsafe type assertions and hidden any usage.",
      "merge_system_rule": true
    }
  ]
}

merge_system_rule이 true이면 해당 파일 타입에 대한 내장 규칙과 내가 적은 규칙을 합쳐서 본다. 팀 규칙이 내장 규칙을 완전히 대체하기보다 보강하는 성격이라면 이쪽이 더 자연스럽다.

처음에는 작게 시작하기

rule을 너무 많이 넣는 것은 또 다른 문제다. 규칙이 길고 많아지면 모델은 결국 무엇을 가장 중요하게 봐야 하는지 잃어버린다. 처음에는 정말 반복해서 놓치는 것만 넣는 편이 좋다.

내가 팀 프로젝트에 넣는다면 대략 이런 순서로 시작할 것 같다.

생성 파일, 빌드 산출물, 의미 없는 파일을 먼저 제외한다.
파일 종류별로 꼭 봐야 하는 기준을 3~5개만 적는다.
ocr rules check로 매칭을 확인한다.
ocr review --preview로 리뷰 대상 파일을 확인한다.
실제 리뷰 결과에서 쓸모없는 코멘트가 반복되면 rule을 줄이고, 중요한 누락이 반복되면 rule을 추가한다.

이 부분은 팀 도입에서 꽤 중요해 보인다. AI 코드 리뷰를 그냥 켜면 “우리 팀이 중요하게 보는 것”과 “모델이 중요하다고 생각하는 것”이 어긋난다. 예를 들어 프론트엔드 팀이라면 접근성, 번들 크기, 서버 컴포넌트 경계, 상태 관리 위치 같은 기준이 있을 수 있고, 백엔드 팀이라면 트랜잭션, N+1, 리소스 해제, 멱등성 같은 기준이 더 중요할 수 있다. 이런 기준을 rule로 명시하면 모델의 자유도를 줄일 수 있다.

자유도를 줄이는 것이 꼭 나쁜 것은 아니다. 리뷰에서는 오히려 장점일 때가 많다. 좋은 리뷰 도구는 모든 말을 하는 도구가 아니라, 지금 이 코드에서 우리가 보기로 한 것을 꾸준히 보는 도구에 가깝다.

에이전트와 같이 쓰기

OpenCodeReview는 CLI로 직접 써도 되지만, README에서는 Claude Code, Codex, Cursor 같은 코딩 에이전트와의 통합도 설명한다. 핵심은 에이전트가 직접 “리뷰”를 하는 것이 아니라, 로컬의 ocr CLI를 호출하게 만드는 것이다.

Claude Code 계열에서는 skill 또는 plugin으로 붙일 수 있다.

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

Claude Code plugin 방식은 다음과 같다.

TXT

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

Codex나 Cursor에서는 plugin을 추가한 뒤 다음처럼 호출하는 흐름이다.

TXT

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

이 통합에서 중요한 점은 OpenCodeReview의 LLM backend가 에이전트의 모델 설정을 그대로 따라가는 것이 아니라는 점이다. ocr CLI 자체가 별도로 설치되어 있고, 앞에서 설정한 provider를 사용한다. 즉 Codex에서 호출하더라도 실제 리뷰 모델은 ~/.opencodereview/config.json에 설정된 provider와 모델이다.

나는 이 분리가 마음에 든다. 코딩 에이전트는 작업 흐름의 UI가 되고, OpenCodeReview는 리뷰 파이프라인이 된다. 에이전트에게 모든 것을 맡기는 대신, “이 리뷰는 이 도구로 하고, 결과를 바탕으로 수정할지 판단해라”라고 역할을 나누는 셈이다.

OpenCode에서는 custom command로 감싸기

README에는 Claude Code, Codex, Cursor 통합이 따로 나오지만, OpenCode용 plugin은 별도로 제공하지 않는 것으로 보인다. 그렇다고 OpenCode에서 못 쓰는 것은 아니다. OpenCode는 프로젝트나 전역 설정에 custom command를 둘 수 있으므로, ocr CLI를 호출하는 명령을 직접 만들면 된다.

프로젝트에만 적용하려면 .opencode/commands/open-code-review.md를 만든다.

mkdir -p .opencode/commands

---
description: Run OpenCodeReview on current changes
agent: build
subtask: true
---

Run OpenCodeReview for the current repository changes.

First, inspect the target files:

!`ocr review --preview`

Then run the actual review in agent-friendly JSON format:

!`ocr review --format json --audience agent`

Use the OpenCodeReview result as the primary review source.
Summarize the issues by severity and confidence.
If there are high-confidence issues, propose fixes first.
Do not change files for low-confidence or stylistic comments unless I explicitly ask.

Additional context from the user:

$ARGUMENTS

이렇게 두면 OpenCode TUI에서 다음처럼 호출할 수 있다.

TXT

/open-code-review
/open-code-review 이번 변경은 로그인 API rate limiting 작업이다. 우회 가능성을 중점적으로 봐줘.

여기서 핵심은 OpenCode에게 “리뷰해줘”라고 바로 맡기는 것이 아니라, 먼저 ocr review의 결과를 읽게 하는 것이다. OpenCode는 작업 흐름을 이어가는 에이전트이고, OpenCodeReview는 리뷰 대상 선정과 rule 적용, 위치 보정이 들어간 리뷰 파이프라인이다. 둘을 섞을 때는 역할을 분리하는 편이 낫다.

브랜치 비교용 명령도 따로 만들 수 있다.

---
description: Run OpenCodeReview against origin/main
agent: build
subtask: true
---

Run OpenCodeReview against `origin/main` and review the result.

Preview target files:

!`ocr review --from origin/main --to HEAD --preview`

Review result:

!`ocr review --from origin/main --to HEAD --format json --audience agent`

Summarize high-confidence issues first.
Suggest fixes, but ask before applying broad refactors.

Additional context from the user:

$ARGUMENTS

이 파일을 .opencode/commands/ocr-pr-review.md처럼 저장하면 /ocr-pr-review로 부를 수 있다. 개인 전역 명령으로 쓰고 싶다면 ~/.config/opencode/commands/ 아래에 두면 된다. 다만 팀 프로젝트에서 같은 리뷰 흐름을 공유하려면 프로젝트의 .opencode/commands/에 두고 저장소에 커밋하는 쪽이 더 낫다.

주의할 점도 있다. $ARGUMENTS를 그대로 셸 명령 안에 넣는 식으로 만들지는 않는 편이 좋다. custom command는 편하지만, 사용자가 입력한 문자열을 셸에 직접 섞으면 의도하지 않은 명령 실행 문제가 생길 수 있다. 위 예시처럼 $ARGUMENTS는 OpenCode에게 전달할 추가 맥락으로만 쓰고, 실제 실행할 ocr review 명령은 고정해두는 쪽이 안전하다.

CI에서 쓰기

CI에서는 --from, --to, --format json 조합이 기본이 될 가능성이 높다.

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

여기서 바로 실패 조건을 걸지는 조금 조심해야 한다. 처음부터 “OCR이 하나라도 지적하면 CI 실패”로 두면 오탐이나 팀 규칙 미정 상태 때문에 금방 피곤해질 수 있다. 처음에는 JSON 결과를 아티팩트로 남기거나 PR 코멘트로 붙이고, 어느 정도 규칙이 안정된 뒤 high-confidence 이슈만 실패 조건으로 삼는 쪽이 낫다.

CI에서 특히 챙길 값은 다음 정도다.

provider API key는 CI secret으로 넣는다.
ocr llm test를 별도 단계로 두어 설정 문제와 리뷰 문제를 분리한다.
--format json으로 결과를 남긴다.
생성 파일, lockfile, 빌드 산출물은 --exclude 또는 rule로 제외한다.
큰 저장소에서는 --concurrency, --timeout, --max-tokens-budget을 보수적으로 잡는다.

자동 리뷰는 팀에 천천히 들어가는 편이 좋다. 도구가 똑똑하냐보다 중요한 것은 팀이 그 도구의 말을 어느 정도 신뢰할 수 있느냐이기 때문이다.

Viewer와 보안

OpenCodeReview에는 리뷰 세션을 확인할 수 있는 viewer도 있다.

ocr viewer
ocr viewer --addr :3000

기본적으로는 로컬에서 세션 히스토리를 확인하는 용도다. README에 따르면 viewer는 session JSONL 내용, 즉 LLM request message와 response를 HTTP로 제공한다. 여기에 코드와 프롬프트가 들어갈 수 있으므로 외부에 노출할 때는 조심해야 한다.

--addr :3000이나 0.0.0.0처럼 루프백이 아닌 주소로 열어야 한다면 OCR_VIEWER_ALLOWED_HOSTS를 설정한다.

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

개인적으로는 viewer를 공개망에 직접 열 이유는 거의 없다고 생각한다. 필요하다면 VPN이나 내부망 뒤에 두고, 세션 로그에 민감한 코드와 프롬프트가 남는다는 전제를 가지고 다뤄야 한다.

언제 쓰면 좋을까

OpenCodeReview는 “AI가 대신 리뷰해주는 마법 도구”라기보다, 반복적인 코드 리뷰 1차 필터에 가깝다. 그래서 어울리는 사용처도 비교적 분명하다.

잘 맞는 경우는 이런 쪽이다.

PR 올리기 전에 로컬에서 한 번 거르는 용도
큰 changeset에서 사람이 놓칠 수 있는 파일을 먼저 훑는 용도
레거시 디렉터리나 새로 맡은 모듈을 스캔하는 용도
팀 규칙을 .opencodereview/rule.json으로 명시하고 반복 적용하는 용도
CI에서 JSON 결과를 남겨 자동 리뷰 기록을 쌓는 용도
코딩 에이전트에게 “리뷰와 수정” 역할을 나눠 맡기는 용도

반대로, 모든 설계 판단을 맡기기에는 아직 조심스럽다. README의 벤치마크 자체도 재현율보다 정밀도를 택했다고 말한다. 이 말은 곧 놓치는 문제가 있을 수 있다는 뜻이다. OpenCodeReview가 조용하다고 해서 안전하다는 뜻은 아니다. 다만 무언가를 지적했을 때 그것이 검토할 가치가 있을 확률을 높이려는 도구에 가깝다.

내가 쓴다면 처음에는 이렇게 둘 것 같다.

# 1. 변경 대상 확인
ocr review --preview

# 2. 로컬 리뷰
ocr review --background "이번 변경의 목적과 주의할 비즈니스 맥락"

# 3. 에이전트가 읽기 좋게 JSON으로 한 번 더 실행
ocr review --format json --audience agent

그리고 팀 프로젝트라면 바로 CI 실패 조건을 걸기보다, 먼저 rule을 쌓을 것이다. 어떤 파일은 보지 않아야 하는지, 어떤 종류의 지적은 정말 중요한지, 어떤 도메인 규칙을 모델이 매번 기억해야 하는지부터 정리한다. 결국 좋은 AI 리뷰는 좋은 프롬프트 하나가 아니라, 리뷰할 범위와 규칙과 출력 형식을 꾸준히 좁혀가는 과정에 가깝다.

마무리

OpenCodeReview에서 흥미로운 점은 “에이전트를 더 자유롭게 만들자”가 아니라 “에이전트가 헤매지 않도록 리뷰 작업의 레일을 깔자”는 쪽에 있다. 파일 선택, 번들링, 규칙 매칭, 위치 보정처럼 기계적으로 잡아야 하는 부분은 기계적으로 잡고, 언어 모델은 맥락 판단에 집중하게 한다.

이 방향은 앞으로 코드 리뷰 도구가 가야 할 꽤 현실적인 형태라고 생각한다. 범용 에이전트 하나에게 모든 것을 맡기면 편하지만, 리뷰라는 작업은 편한 것보다 믿을 수 있는 것이 더 중요하다. 특히 팀에서 쓰는 도구라면 더 그렇다.

Ollama Cloud 같은 OpenAI 호환 provider를 붙일 수 있다는 점도 좋다. 특정 벤더에 완전히 묶이지 않고, custom_providers 설정으로 모델을 갈아 끼울 수 있다. 처음에는 로컬에서 ocr review --preview와 ocr review 정도로 시작하고, 어느 정도 감이 잡히면 rule과 CI, 에이전트 통합으로 넓혀가는 순서가 가장 안전해 보인다.

결국 중요한 것은 AI가 리뷰를 “해준다”는 사실이 아니다. 리뷰라는 반복 작업에서 어디까지를 도구에게 맡기고, 어디부터는 사람이 판단할지 경계를 정하는 일이다. OpenCodeReview는 그 경계를 꽤 실용적인 방식으로 그어보려는 도구다.

OpenCodeReview가 하려는 일

설치하기

LLM provider 설정하기

Ollama Cloud로 설정하기

기본 사용 패턴

1. 로컬 작업 공간 리뷰

2. PR 전 브랜치 리뷰

3. 코드베이스 스캔

리뷰 규칙을 프로젝트에 넣기

rule의 우선순위

rule 파일의 기본 구조

프론트엔드 프로젝트의 rule 예시

긴 규칙은 Markdown 파일로 빼기

rule 매칭 확인하기

구체적인 규칙을 앞에 두기

내장 규칙과 합치기

처음에는 작게 시작하기

에이전트와 같이 쓰기

OpenCode에서는 custom command로 감싸기

CI에서 쓰기

Viewer와 보안

언제 쓰면 좋을까

마무리

더 읽어보기

더 읽어보기