differential-review

differential-review skillの概要

differential-review は何をするのか

differential-review skill は、PR、コミット、diff を通常のプロンプトよりも厳密にレビューするための、セキュリティ重視のワークフローです。認証、暗号、外部呼び出し、状態変更、その他リスクの高い経路に変更が入ったとき、回帰を招くかどうかを判断したいレビュアー向けに作られています。

どんな人に向いているか

セキュリティ上重要なコードをレビューしている場合、大きな diff を引き継いだ場合、あるいはコードベースの規模に応じて調整できる再現性のある手法が必要な場合に、differential-review skill は特に向いています。表面的な行ごとの流し読みではなく、根拠に基づいた指摘を求めるエンジニア、セキュリティレビュアー、AI 支援の監査担当者に適しています。

何が違うのか

differential-review の主な価値は、結論より先にコンテキストを必須にする点です。ベースラインの履歴、影響範囲、テストカバレッジ、そして明示的な確信度の限界まで確認します。さらに、リポジトリは出力を構造化された markdown レポートに落とし込むため、これは単なる分析プロンプトではなく、成果物を伴うレビュー手順になっています。

differential-review skill の使い方

インストールして skill を読み込む

典型的な differential-review install は、まずリポジトリのツールチェーンを使い、その後でエージェントを skill フォルダに向けます。このパッケージでは、インストール先は plugins/differential-review/skills/differential-review です。Trail of Bits の skills repo を使っている場合は、プロジェクトの skills コマンドでインストールし、最初に SKILL.md を開いてください。

レビュー向けの入力を与える

differential-review usage を最大限に活かすには、特定の base/head 範囲、コミット、または PR をレビュー対象として指定し、分かっているならセキュリティ上の懸念も添えてください。たとえば、「base..head を auth bypass、reentrancy、テスト不足の観点でレビューし、外部呼び出し経路と状態遷移に注目してほしい」のような入力は強い例です。「この diff を見て」のような曖昧な指示は、推測に頼る余地が大きすぎます。

最初に読むべきファイル

良い differential-review guide は、まず SKILL.md を読み、続いて methodology.md、adversarial.md、patterns.md、reporting.md に進みます。これらのファイルには、ベースラインのコンテキストをどう作るか、どんな攻撃モデルを使うか、何をスキャンするか、最終レポートをどう整形するかが書かれています。この plugin には補助スクリプトや追加の参照フォルダはないため、skill ファイル自体が唯一の正本です。

出力品質を左右するワークフローのコツ

明確な diff、ベースラインのコミット、そして呼び出し元やテストを確認できるだけのリポジトリ文脈を渡せるときに使うのが理想です。コードベースが小・中・大のどれかを伝えるか、スケールを推定させても構いませんが、ベースライン／履歴の確認は省かないでください。differential-review for Code Review で価値が高い入力は、変更ファイル、想定される信頼境界、怪しい関数、そして既知の回帰履歴など、具体的な情報です。

differential-review skill の FAQ

differential-review はセキュリティレビュー専用ですか？

はい、基本的にはそのとおりです。一般的なスタイル整形や機能受け入れではなく、セキュリティに焦点を当てた differential review のために設計されています。通常のコードレビューにも使えますが、本領を発揮するのは、変更が信頼境界、データ整合性、または悪用可能性に影響しうるときです。

普通のプロンプトと何が違うのですか？

普通のプロンプトは diff の要約で終わることがありますが、differential-review は履歴、影響範囲、攻撃者モデルを使ってリスクを立証または反証しようとします。さらに markdown レポートを前提にしているため、結果を引き継ぎやすく、保管もしやすくなっています。

初心者でも使いやすいですか？

初心者でも使えますが、特定の diff を指し示して、構造化された分析を求められることが前提です。コードベースに詳しくなくても、ベースラインのコンテキストを要求し、足りないカバレッジを明示してくれるので役立ちます。

どんなときに使わないほうがいいですか？

些細な文言変更、低リスクな書式修正だけの PR、あるいは 1 段落の要約だけで足りる場合には、differential-review は使わないでください。意味のあるセキュリティリスクや回帰リスクがないなら過剰ですし、深掘りする価値があるときにだけ、そのプロセスが生きてきます。

differential-review skill を改善する方法

レビューの文脈をもっと具体的に渡す

最も大きな改善は、skill に正確なレビュー対象を渡すことです。PR 番号、コミット範囲、対象ブランチ、そして疑っているリスク領域を明示してください。プロジェクトのドメインが分かっているなら、先に伝えるのも有効です。たとえば Solidity の変更、API の認証フロー、支払い経路などを伝えると、分析が適切な攻撃モデルに寄ります。

初回で欲しい深さを最初に指定する

differential-review usage をより良くしたいなら、正確性、悪用可能性、回帰リスクのどれを重視するかを指定してください。たとえば、「外部から呼べる関数、変更されたバリデーション、新しい分岐に対するテスト漏れを重視してほしい」といった指示です。そうすると、重要な経路に検索範囲を絞り込めるため、ノイズの多い指摘が減ります。

よくある失敗パターンに注意する

見落としがちな点は、小さな diff を低リスクとみなすこと、削除されたコードの履歴を無視すること、そして影響範囲を判断するときに間接的な呼び出し元を忘れることです。skill はまさにその失敗を避けるために書かれていますが、それでも適切に機能させるには、具体的なベースラインと、境界が明確な diff が必要です。

最初のレポートのあとで反復する

最初のレポートを次のパスの調整に使ってください。結果が広すぎるなら、攻撃者モデルを絞るか、特定のサブシステムを深掘りするよう依頼します。浅すぎるなら、より多くの履歴、より厳しいテスト確認、あるいは不変条件と回帰経路への厳密なフォーカスを指定して再実行させてください。