openqodex

OpenQodex: 푸시 전에 변경 사항 리뷰하기

OpenQodex는 하나의 명령어로 변경 사항을 리뷰합니다. 변경 사항의 스냅샷을 복사한 후, 변경된 파일에 맞는 결정론적 스캐너(gitleaks, semgrep, bandit, hadolint, shellcheck, actionlint, osv-scanner 등)를 실행하고, 변경된 라인에 대한 보고만 유지한 다음 자체 리뷰어를 시작합니다. 리뷰어는 별도의 Claude Code 또는 Codex 프로세스로, 복사본만 읽습니다. 리뷰어는 모든 스캐너 결과를 확인하고, 모든 변경된 라인을 전달받아 정해진 형식으로 답변합니다. OpenQodex는 스크립트로 답변을 확인하고 하나의 보고서를 출력합니다. 개발자의 Claude Code 또는 Codex 로그인 외에 별도의 키나 계정이 필요하지 않습니다. 코드는 해당 로그인이 사용하는 모델로 전송됩니다. ~/.openqodex/config.yaml에서 reviewer_web: off를 설정하지 않는 한 리뷰어는 웹을 검색하고 웹 페이지를 열 수 있습니다. 네 개의 스캐너는 온라인으로 작동하며, 어떤 스캐너도 코드를 전송하지 않습니다. semgrep은 실행할 때마다 Semgrep 레지스트리에서 규칙 팩을 다운로드합니다. 변경 사항이 의존성 파일을 포함하면 osv-scanner는 의존성 이름과 버전을 osv.dev로 전송합니다. kubeconform은 Kubernetes 스키마를 다운로드합니다. cargo-deny는 RustSec 권고 데이터베이스를 다운로드합니다. --offline은 semgrep, osv-scanner, kubeconform, cargo-deny를 건너뜁니다.

실행 시기

• git push를 실행하기 전.
• 개발자가 변경 사항 리뷰를 요청할 때.
• OpenQodex 훅에 의해 푸시가 차단되거나 경고되었을 때.
• 발견 사항을 수정한 후, 변경 사항을 다시 확인할 때.

리뷰어

OpenQodex는 리뷰할 때마다 자체 리뷰어 프로세스를 시작하며, 이 세션에 대한 메모리는 없습니다. 직접 서브에이전트를 시작하거나 변경 사항을 직접 리뷰하지 마세요. 명령어를 실행하고 출력된 결과를 보여주세요.

review 명령어가 "전체 리뷰를 사용할 수 없음"이라고 출력하고 현재 사용 중인 에이전트로 리뷰하는 방법을 알려주면, 지침을 따르세요. 명령어를 실행하고 출력된 브리핑에 따라 작업하세요.

절차

~/.openqodex/bin/openqodex 파일이 존재하면, 이 스킬의 모든 명령어에서 npx -y openqodex@<version> 대신 이 파일을 실행하세요. 이는 openqodex init이 설치한 복사본입니다. 파일이 존재하지 않으면, 이 스킬이 푸시 검사 없이 단독으로 설치된 것입니다. 첫 리뷰 전에 저장소에서 npx -y [email protected] init --yes --agent <host>를 한 번 실행하세요. 여기서 <host>는 현재 사용 중인 에이전트(claude-code, codex, cursor 또는 cline)입니다. 이 명령어는 OpenQodex를 설치한 후 리뷰어를 시작할 수 있을 때 변경 사항을 리뷰하므로 몇 분이 걸릴 수 있습니다. 백그라운드에서 실행하고 종료될 때까지 기다리세요. "첫 번째 리뷰: 완료"라고 출력되면, 그 위의 영수증이 리뷰 결과입니다. 3단계에 따라 표시하고 4단계부터 진행하세요.

1. 저장소에서 다음 명령어를 실행하세요:

   npx -y [email protected] review
   

   이 명령어는 변경 사항(아직 푸시되지 않은 커밋과 추적되지 않은 파일을 포함한 모든 커밋되지 않은 변경 사항)을 리뷰합니다. 전체 저장소를 리뷰하려면 다음 명령어를 실행하세요:

   npx -y [email protected] review --all
   

2. 기다리세요. 리뷰는 몇 분이 걸릴 수 있습니다. OpenQodex는 30분 후에 리뷰어를 중지하며, --all의 경우 2시간 후에 중지합니다. 많은 에이전트가 명령어를 더 일찍 중지합니다. 따라서 백그라운드에서 실행하고 종료될 때까지 기다리세요. 리뷰어가 작업하는 동안 15초마다 stderr에 진행 상황을 출력합니다. 하나가 실행 중일 때 두 번째 리뷰를 시작하지 마세요.

3. 개발자에게 출력된 영수증을 그대로 보여주세요: 판정, 각 발견 사항에 대해 한 줄(번호, 심각도, 카테고리, 제목, 파일, 라인) 및 report.html의 절대 경로. 내용을 바꾸거나, 줄이거나, 자신의 발견 사항을 추가하지 마세요. report.html 경로를 알려주세요. 해당 페이지는 각 변경된 파일과 각 발견 사항을 코드 라인 아래에 표시합니다. 영수증이 Observations (판정에 포함되지 않음):으로 끝나고 그 아래에 번호가 매겨진 줄이 있으면, 그 줄도 그대로 보여주세요. 관찰 사항은 스타일, 이름 지정, 문서 또는 테스트 노트입니다. 개발자가 번호를 지정하지 않는 한 수정해야 할 발견 사항이 아닙니다.

4. 개발자에게 물어보세요: "모두 수정할까요, 아니면 어떤 것을 알려주시겠어요?" 개발자가 답변하기 전에 코드를 변경하지 마세요. 개발자가 이미 무엇을 수정할지 말했다면(예: "리뷰하고 모두 수정해줘"), 다시 묻지 않고 그대로 진행하세요.

5. 개발자가 지정한 발견 사항만 수정하세요. 다음 명령어는 영수증의 번호로 발견 사항을 전체 내용(위치, 문제, 중요성, 수정 방법, 출처)과 함께 출력합니다:

   npx -y [email protected] findings 1,3
   

   findings all은 모든 발견 사항을 출력합니다. 수정이 완료되면 리뷰를 다시 실행하고 개발자에게 새 영수증을 보여주세요.

6. 종료 코드에 따라 조치하세요:

   • 0: 리뷰가 완료되었으며 푸시를 막는 것이 없습니다.
   • 1: 리뷰가 완료되었으며 판정이 blocked입니다. 푸시하지 마세요. 개발자에게 영수증을 보여주고 어떤 발견 사항을 수정할지 물어보세요. 개발자가 발견 사항을 확인한 후에만 푸시하세요.
   • 2: 완전한 리뷰가 없습니다. 출력에 무엇이 누락되었는지 나와 있습니다(예: 리뷰어를 시작할 수 없는 경우 "전체 리뷰를 사용할 수 없음", 또는 사유와 함께 "리뷰 불완전"). 개발자에게 정확히 알리세요. 스캐너 출력을 리뷰로 제시하지 마세요.

브랜치 또는 풀 리퀘스트 리뷰

개발자가 현재 작업 중이 아닌 브랜치나 풀 리퀘스트 리뷰를 요청하면, 이름을 지정하세요:

npx -y [email protected] review feature/login
npx -y [email protected] review '#42'

#42는 따옴표로 감싸야 합니다. 셸에서 #은 주석을 시작하기 때문입니다. 풀 리퀘스트 링크도 작동합니다. OpenQodex는 대상을 가져와 임시 폴더에 체크아웃하고, 베이스에서 분기된 이후 추가된 내용을 리뷰합니다. 이는 다른 사람의 코드이므로, 절대 테스트, 스크립트, 빌드 또는 서비스를 실행하거나 편집하지 마세요.

규칙

• 리뷰 중에는 코드를 편집하지 마세요. 먼저 리뷰하고, 영수증을 보여준 다음, 개발자가 지정한 발견 사항만 수정하세요(3~5단계).
• 개발자에게 먼저 묻지 않고 openqodex trust를 실행하지 마세요. 이는 사용자 머신에서 실행되는 명령어인 사용자 정의 스캐너를 승인합니다.
• OPENQODEX_SKIP을 설정하지 마세요. 이는 개발자용 스위치이지, 당신의 것이 아닙니다.
• OpenQodex가 에이전트용으로 작성한 파일이 이전 버전이고 init이 새로고침한다고 출력하면, 개발자에게 한 줄로 알리고 해당 init 명령어를 제공하세요. 개발자가 요청할 때만 실행하세요. 에이전트 파일을 다시 작성합니다.
• 판정이 blocked이면, 개발자가 발견 사항을 확인한 후에만 푸시하세요.
• OpenQodex가 "OpenQodex에 문제가 발생했습니다. 아무것도 전송되지 않았습니다."라고 출력하면서 1 GitHub 이슈 생성과 2 무시를 보여주면, 개발자에게 한 줄로 무슨 문제였는지 알리고 두 가지 선택지를 제공하세요. 직접 1을 선택하지 마세요. 개발자가 1을 선택하면, 같은 폴더에서 npx -y [email protected] report --send-last를 실행하세요. 그 외의 경우는 2를 의미합니다. 아무것도 하지 마세요.

보고서 읽기

• 보고서는 저장소의 .openqodex/reviews/<time>-<id>/ 디렉토리에 있습니다: report.html(브라우저에서 열기, 각 변경 파일을 diff로 표시하고 각 발견 사항을 해당 라인 아래에 표시, 커버리지, 스캐너, 블래스트 래디어스 포함), report.md(텍스트로 읽기), report.json 및 report.sarif(도구용). 영수증은 report.html과 report.md의 절대 경로를 제공합니다. .openqodex/latest.json은 가장 최근 리뷰를 가리킵니다. 보고서는 git status에 표시되지 않습니다. .openqodex/.gitignore가 제외합니다. 해당 폴더의 다른 두 파일인 config.yaml과 custom-instructions.md는 팀 파일이며 커밋 대상입니다.
• 판정은 passed(경고 유무와 관계없음) 또는 blocked입니다. 저장소 구성(.openqodex/config.yaml 또는 루트의 .openqodex.yaml)이 block_on_severity를 설정하고 발견 사항이 해당 수준 이상인 경우에만 blocked입니다. 구성이 없으면 OpenQodex는 경고하고 차단하지 않습니다.
• 완전한 리뷰는 모든 단계가 실행되고, 모든 스캐너 결과가 확인되었으며, 모든 변경된 라인이 리뷰어에게 제시되었음을 의미합니다. 포함되지 않은 내용은 보고서에 명시됩니다. 아무것도 놓치지 않았다는 의미는 아닙니다. 어떤 리뷰도 모든 것을 찾아내지는 못합니다.
• 커버리지 목록은 각 스캐너가 실행되었는지 여부를 보여줍니다. 실행되지 않은 스캐너는 한 줄짜리 이유를 표시합니다:
  • no matching files: 변경 사항에 스캐너가 읽는 파일 종류가 없습니다.
  • installing: 처음 다운로드 중이며, 다음 실행부터 포함됩니다. 기다리지 말고 개발자에게 알리세요.
  • not installed: 여기에 설치할 수 없습니다. 이유가 설명됩니다.
  • needs Ruby 또는 needs Go: brakeman은 Ruby 3.0 이상, rubocop은 Ruby 2.7 이상, golangci-lint는 Go가 필요합니다. OpenQodex는 언어 런타임을 설치하지 않습니다. 개발자가 해당 스캐너를 원하면, 시스템에 맞는 일반적인 방법(예: Mac에서 brew install ruby go)으로 Ruby 또는 Go를 설치하고 리뷰를 다시 실행하세요.
  • untrusted: 저장소 구성의 사용자 정의 스캐너로 개발자가 승인하지 않았습니다. 개발자에게 알리세요. 승인은 개발자의 결정입니다(npx -y [email protected] trust).
  • failed: 스캐너가 실행되었으나 중단되었으며, 이유에 오류가 포함됩니다. 스캐너 문제는 종료 코드를 변경하지 않습니다.

샌드박스 내부

일부 에이전트는 네트워크에 연결할 수 없거나 프로젝트 외부에 쓸 수 없는 샌드박스에서 명령어를 실행합니다. 이러한 경우 첫 번째 실행에서 스캐너를 다운로드할 수 없고, 리뷰어가 모델에 도달하지 못할 수 있습니다. 개발자에게 에이전트 외부의 자신의 터미널에서 저장소 내에서 다음 명령어를 한 번 실행하도록 알리세요:

npx -y [email protected] doctor --install

이 명령어는 이 저장소의 파일이 필요로 하는 스캐너를 ~/.openqodex/tools/에 다운로드하고 각각에 대한 이유를 출력합니다. --all-scanners는 모든 스캐너를 다운로드합니다. 샌드박스 내에서 리뷰가 여전히 "전체 리뷰를 사용할 수 없음"이라고 표시되면, 개발자는 자신의 터미널에서 npx -y [email protected] review를 실행하세요.

더 알아보기

npx -y [email protected] guide는 이 가이드를 출력합니다. npx -y [email protected] guide <topic>은 문서 페이지를 오프라인으로 출력합니다: quickstart, config, scanners, custom-scanners, security, agents, cli, for-agents. for-agents는 설치, 구성, 사용자 정의 스캐너 및 각 메시지의 의미를 다룹니다.

함수를 호출하는 위치, 구현체, 두 부분이 어떻게 연결되는지 또는 변경 사항이 무엇에 영향을 미치는지 찾기 위해 많은 파일을 읽기 전에 코드 그래프를 요청할 수 있습니다: npx -y [email protected] graph help는 질문 목록을 표시하거나, 에이전트에 openqodex MCP 서버의 graph_ 도구가 있으면 사용하세요. unknown.floor가 true인 답변은 호출자가 누락되었을 수 있으므로 "사용되지 않음"으로 읽지 마세요.

절대 review.instructions_files에 파일을 직접 추가하지 마세요. 리뷰어가 사용할 파일을 개발자에게 물어보고, 개발자가 지정한 것만 설정하세요. 기본값은 []이며, 선택된 파일은 .openqodex/custom-instructions.md에 추가됩니다.