OpenQodex: push 전 코드 변경을 별도 리뷰어로 검토하는 도구

배경과 문제

같은 코딩 에이전트에게 자기 변경을 다시 리뷰하게 하면 작성 때의 맥락과 가정을 공유한다. 별도 세션에 검토를 맡기는 것은 다른 관점에서 점검할 기회를 주지만, 그것만으로 오류를 모두 찾는다는 보장은 없다. OpenQodex는 여기에 정적 분석과 코드 인용 대조를 붙여 리뷰가 무엇을 확인했는지 기록하려는 도구다.

OpenQodex는 이 검토를 push 직전, 개발자의 컴퓨터 안으로 옮기고 리뷰어를 코드를 쓴 에이전트와 분리한다. 리뷰 대상은 아직 push하지 않은 커밋과 커밋하지 않은 수정이다. 기본 설정에서는 코드를 쓴 에이전트가 리뷰를 맡지 않으며, 리뷰어는 사용자의 Claude Code 또는 Codex 로그인으로 실행되어 별도 계정이나 API 키가 필요 없다. 리뷰 요청은 Claude Code, Codex CLI, Cursor, Cline에서 모두 할 수 있지만 리뷰어 역할은 Claude Code와 Codex만 맡을 수 있다.

기존 접근의 한계

포럼은 Claude Code의 내장 /code-review와 비교해 OpenQodex의 별도 스캐너 단계와 코드 근거 검사를 강조한다. 22종 스캐너 중 파일 유형과 실행 환경에 맞는 것만 돌아가며 항상 모두 실행되는 것은 아니다. Claude Code 리뷰어는 사용자 설정과 지시 파일을 불러오지 않지만, 공식 agents 문서에 따르면 Codex 리뷰어는 전역 ~/.codex/AGENTS.md를 여전히 읽는다. 모든 리뷰어의 지시 환경이 완전히 비어 있다고 보면 부정확하다.

공식 벤치마크에는 같은 사례를 Claude Code의 /code-review medium으로 평가하는 대조군 모드가 있지만, 공개 결과표에는 아직 그 대조군 행이 없다. 따라서 별도 스캐너와 검증 구조가 있다는 사실은 확인할 수 있어도, 내장 리뷰보다 정확하다는 같은 사례의 비교 증거는 확보되지 않았다.

검토가 진행되는 순서

OpenQodex는 리뷰를 세 단계로 나눈다. 먼저 변경된 파일에 맞는 스캐너(gitleaks, semgrep처럼 모델 없이 코드를 검사하는 프로그램)를 실행하고 변경된 줄에 걸린 결과만 남긴다. 스캐너 결과는 테스트 픽스처와 사용자가 끈 규칙의 결과를 버리고, 의존성 검사는 예외적으로 저장소의 모든 lockfile을 리뷰할 때마다 osv.dev에 조회하되 변경 줄 밖의 취약점 권고는 보여주기만 하고 판정에 세지 않는다.

다음으로 세션 기억이 없는 별도의 Claude Code 또는 Codex 프로세스를 띄운다. 찾기(finder) 세션은 변경 부분과 그 코드를 호출하는 코드를 함께 읽고 문제 후보를 근거 줄과 함께 제안한다. 검증(verifier) 세션은 그 후보와 스캐너 결과를 하나씩 확인 또는 반박하며, 이 모든 과정을 스크립트가 검사한다. 리뷰어는 개발자의 작업 폴더가 아니라 ~/.openqodex/checkouts/ 아래 변경 사본을 읽고, Claude Code 리뷰어에게는 읽기·검색·목록 도구와 웹 검색·웹 페이지 열기 도구만 주어지며 셸과 파일 수정, MCP 서버, 서브에이전트는 주어지지 않는다.

마지막으로 OpenQodex는 판정과 지적 목록을 담은 영수증(receipt)을 출력하고 개발자가 어떤 지적을 고칠지 고른다. 보고서는 저장소의 .openqodex/reviews/ 폴더에 report.html, report.md, report.json, report.sarif로 저장되고 .openqodex/.gitignore가 이 보고서들을 git에서 제외한다. 모든 단계가 실행되지 않은 리뷰는 'Review incomplete'와 빠진 단계를 출력하고 종료 코드 2로 끝난다.

결과와 숫자의 의미

개발팀의 합성 개발셋에는 버그 51개와 버그 없는 변경 2개가 있고, 세 번 반복하면 버그 평가 기회 153회와 깨끗한 변경 평가 6회가 된다. Claude Code의 최고 결과는 150/153, 즉 98.0%다. 이 두 행은 10월 27일 main 빌드 76a4cd15와 1dd1f708이며 채점 규칙은 11과 12다. 84.3%는 10월 12일 빌드의 규칙 7 결과다. 포럼은 당시 0.15.0을 소개하지만 이번에 고정한 공식 main의 package 버전은 0.16.0이다. 이 결과들을 현재 배포판의 측정값이나 규칙까지 동일한 개선 비교로 읽을 수는 없다.

AACR-Bench 결과는 전체 200개 PR이 아니라 dev-laptop 36개 PR·정답 이슈 256개 부분집합이다. Claude의 한 번 평가 위치 재현율은 56/256=21.9%, 71/256=27.7%였고, 앞선 세 번 반복 행은 82/768=10.7%였다. 이는 정답 위치의 한 줄 이내에 지적이 붙었는지만 센다. 내용까지 같은 문제인지 사람이 판정하는 issue recall은 모델 리뷰어 행 모두 아직 미판정이다. 별도 라이브러리 경로에서 gpt-6.1-sol을 AACR 평가기로 채점한 의미 재현율 5.2%도 Claude CLI의 위치 지표와 구분해야 한다.

구체적인 예시

예시 보고서에는 지적의 심각도, 분류, 파일과 줄 위치가 함께 나온다. 검토가 끝나면 판정과 지적 목록을 담은 영수증을 보여주고 개발자가 수정 범위를 고르는 흐름이다. 이미 모든 수정을 요청한 경우에는 다시 묻지 않는다는 공식 문서 설명도 있다. 이 절차는 에이전트에게 주는 작업 지침이며, 지정하지 않은 수정을 기술적으로 불가능하게 만드는 잠금 장치는 아니다.

코드 그래프는 모델 없이 저장소의 함수, 클래스, 타입과 그 사이의 호출, import, 상속 관계를 계산한다. 지원 언어는 TypeScript, TSX, JavaScript, Python, Go, Ruby, Java이며, Django, Rails, Express, React, Next.js, FastAPI, Go net/http는 프레임워크 플러그인이 라우트와 핸들러 같은 관계를 따로 읽는다. 그래프의 각 호출 관계에는 그것을 증명한 근거와 확실도(certain, likely, possible)가 붙는다. OpenQodex는 리뷰 개요(brief)에 바뀐 코드의 호출자를 그래프에서 뽑아 넣는다.

한계와 오해하기 쉬운 점

수치는 개발팀이 공개한 측정이며 이번 검토에서 독립 재현하지 않았다. 정밀도 상·하한은 사람이 아직 판정하지 않은 지적을 모두 오답 또는 모두 정답으로 센 범위로, 통계적 신뢰구간과 다르다. 작은 합성 저장소에서는 그래프 없이도 리뷰어가 호출자를 검색할 수 있었다. 따라서 대규모 저장소에서 코드 그래프가 얼마나 도움이 되는지도 이 결과만으로는 알 수 없다.

로컬에서 실행해도 리뷰어는 읽은 코드를 Claude Code·Codex 로그인이 사용하는 외부 모델 서비스에 보낸다. --offline은 일부 스캐너의 네트워크와 다운로드를 끄지만 모델 호출은 남는다. 별도 리뷰어를 시작하지 못할 때의 review --agent는 작성 에이전트가 스스로 검토하는 fallback이다. 기본 push 게이트는 경고만 하고, 차단 설정을 켜도 불완전 리뷰와 게이트 자체 조회 실패는 통과한다. 검토 완료나 push 허용을 코드 안전성 보증으로 볼 수 없다.

실제로 어떻게 활용할까

사용 환경은 Node 22 이상과 git, macOS 또는 Linux이며 전체 리뷰에는 로그인된 Claude Code나 Codex가 필요하다. init은 작성할 파일 목록을 보여준 뒤 리뷰 스킬, push 훅, 권한 규칙, 코드 그래프 MCP 등록과 런처 등을 설치한다. 사용자 설정뿐 아니라 저장소의 지시 파일도 바꿀 수 있으므로 적용 범위를 확인해야 한다. 추가 계정이나 키가 필요 없다는 설명이 모델 사용량까지 무료라는 뜻은 아니다.

실제 적용에서는 자기 저장소의 대표 변경을 대상으로 발견한 문제, 잘못된 지적, 실행되지 않은 단계를 함께 보는 편이 유용하다. 에이전트 훅은 현재 작업의 리뷰 기록을, git pre-push 훅은 실제 보낼 변경의 기록을 확인한다. review.block_on_severity를 설정해야 미리뷰 변경과 해당 심각도 이상 지적을 차단하며, git 훅은 --no-verify로도 건너뛸 수 있다. 이런 범위를 이해한 뒤 팀의 기존 검토 절차에 보조 수단으로 넣는 것이 이 자료에서 도출되는 활용 관점이다.