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が「完全なレビューは利用できません」と出力し、現在のエージェントでレビューする方法を表示した場合は、それに従ってください。指定されたコマンドを実行し、表示された簡単な指示に従ってください。
手順
~/.openqodex/bin/openqodexファイルが存在する場合、このスキルのすべてのコマンドでnpx -y openqodex@<version>の代わりにそれを実行してください。これはopenqodex initがインストールしたコピーです。ファイルが存在しない場合、このスキルは単独でインストールされており、プッシュチェックはありません。最初のレビューの前に、リポジトリからnpx -y [email protected] init --yes --agent <host>を1度実行してください。<host>は使用しているエージェント（claude-code、codex、cursor、cline）です。これによりOpenQodexがインストールされ、レビューアが起動可能になると変更をレビューするため、数分かかることがあります。バックグラウンドで実行し、終了するまで待機してください。「最初のレビュー: 完了」と表示された場合、その行の上のレシートがレビューのものです。手順3に従って表示し、その後手順4に進んでください。
-
リポジトリから以下を実行します:
npx -y [email protected] reviewこれにより、まだプッシュされていないコミットと、すべてのコミットされていない変更（追跡されていないファイルを含む）をレビューします。リポジトリ全体をレビューする場合は、以下を実行します:
npx -y [email protected] review --all -
完了するまで待機します。レビューには数分かかることがあります。OpenQodexは30分後（
--allの場合は2時間後）にレビューアを停止します。多くのエージェントはコマンドを早期に停止します。そのため、バックグラウンドで実行し、終了するまで待機してください。レビューアが動作中は、stderrに15秒ごとに進捗行が出力されます。実行中に2回目を起動しないでください。 -
開発者に、出力されたレシートをそのまま表示してください: 判定結果、問題ごとに1行（番号、重大度、カテゴリ、タイトル、ファイル、行番号）、および
report.htmlの絶対パス。言い換えたり、短縮したり、独自の問題を追加したりしないでください。report.htmlのパスも伝えてください。そのページには、各変更ファイルと、各問題がコード行の下に表示されます。レシートが「観察事項（判定にはカウントされません）」で終わり、その下に番号付きの行がある場合は、それらの行もそのまま表示してください。観察事項はスタイル、命名、ドキュメント、テストに関する注意事項です。開発者が番号を指定しない限り、修正すべき問題ではありません。 -
開発者に尋ねてください：「すべて修正しますか、それともどれを修正するか教えてください？」開発者が答える前にコードを変更しないでください。開発者がすでに何を修正するか指示している場合（例：「レビューしてすべて修正して」）、再度尋ねずにそれを行ってください。
-
開発者が指定した問題のみを修正してください。以下のコマンドは、レシートの番号で指定された問題を完全に（場所、問題、理由、修正方法、ソース）表示します:
npx -y [email protected] findings 1,3findings allですべての問題を表示します。修正が完了したら、再度レビューを実行し、新しいレシートを開発者に表示してください。 -
終了コードに応じて行動してください:
- 0: レビューが完了し、プッシュを妨げるものはありません。
- 1: レビューが完了し、判定は「ブロック」です。プッシュしないでください。開発者にレシートを表示し、どの問題を修正するか尋ねてください。開発者が問題を確認した後にプッシュすると言った場合のみプッシュしてください。
- 2: 完全なレビューはありません。出力に何が不足しているかが示されます（例：「完全なレビューは利用できません」（レビューアが起動できなかった場合）、または「レビューが不完全です」（理由付き））。その内容を正確に開発者に伝えてください。スキャナーの出力をレビューとして提示しないでください。
ブランチまたはプルリクエストのレビュー
開発者が現在の作業ではないブランチやプルリクエストのレビューを依頼した場合は、名前を指定してください:
npx -y [email protected] review feature/login
npx -y [email protected] review '#42'
#42は引用符で囲んでください。シェルでは#はコメントの開始を意味します。プルリクエストのリンクも使用できます。OpenQodexはターゲットを取得し、一時フォルダにチェックアウトして、ベースブランチから追加された内容をレビューします。これは他人のコードです。テスト、スクリプト、ビルド、サービスを決して実行せず、編集もしないでください。
ルール
- レビュー中はコードを編集しないでください。最初にレビューし、レシートを表示し、その後開発者が指定した問題のみを修正してください（手順3〜5）。
- 開発者に事前に尋ねずに
openqodex trustを実行しないでください。これはカスタムスキャナーを承認するものであり、開発者のマシン上で実行されるコマンドです。 OPENQODEX_SKIPは決して設定しないでください。これは開発者用のスイッチであり、あなたが使用するものではありません。- OpenQodexが、エージェント用に書き込んだファイルが古いバージョンであり、
initで更新できると表示した場合、そのことを1行で開発者に伝え、initコマンドを提示してください。開発者が依頼した場合のみ実行してください。エージェントファイルが書き換えられます。 - 判定が「ブロック」の場合、開発者が問題を確認した後にプッシュすると言った場合以外はプッシュしないでください。
- OpenQodexが「OpenQodexに問題が発生しました。何も送信されていません。」と表示し、「1 GitHub Issueを作成する」「2 無視する」の選択肢を表示した場合、何が問題だったかを1行で開発者に伝え、2つの選択肢を提示してください。自分で選択肢1を選択しないでください。開発者が1と言った場合、同じフォルダから
npx -y [email protected] report --send-lastを実行してください。それ以外の場合は選択肢2として、何もしないでください。
レポートの読み方
- レポートはリポジトリ内の
.openqodex/reviews/<時間>-<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はチームのものであり、コミットされることを意図しています。 - 判定は「合格」（警告ありまたは警告なし）または「ブロック」です。リポジトリの設定（
.openqodex/config.yaml、またはルートの.openqodex.yaml）がblock_on_severityを設定し、問題がそのレベル以上の場合のみ「ブロック」になります。設定がない場合、OpenQodexは警告を表示し、ブロックしません。 - 完全なレビューとは、すべてのステージが実行され、すべてのスキャナー結果がチェックされ、すべての変更行がレビューアに提示されたことを意味します。カバーされていないものはレポートに名前が記載されます。何も見逃されなかったことを意味するわけではありません。完全なレビューは存在しません。
- カバレッジリストには、各スキャナーが実行されたかどうかが表示されます。実行されなかったスキャナーには1行の理由があります:
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: スキャナーが実行され、壊れました。理由にエラーが表示されます。スキャナーの問題が終了コードを変更することはありません。
サンドボックス内での実行
一部のエージェントは、ネットワークにアクセスできない、またはプロジェクト外に書き込めないサンドボックス内でコマンドを実行します。その場合、初回実行でスキャナーをダウンロードできず、レビューアがモデルに到達できない可能性があります。開発者に、自身のターミナルで（エージェント外で）リポジトリ内で以下を1度実行するように伝えてください:
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 <トピック>でドキュメントのページをオフラインで表示します。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に追加されます。