AI エージェント時代における変更の受け取り方：Hunk を活用した差分レビューの再構築

こんにちは。Algomatic でソフトウェアエンジニアをしている Go（@53able）です。

コードレビューは、昔から「完成したファイル」全体を読むのではなく、「変更された箇所」に注力する仕事でした。ローカル環境では git diff で差分を確認し、Pull Request 上では変更行に対してコメントを残す。開発者は、コードそのものよりも、そこに付加された変化を受け取ることに慣れてきました。

Rethinking Code Review in the Age of AI は、AI 時代のコードレビューを再考するためのビジョンやフレームワークを示す論文です。ここでは、レビューの場所が手元の確認から Pull Request 中心のワークフローへ移行し、AI コーディングアシスタントの利用によってレビュー対象の量が膨れ上がっているという問題提起がなされています。変化しているのは、差分が生じる速度と量です。

arxiv.org

AI エージェントに任せた変更であっても、最終的には人間が差分として読み解く必要があります。どのファイルが変わったのか。なぜその変更が行われたのか。危険な箇所はどこか。説明とコードは整合しているのか。

チャット上で「完了しました」と言われただけでは、まだ変更を受け取ったことにはなりません。変更箇所を直接確認し、意図を読み取り、責任を持って判断できる状態にして初めて、「受け取った」と言えるのです。

Hunk は、この「受け取り方」を整備するためのターミナル用差分ビューアです。README では Hunk を、エージェントが作成した変更セットを対象とした「レビューファーストのターミナル差分ビューア」と定義しています。この記事では、Claude Code や Codex、Copilot Agent などにコード変更を任せるようになった開発者向けに、Hunk を活用した差分の受け取り方を整理します。

github.com

本記事で扱うのは、以下の 3 つです。

• Hunk で AI エージェントの差分を確認する最小限の手順
• 人間とエージェントでレビューの役割を分ける方法
• Hunk だけでは確認できないこと

私のスタンスはシンプルです。AI エージェントを「コードを書く相手」としてだけ扱ってはいけません。

AI が速く書くほど、開発者は「どう受け取るか」を設計する必要があります。差分を読む場所、コメントを残す場所、最終判断を下す場所が曖昧なままだと、AI の高速化は逆にレビューの負担として跳ね返ってきます。

最近の研究も、この見方と近い位置にあります。Human oversight of agentic systems in practice では、開発者がエージェントを利用する際の監督作業を、「事前制御」「共同計画」「実行中の観察」「事後レビュー」の 4 つに分類しています。

arxiv.org

Hunk が主眼を置くのは、変更後のレビューと、--watch やライブセッションを通じて変化する差分（diff）の追跡です。エージェントの行動ログや推論プロセスそのものを監視するツールではありません。

Human-AI Synergy in Agentic Code Review では、AI エージェントが欠陥スクリーニングの範囲を広げる一方で、人間は文脈に依存したフィードバック——理解やテスト、知識共有など——を担う役割が大きくなると報告されています。

arxiv.org

ただし、AI の提案が人間の提案よりも採用率が低いというデータもあり、AI エージェントの提案を鵜呑みにするのは危険です。だからこそ、人間が判断しやすい単位に差分を戻す方が理にかなっています。

• AI が書いた差分で困ること

• まずはこの手順で試す

• Hunk が AI エージェントと相性がいい理由

1. AI の作業は差分として残る

• 2. 人間とエージェントが同じ差分を見られる

• 3. 差分の構造だけを先に読める

• Hunk でコメントを差分の近くに置く

• 変更のやり直しを同じ画面で追う

• エージェント向けの使い方が用意されている

• 実務ではこう使う

1. まず変更の広がりを見る

• 2. エージェントに見るべき hunk を絞らせる

• 3. コメントを読んだうえで人間が判断する

• 4. 修正後も同じ画面で確認する

• Hunk だけでは確認できないこと

• まとめ: Hunk は AI の変更を受け取る場所になる

• エンジニアを募集しています！

AI エージェントを使えば、個々の PR（プルリクエスト）が常に大きくなるわけではありません。それでも、生成と修正の反復が速まるほど、チーム全体で確認する差分の量やレビュー回数は増えやすくなります。小さな修正なら追えますが、複数ファイルにまたがる変更や再編集が続く場面では、レビュー側の負担はすぐに膨らみます。

具体的には、以下のような課題が発生します。

• 変更ファイルが多く、どこから手をつけるべきか分からない
• エージェントの説明と差分（diff）を行き来する必要がある
• リスクのある hunk と整形された差分が混在している
• レビューコメントがチャット側に残り、コードから離れてしまう
• エージェントが再編集するたびに、レビュー対象を最初から追わなければならない

README では、マルチファイルのレビューストリーム、インライン AI/エージェント注釈、分割・スタック・自動レイアウト機能、ウォッチモード、キーボードやマウス、ページャー、Git difftool への対応などを主要機能として挙げています。これらの機能はすべて、AI が生成した後の確認作業を想定して設計されています。

github.com

Hunk の役割は、AI にコードを書かせることではありません。あくまで AI が生成した変更を、人間が読みやすい形に整えるためのツールです。

まずはこの手順で試す

使い方はシンプルです。

• Hunk をインストールする。

npm i -g hunkdiff

Homebrew を利用している場合はこちらです。

brew install hunk

• 別のターミナルやエディタ上で、Claude Code、Codex、Copilot Agent などにコードの変更を行わせます。

• 変更された作業用ブランチ（working tree）を Hunk で確認します。

hunk diff

スクリーンショットを見れば、Hunk の役割がより明確になります。画像を見る前に、まず何に注目すべきかを整理しておきましょう。

作業中の変更を確認する。 hunk diff コマンドは、まだコミットされていない作業用ブランチの変更を開きます。追加された行と削除された行を、hunk（変更のまとまり）単位で確認できます。

imageHunk で作業用ブランチの差分を開いた例

コミット済みの変更を確認する。 hunk show HEAD コマンドを使えば、最新コミットの内容を同じ UI で開けます。作業中の差分だけでなく、コミット後の確認にも活用できます。

imageHunk で最新コミットを開いた例

ここまでは、ローカルリポジトリにある変更を確認する例でした。もう一つ便利な使い方が、「変更内容だけを受け取って確認する」方法です。

例えばコードレビューの依頼で「この変更を見てください」と、.patch や .diff ファイルだけが送られてくることがあります。パッチファイルとは、Git で生成した差分ファイルを保存したものです。中身は「この行を削除し、この行を追加する」という変更内容そのものであり、対象ファイルや周辺コンテキストが合っていれば、別の環境でも同じ変更を再現できます。

Hunk では、このパッチファイルも通常の差分画面として開くことができます。

hunk patch change.patch

git diff の出力など、ファイルに保存せずにパイプで渡す場合のみ、標準入力（stdin）を使用します。

git diff --no-color | hunk patch -

パッチを Hunk で見る。 画面上部の before.js → after.js は、「どのファイルからどのファイルへの変更か」を示しています。緑色の行が追加された内容です。保存済みのパッチはファイル名で指定し、パイプラインの場合は標準入力から読み込みます。どちらも通常の差分表示と同じ見た目なので、すぐに確認できます。

image標準入力からパッチを読み込んで Hunk で開いた例

次の2枚の画像は、AI エージェントに Hunk を操作させる際の画面です。人間が確認する通常の diff 画面とは別に、エージェントは「hunk session」と「skill」を活用して Hunk セッションを読み解きます。

エージェントがセッション構造を読み取る。

通常は --repo . を指定することで、現在のリポジトリに紐づくセッションを簡単に選べます。ただし、同じリポジトリ内に複数の Hunk セッションが開かれている場合は、hunk session list で session id を確認した上で、hunk session review <session-id> --json のように ID を明示して指定する必要があります。

imagehunk session review session-id --json の例

エージェントに Hunk の扱い方を指示する。

hunk skill path で表示される SKILL.md ファイルのパスをエージェントに読ませることで、Hunk セッションの見方やコメントの書き方といったルールを伝えることができます。

imagehunk skill path の例

• エージェントが変更を継続中なら、自動更新モードで確認する。

hunk diff --watch

この段階における Hunk は、見やすい diff ビューワーとして機能します。サイドバーから複数ファイルの変更を追跡し、hunk ごとに内容を読み込みながら、AI が修正した範囲を確実に確認できます。

AI エージェントにも Hunk セッションを扱わせる場合は、以下のように指示を出してください。

Load the Hunk skill and use it for this review.
Run `hunk skill path` to get the skill path.

人間は Hunk の TUI（ターミナルユーザーインターフェース）画面を確認します。一方、エージェントは hunk session list で対象のセッションを見つけ出し、hunk session review <session-id> --json を実行して差分構造を読み取ります。必要に応じて、hunk session navigate --repo . --file src/App.tsx --hunk 2 のように該当する hunk に移動したり、hunk session comment add --repo . --file README.md --new-line 103 --summary "Tighten this wording" のようにライブコメントを残したりします。

エージェントがコメントを残す。

hunk session comment add コマンドを使用すると、hunk の近くにライブなインラインレビューノートが表示されます。これにより、説明と差分を同じ画面で同時に確認することが可能です。

imageHunk セッションに live inline review note を追加した例

役割を明確に分けることで、運用がスムーズになります。

必ず JSON 形式で返してください。translation フィールドのみを含め、他のフィールドは一切追加しないこと。余計なフィールドを追加しようとして本文がトークン上限で打ち切られる事故を防ぐためです：

{"translation": "リライト全文"}

リライト全文

• 必要に応じて、hunk session navigate --repo . --file src/App.tsx --hunk 2 のようにコマンドを実行し、画面を該当する hunk に移動させます。
• hunk session comment add --repo . --README.md --new-line 103 --summary "Tighten this wording" でライブコメントを残せます。複数のコメントをまとめて JSON 形式で標準入力から渡す場合は、hunk session comment apply --repo . --stdin を利用します。

チャットベースのレビューでは、エージェントは「src/App.tsx のこのあたりが問題です」と説明するにとどまります。読者はその説明を手掛かりに該当箇所を探す必要があります。しかし Hunk を使えば、エージェント自身が該当 hunk に移動し、直接コメントを残すことができます。これにより、説明とレビュー対象の距離を縮められます。

imageHunk ライブセッションのワークフロー図解

3. 差分の構造だけを先に読める

AI エージェントに巨大な diff を丸ごと読ませると、コンテキスト容量をすぐに使い果たしてしまいます。リスクの低い変更も混在するため、本当に見るべき場所がぼやけてしまうのです。

Hunk のワークフローでは、まず構造だけを読み込ませます。

hunk session review コマンドに --repo . --json または <session-id> を指定して実行すると、読み込まれたファイルと hunk の構造情報が JSON 形式で返されます。ただし、デフォルトでは生の unified diff は含まれません。必要な箇所だけを絞り込んでパッチを確認したい場合は、--include-patch オプションを付与してください。

この順序は LLM にとっても扱いやすい設計です。まず全文を読む前に構造を把握し、どのファイルにいくつの hunk が存在するかを確認してから、必要な場所だけを読み込むことができます。これは人間のレビュープロセスにも、エージェントのコンテキスト管理にも適した運用設計と言えます。

必ず JSON 形式で返してください。出力には translation フィールドのみを含め、他のフィールドは一切追加しないでください。余計なフィールドを記述しようとして本文がトークン上限に達し、出力が途中で打ち切られる事故を防ぐためです。

今回の調査では、この効果を直接測定したベンチマークは見つかりませんでした。ただし、bundled の hunk-review skill には、「まずファイルや hunk の構造を確認し、生（raw）の diff は必要な場合のみ参照する」という方針が明記されています。

github.com

image巨大な diff を扱う際、全文を眺める前に構造から把握する重要性を示す図解

Hunk ではコメントを差分の近くに配置する

AI エージェントの提案は、チャット画面に表示されるため、実際のコードから離れてしまうことがあります。

必ず JSON 形式で返してください。出力するのは translation フィールドのみです。他のフィールドは一切追加しないでください。余計な情報を付け加えようとして本文がトークン上限に達し、途中で切れる事故を防ぐためです。

「この変更は、入力データの正規化を目的としたものです」

AI エージェントによるコード変更をどう受け取るか。Hunk を活用して差分レビューを整える（続き 6/10） (retry d1 3/3)

そう書かれていても、どの行に該当するのか、あるいはどの hunk にリスクがあるのかを特定する必要があります。説明と diff の距離が離れれば離れるほど、レビュー作業は面倒になります。

Hunk は、インライン AI やエージェント注釈を主要機能として掲げています。これにより、説明やレビューコメントを、該当するコード差分のすぐ近くに配置することが可能になります。

同梱された hunk-review skill も、コメントの対象を「意図（intent）」「構造（structure）」「リスク（risks）」「フォローアップ（follow-ups）」に絞るよう案内しています。エージェントがすべての hunk にコメントする必要はありません。人間が見落としやすい判断材料を差分の横に置くだけで十分です。

操作画面では、ライブなインラインレビューノートが対象となる hunk の直上に表示されます。チャット内に説明を置くのではなく、確認する行の近くに判断材料を配置する形です。

エージェントにはレビュー補助を任せ、最終的な判断は人間が行います。

image説明をチャットから対象 hunk の近くへ移す図解

変更のやり直しを同じ画面で追う

AI エージェントとの開発では、一発で完了することは少ないものです。

生成して確認し、テストして修正する。そして再度確認する。

hunk diff --watch は、作業ツリーの変更を追跡するウォッチモードとして、レビュー画面を開く際に使用します。すでに開いているライブセッションをエージェント側から更新する場合は、hunk session reload --repo . -- diff のようにリロードを行います。

レビュー画面を開いたまま、エージェントによる編集を追跡できます。エージェントも必要に応じてセッションをリロードし、次に見るべき hunk へ案内することができます。

AI が裏で編集を行い、人間が横で監督する。この形こそが Hunk に合っています。

image変更のやり直しを同じ画面で追う図解

エージェント向けの使い方が用意されている

Hunk は CLI だけでなく、エージェントが読み込むための同梱されたレビュースキルも提供しています。README では、hunk skill path が返すスキルファイルをエージェントに読ませる流れを案内しています。

このスキルは、エージェントの操作を具体化します。

• エージェントがインタラクティブな hunk diff や hunk show を直接起動することはありません
• ユーザーが Hunk TUI を起動します

• エージェントは hunk session * commands を使って、ライブセッションの検査・ナビゲーション・リロード・コメント付けを行います
• raw patch は必要な時だけ読みます
• すべての hunk にコメントするのではなく、人間が見落としがちな点に絞り込みます

AI エージェントには優れた道具があっても、正しく使えるとは限りません。TUI を起動して詰まったり、diff の全文を読み込んでコンテキストを無駄に使ったり、重要でない箇所にコメントを量産したりするからです。Hunk は「skill」によってエージェントの振る舞いをレビュー用途に最適化します。

imageHunk の review skill がエージェントの振る舞いをレビュー用途に絞る図解

実務ではこう使う

AI エージェントによる変更を受け取る際は、以下の手順で確認を進めると、観点が揃いやすくなります。

1. まず変更の広がりを見る

最初から細部を読み込むのではなく、hunk diff で変更されたファイルの一覧を確認します。

注目すべきは次の 3 点です。

• 変更ファイル数が想定より多くないか
• 触ってほしくない領域に変更が入っていないか
• 新規ファイルや削除ファイルが混ざっていないか

違和感があれば、細部を見る前にエージェントへ戻ります。

2. エージェントに見るべき hunk を絞らせる

次に、エージェントに Hunk skill を読ませ、ライブセッションをレビューさせます。指示は「全体の説明」よりも、「見てほしい観点」に寄せるようにします。

この Hunk セッションを見て、レビュー優先度が高い hunk を 3 つ選んでください。

理由は security（セキュリティ）/ data loss（データ損失）/ behavior change（挙動変化）/ maintainability（保守性）の観点で短くコメントしてください。

この指示なら、エージェントはすべての hunk に薄いコメントを付けるのではなく、人間が確認すべき箇所を絞り込みやすくなります。

3. コメントを読んだうえで人間が判断する

エージェントのコメントは便利ですが、それ自体が判断ではありません。コメントが付いた hunk では、次を確認します。

• エージェントの説明と diff が一致しているか
• 変更前の挙動を壊していないか
• 例外処理、境界値、権限、永続化への影響がないか
• テストで確認できる変更か

Hunk は確認場所を見つけるための道具です。承認の根拠は、コード、テスト、仕様、実行結果に置きます。

4. 修正後も同じ画面で確認する

エージェントに修正させた後、人間が開いている画面が hunk diff --watch の場合は watch モードで追跡できます。すでに開いているライブセッションを明示的に更新したい場合は、次のようにリロードします。

hunk session reload --repo . -- diff

レビューの文脈は捨てないでください。前の指摘が直ったか、別の hunk に副作用が出ていないかをチェックします。同じ画面で追うと、チャットログだけで追うよりも確認の流れを保ちやすくなります。

Hunk だけでは確認できないこと

注意

Hunk はレビュー面を整えるための道具です。判断責任は人間側に残ります。

Hunk 単体では、以下の点を保証するものではありません。

• 変更が仕様を満たしていること
• テストが十分であること
• 実行時の挙動が正しいこと
• 設計として長期的に妥当であること
• CI やポリシー適用を通過すること
• セマンティックな正しさが検証済みであること

また、Hunk のライブセッションワークフローは、手元で開いている Hunk と AI エージェントが同じ PC 内で通信できることを前提としています。そのため、エージェントがクラウド上で動作している場合や Docker コンテナ内、あるいはローカル通信が制限されたサンドボックス環境にある場合は、hunk session list を実行しても開いている Hunk セッションが見つからないことがあります。この点は、Hunk のエージェントワークフロードキュメントでもトラブルシューティングとして説明されています。

github.com

README の機能比較 は参考にはなりますが、独立したベンチマーク結果ではありません。レビュー時間の短縮や欠陥削減についても、今回の調査では公開された定量データを確認していません。

github.com

ここで明確にしておきたいのは、Hunk が支える範囲です。Hunk はレビュー画面を整備しますが、変更そのものの正しさを保証するものではありません。

この記事で研究を参照しているのも、Hunk の効果を証明するためではありません。むしろ、Hunk への過度な期待を戒めるためです。Hunk が解決するのは「AI が正しいコードを書いたか」ではなく、「AI が出した変更を人間が確認できる形に戻せるか」という点にあります。

この切り分けは、最近のコードレビュー研究とも合致します。Rethinking Code Review in the Age of AI では、AI によるコード生成が高速化するほどレビュー側が詰まりやすくなるという課題を論じ、専門エージェントを活用しつつ人間が品質ゲートを担う流れを提案しています。

arxiv.org

ここでは実証結果そのものよりも、AI 時代のレビュー設計を考えるための視点として参照しています。

さらに、How AI Coding Agents Modify Code では、AI コーディングエージェントによる PR と人間の PR を比較すると、コミット数や変更対象ファイル数などに違いがあることが報告されています。

arxiv.org

少なくとも、この論文で分析されたオープンソースプロジェクトの統合プルリクエスト（PR）データを見ると、AI による変更を「いつもの人間の PR」と同じ感覚で眺めれば十分だとは限りません。だからこそ、複数ファイルにわたる差分を一覧表示し、hunk 単位で確認でき、必要な箇所にコメントを残せる機能が大きな強みとなります。

まとめ：Hunk は AI の変更を受け取る場所になる

Hunk と AI エージェントの相性が良い理由は、AI が生成したコードを人間が検査する点にあります。

この記事で押さえておきたいポイントは以下の通りです。

• AI エージェントの成果物は差分（diff）として現れる
• 人間の確認作業は hunk 単位で行われやすい
• Hunk はその差分をレビューファーストな UI に落とし込み、hunk diff や hunk diff --watch コマンドで人間が追跡可能にする
• インライン注釈（annotation）により、説明がコードから離れない
• hunk セッション機能により、エージェントが人間が見ているレビュー画面を操作できる
• review --json により、エージェントは構造化されたデータから段階的に内容を把握できる
• watch や reload 機能により、反復的な編集にも追従可能
• bundled skill により、エージェントの操作プロトコルまで明文化されている

Hunk は、AI エージェントが作成した変更を人間が確認するための作業環境を整えるツールです。

AI コーディングにおいて難しいのは、コードを書かせることよりも、信頼できる形で受け取ることです。

私は、AI エージェントを導入するなら、生成速度よりも先に「受け取りの作法」を整えるべきだと考えます。速く書ける環境であればあるほど、差分を読む場所、指摘を残す場所、そして最終判断を下す人を明確に決めておく必要があります。

Hunk は、その受け取り方を「diff」「hunk」「comment」「session」という単位に分解して整理します。AI に任せる範囲を広げるほど、人間が引き受ける確認の形も事前に決めておくべきです。そのための小さな足場として、Hunk はまさに最適な位置にあります。

エンジニアを募集しています！

ここまでお読みいただきありがとうございました！

Algomatic では、「AI 革命で人々を幸せにする」をミッションに、変化の激しい領域でも学びや試行錯誤を続けられるエンジニアを募集しています。

もし少しでもご興味をお持ちいただけましたら、カジュアル面談にご参加いただければ幸いです！