openqodex

OpenQodex：プッシュする前に変更をレビューする

OpenQodex は、1 つのコマンドで変更をレビューします。変更の固定コピーを作成し、変更されたファイルに適した決定論的スキャナー（gitleaks、semgrep、bandit、hadolint、shellcheck、actionlint、osv-scanner など）を実行して、変更行に関する報告を保持したうえで、専用のレビュアーを起動します。これは、そのコピーだけを読み取る別個の Claude Code または Codex プロセスです。レビュアーはすべてのスキャナーの検出結果を確認し、すべての変更行を与えられて、所定の形式で回答します。OpenQodex はスクリプトで回答を検証し、1 つのレポートを出力します。開発者の Claude Code または Codex のログイン以外に、キーやアカウントは必要ありません。コードは、そのログインで使用するモデルに送信されます。~/.openqodex/config.yaml で reviewer_web: off が設定されていない限り、レビュアーはウェブを検索したり、ウェブページを開いたりすることもできます。4 つのスキャナーはオンラインに接続しますが、コードを送信するものはありません。semgrep は実行のたびに Semgrep レジストリからルールパックをダウンロードします。変更が依存関係ファイルに触れる場合、osv-scanner は依存関係の名前とバージョンを osv.dev に送信します。kubeconform は Kubernetes スキーマをダウンロードします。cargo-deny は RustSec アドバイザリデータベースをダウンロードします。--offline は semgrep、osv-scanner、kubeconform、cargo-deny をスキップします。

実行するタイミング

• git push の前。
• 開発者から変更のレビューを頼まれたとき。
• OpenQodex のフックによってプッシュがブロックされたとき、または警告されたとき。
• 検出結果を修正した後、変更を再確認するとき。

レビュー担当

OpenQodex はレビューごとに独自のレビュアープロセスを起動します。このプロセスは、このセッションの内容を記憶していません。サブエージェントを起動したり、自分で変更をレビューしたりせず、コマンドを実行して出力を見せてください。

review が「Full review unavailable」と表示し、現在使用しているエージェントでレビューする方法を出力した場合は、その指示に従ってください。指定されたコマンドを実行し、出力された概要の指示に沿ってください。

手順

~/.openqodex/bin/openqodex が存在する場合は、このスキルのすべてのコマンドで npx -y openqodex@<version> の代わりに実行してください。これは openqodex init がインストールしたコピーです。存在しない場合、このスキルだけがインストールされており、プッシュチェックは行われていません。最初のレビューの前に、リポジトリから一度だけ npx -y [email protected] init --yes --agent <host> を実行してください。<host> には、使用しているエージェント（claude-code、codex、cursor、cline）を指定します。OpenQodex がインストールされ、レビュー担当者が開始できる状態になると変更をレビューします。そのため、数分かかることがあります。バックグラウンドで実行し、終了するまで待ってください。First review: finished と表示されたら、その行の上にあるレシートがレビュー結果です。手順 3 のとおりに提示し、手順 4 に進んでください。

1. リポジトリから次を実行します。

   npx -y [email protected] review
   

   変更をレビューします。まだプッシュされていないコミットに加え、未追跡ファイルを含むすべての未コミットの変更が対象です。リポジトリ全体をレビューするには、次を実行します。

   npx -y [email protected] review --all
   

2. 終了するまで待ちます。レビューには数分かかることがあります。OpenQodex は、--all を指定しない場合は 30 分後、指定した場合は 2 時間後にレビュー担当者を停止します。多くのエージェントは、コマンドをそれより早く停止します。そのため、バックグラウンドで実行し、終了するまで待ってください。レビュー担当者の作業中は、15 秒ごとに標準エラー出力へ進捗行が表示されます。実行中のレビューがある場合、二度目を開始しないでください。

3. 出力されたレシートを、表示どおりに開発者へ提示します。判定、指摘事項ごとの 1 行（番号、重大度、カテゴリ、タイトル、ファイル、行番号）、および report.html の絶対パスを含めます。言い換えたり、短くしたり、独自の指摘事項を追加したりしないでください。report.html のパスを伝えてください。このページでは、変更された各ファイルと、そのコード行の下に各指摘事項が表示されます。レシートが Observations (do not count toward the verdict): で終わり、その下に番号付きの行がある場合は、それらの行も表示どおりに提示してください。観察事項は、スタイル、命名、ドキュメント、テストに関するメモです。開発者が番号を指定しない限り、修正すべき指摘事項ではありません。

4. 開発者に「すべて修正しますか、それとも修正する項目を指定しますか？」と尋ねます。回答を得る前にコードを変更しないでください。開発者が「レビューしてすべて修正して」のように、修正する内容をすでに伝えている場合は、再度尋ねずに対応してください。

5. 開発者が指定した指摘事項だけを修正します。次のコマンドは、レシートの番号に基づいて、指定した指摘事項の詳細（場所、問題点、重要な理由、修正方法、出典）をすべて表示します。

   npx -y [email protected] findings 1,3
   

   findings all を指定すると、すべての指摘事項が表示されます。修正が完了したら、レビューを再実行し、新しいレシートを開発者に提示してください。

6. 終了コードに応じて対応します。

   • 0：レビューが完了しており、プッシュを妨げるものはありません。
   • 1：レビューが完了しており、判定は blocked です。プッシュしないでください。レシートを開発者に提示し、どの指摘事項を修正するか尋ねてください。指摘事項を確認した後、開発者がプッシュを指示した場合に限りプッシュしてください。
   • 2：レビューが完了していません。不足している内容が出力されます（例：レビュー担当者を起動できない場合の「Full review unavailable」、または理由付きの「Review incomplete」）。その内容を正確に開発者へ伝えてください。スキャナーの出力をレビュー結果として提示してはいけません。

ブランチまたはプルリクエストのレビュー

開発者から、現在の作業対象ではないブランチまたはプルリクエストのレビューを依頼された場合は、次のように指定します。

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 が 1 create a GitHub issue と 2 ignore を表示して「OpenQodex had a problem. Nothing has been sent.」と伝えた場合は、何が起きたかを一行で開発者に伝え、2 つの選択肢を提示してください。1 を選んではいけません。開発者が 1 と答えた場合は、同じフォルダーから npx -y [email protected] report --send-last を実行してください。それ以外の場合は 2 を選んだものとして扱い、何もしないでください。

レポートの確認

• レポートはリポジトリ内の .openqodex/reviews/<time>-<id>/ にあります。report.html はブラウザーで開くレポートです（変更された各ファイルの差分、行ごとの各指摘事項、その後にカバレッジ、スキャナー、影響範囲が表示されます）。report.md はテキスト形式で確認でき、report.json と report.sarif はツール用です。レシートには report.html と report.md の絶対パスが記載されます。.openqodex/latest.json は最新のレビューを指します。レポートは git status には表示されません。.openqodex/.gitignore により除外されているためです。このフォルダーにあるほかの 2 つのファイル、config.yaml と custom-instructions.md はチームのもので、コミットすることを想定しています。
• 判定は passed（警告の有無を問わず）または blocked です。blocked になるのは、リポジトリの設定（.openqodex/config.yaml またはルートにある .openqodex.yaml）で block_on_severity が設定されており、指摘事項の重大度がその値以上の場合に限られます。設定がない場合、OpenQodex は警告を出しますが、ブロックすることはありません。
• 完全なレビューとは、すべてのステージが実行され、すべてのスキャナーの指摘事項が確認され、変更されたすべての行がレビュアーに提示された状態です。カバレッジ対象外のものはレポートに明記されます。見落としが一切ないという意味ではありません。すべてを見つけられるレビューはありません。
• カバレッジ一覧には、各スキャナーが実行されたかどうかが記載されます。実行されなかったスキャナーには、理由が一行で示されます。
  • no matching files：変更内容に、そのスキャナーが読み取る種類のファイルがありません。
  • installing：初回ダウンロード中です。次回の実行から利用できます。待たずに、その旨を開発者に伝えてください。
  • not installed：この環境ではインストールできませんでした。理由も記載されています。
  • needs Ruby または needs Go：brakeman には Ruby 3.0 以降、rubocop には Ruby 2.7 以降、golangci-lint には Go が必要です。OpenQodex は言語ランタイムをインストールしません。開発者がこれらのスキャナーを使いたい場合は、各自のシステムで通常の方法で Ruby または Go をインストールして（たとえば Mac なら brew install ruby go）、レビューを再実行します。
  • untrusted：開発者が承認していない、リポジトリの設定にあるカスタムスキャナーです。開発者に伝えてください。承認するかどうかは開発者が決めます（npx -y [email protected] trust）。
  • failed：スキャナーは実行されましたが、エラーが発生しました。理由にエラーの内容が記載されています。スキャナーの問題によって終了コードが変わることはありません。

サンドボックス内

サンドボックスでコマンドを実行するエージェントもあります。ネットワークに接続できず、プロジェクト外に書き込めないサンドボックスでは、初回実行時にスキャナーをダウンロードできず、レビュアーがモデルにアクセスできないこともあります。開発者には、エージェントの外で、リポジトリ内に移動して自分のターミナルで一度、次のコマンドを実行するよう伝えてください。

npx -y [email protected] doctor --install

このコマンドは、リポジトリ内のファイルに必要なスキャナーを ~/.openqodex/tools/ にダウンロードし、それぞれの理由を表示します。--all-scanners を指定すると、すべてのスキャナーをダウンロードします。サンドボックス内でレビューに「Full review unavailable」と表示される場合は、開発者が自分のターミナルで 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 では、インストール、設定、カスタムスキャナー、および各メッセージの意味を説明しています。

関数を呼び出している箇所、関数の実装、2つの部分のつながり、変更の影響範囲を探すために多くのファイルを読む前に、コードグラフに問い合わせることができます。npx -y [email protected] graph help で問い合わせ内容を確認できます。または、エージェントが利用できる場合は openqodex MCP サーバーの graph_ ツールを使ってください。回答の unknown.floor が true の場合、呼び出し元が見つかっていない可能性があるため、「未使用」と解釈しないでください。

review.instructions_files にファイルを勝手に追加しないでください。レビュー担当者が使用できるファイルを開発者に確認してから、指定されたファイルだけを設定してください。デフォルトは [] です。選択したファイルの内容は .openqodex/custom-instructions.md に追加されます。