PRレビューの認知負荷を下げるために、AIでdiffに濃淡をつけてみた

AI支援でコードを書く機会が増えると、Pull Requestの数やサイズも増えます。

AIは実装を速くしてくれますが、最終的に「この変更は本当に意図どおりか」「この業務ルールは正しいか」「この境界条件で問題ないか」を判断するのは、まだ人間の仕事として残っています。

一方で、人間のレビュー時間は増えません。

そこで、PR diffの中で 人間が注意して見るべき場所 を目立たせるビューアを作っています。

名前は Attention Diff です。

作っているもの

Attention Diffは、GitHub Pull Requestのdiffを、人間の確認必要度に応じた濃淡つきビューで表示するツールです。

目的は、AIレビューで人間のレビューを置き換えることではありません。

むしろ逆で、人間がレビューするときに、

• まずどこを見るべきか
• どの変更は軽く見てもよさそうか
• どの行には業務・仕様・運用上の判断が必要か
• authorに何を確認すべきか

を判断しやすくすることを目的にしています。

通常のdiffは「何が変わったか」を見せてくれます。
Attention Diffでは、それに加えて「どこに注意を向けるべきか」を見せたいと考えています。

何を濃くするのか

最初は「危なそうなファイルを濃くする」だけでもよさそうに見えました。

たとえば、billing、auth、permission、migrationのようなファイルです。

ただ、実際にはそれだけだと雑です。

billingファイルの中にも、既存パターンをコピーしただけの低注意度の変更はあります。
authファイルの中にも、aliasを1つ追加しただけのような機械的な変更はあります。

逆に、一見小さな条件式の変更でも、

• 対象者が変わる
• 権限が変わる
• デフォルト値が変わる
• fallbackの挙動が変わる
• 業務上の閾値が変わる

なら、人間が確認すべき変更になり得ます。

なのでAttention Diffでは、一般的なリスクではなく、人間に残された判断の大きさ を見るようにしています。

画面イメージ

濃く表示される行は、人間が確認すべき可能性が高い行です。

薄く表示される行は、既存パターンのコピー、機械的な置換、テスト上の定型変更など、軽く見てもよさそうな行です。

重要なのは、薄い行にも理由を持たせることです。

「薄いから見なくていい」ではなく、
「既存パターンと一致しているので、まずは優先度を下げてよさそう」
という説明があると、レビュアーの納得感が上がります。

仕組み

現在のMVPでは、Codex / Claude Code用のプラグインとして動かしています。

使う側は、GitHubリポジトリ内で次のように依頼します。

/attention-diff 190

内部では、おおまかに次の流れで動きます。

gh pr view / gh pr diff
  ↓
diff.json を生成
  ↓
Codex / Claude Code が attention.json を生成
  ↓
validation
  ↓
local viewer で表示

ポイントは、diff本体とAIの評価結果を分けていることです。

diff.json と attention.json を分ける

最初は、AIに「diffを読んで、表示用JSONを全部作ってもらう」ことも考えました。

ただ、その形だとコード本文をAIに再出力させる必要があります。

diffが大きいPRではトークンがもったいないですし、コード本文をAI出力に含めると、表示用データの正本が曖昧になります。

そこで、MVPでは2つのJSONに分けました。

diff.json
  - 機械的に生成する
  - code本文、file、hunk、line、行番号を持つ
  - viewerの正本

attention.json
  - AIが生成する
  - score、理由、確認質問を持つ
  - code本文は持たない
  - diff.json の fileId / hunkId / lineId を参照する

この分離にしたことで、AIにやらせたい仕事を「どこに注意すべきかの判断」に寄せられます。

コード本文や行番号の管理は、決定的に処理できるプログラム側に任せます。

attention.json のイメージ

attention.json には、hunk単位の確認理由と、行グループ単位の濃淡を入れています。

{
  "fileId": "file_0001",
  "attention": 4,
  "hunks": [
    {
      "hunkId": "file_0001_hunk_0001",
      "attention": 4,
      "reviewReason": "業務上の閾値変更なので、人間が仕様と照合する必要がある。",
      "skimReason": "周辺の代入処理は既存パターンに沿った追加。",
      "question": "この閾値は仕様として合意済みですか？",
      "attentionGroups": [
        {
          "id": "file_0001_hunk_0001_group_0001",
          "kind": "highlighted",
          "attention": 4,
          "lineIds": ["file_0001_hunk_0001_line_0003"],
          "label": "閾値変更",
          "reason": "集計結果に影響する境界値が変わっている。"
        }
      ]
    }
  ]
}

実際には、attention は1から5の5段階にしています。

濃淡は単純な「危険度」ではなく、「人間が判断すべき度合い」として扱います。

使ってみて感じたこと

実際にPRに対して試してみると、単に「危なそうなファイル」を見るよりも、hunkや行単位で濃淡が付いているほうがレビューしやすいと感じました。

特によかったのは、既存パターンのコピーや機械的な変更が薄くなることです。

大きめのPRでは、すべての変更を同じ強さで読むのがつらいです。
しかし、薄くしてよい理由が添えられていると、最初に読む場所を決めやすくなります。

一方で、今のローカルviewerだけだと課題もあります。

• IDEの関数ジャンプが使えない
• 参照検索や型情報を見に行きづらい
• GitHub Pull Requests拡張のようなPRレビュー体験にはまだ届かない

そのため、Attention Diffを通常のレビュー画面の置き換えにするより、レビュー前に見る注意マップ として使うのがよさそうだと考えています。

今後やりたいこと

直近では、viewerからVS Codeに飛べるリンクを追加したいです。

たとえば、

• hunkヘッダーから該当ファイルの行を開く
• 行番号クリックでVS Codeの該当行へ飛ぶ
• 高注意度のhunkだけ順に確認する

といった使い方です。

Attention Diff上で「どこを見るべきか」を決めて、詳しい確認はVS Codeで行う。

この役割分担が現実的そうです。

将来的には、小さなVS Code companion extensionを作って、Attention Diffの結果をIDE内のサイドバーに表示することも考えています。

インストール

Codexでは次のようにインストールできます。

codex plugin marketplace add Basio0916/attention-diff --ref main
codex plugin add attention-diff@attention-diff

Claude Codeでは次のようにインストールできます。

claude plugin marketplace add Basio0916/attention-diff
claude plugin install attention-diff@attention-diff

GitHub CLIとNode.js 20以上が必要です。

まとめ

AIがコードを書く量が増えても、人間のレビューが不要になるわけではありません。

むしろ、人間が限られた時間でどこを見るべきかを判断する重要性は上がっていると思います。

Attention Diffでは、diffに濃淡をつけることで、レビューの認知負荷を少しでも下げられないかを試しています。

まだMVPですが、AIレビューコメントを大量に投稿するよりも、まずは人間の注意配分を助けるUIとして育てていきたいです。