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

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

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

*Rethinking Code Review in the Age of AI* は、AI 時代のコードレビューを考える vision / framework paper として、レビューが手元での確認から Pull Request 中心のワークフローへ移り、AI coding assistant によってレビュー対象の量が増えているという問題設定を論じています。変わったのは、差分が生まれる速さと量です。

arxiv.org

AIエージェントに任せた変更も、最後は人間が差分として読みます。どのファイルが変わったのか。なぜその変更を入れたのか。危ない変更はどこか。説明とコードは合っているか。

チャット上の「できました」だけでは、まだ変更を受け取ったことになりません。変更箇所を見て、意図を読み、責任を持てる状態にして、はじめて受け取ったと言えます。

Hunk は、この受け取り方を整えるための terminal diff viewer です。README は、Hunk を “review-first terminal diff viewer for agent-authored changesets” と定義しています。この記事では、Claude Code、Codex、Copilot Agent などにコード変更を任せ始めた開発者に向けて、Hunk を使った差分の受け取り方を整理します。

github.com

この記事で扱うのは次の3つです。

• Hunk で AI エージェントの差分を見る最小手順

• 人間とエージェントでレビューの役割を分ける方法

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

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

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

最近の研究も、この見方と近い位置にあります。*Human oversight of agentic systems in practice* は、開発者がエージェントを使うときの監督作業を、事前制御、共同計画、実行中の観察、事後レビューに分けています。

arxiv.org

Hunk が主に支えるのは、変更後のレビューと、--watch や live session を通じて変わっていく diff を観察する作業です。エージェントの行動ログや推論過程そのものを監視する道具ではありません。

*Human-AI Synergy in Agentic Code Review* は、AI エージェントが defect screening を広げる一方で、人間は理解、テスト、知識共有のような文脈依存のフィードバックを多く担うと報告しています。

arxiv.org

ただし、AI の提案は人間の提案より採用率が低いとも報告されており、AIエージェントの提案をそのまま信頼できるわけではありません。だからこそ、人間が判断しやすい単位へ差分を戻す方が筋が通ります。

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

• まずはこの手順で試す

• HunkがAIエージェントと相性がいい理由 1. AIの作業はdiffとして残る

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

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

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

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

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

• 実務ではこう使う 1. まず変更の広がりを見る

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

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

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

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

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

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

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

たとえば、次のような場面です。

• 変更ファイルが多く、どこから見るべきか分からない

• エージェントの説明と diff を行き来する

• リスクのある hunk と整形差分が混ざる

• レビューコメントがチャット側に残り、コードから離れる

• エージェントが再編集するたびに、レビュー対象を追い直す

README は、multi-file review stream、inline AI/agent annotations、split / stack / auto layout、watch mode、keyboard / mouse / pager / Git difftool support を主要機能として挙げています。どの機能も、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 は、まだ commit していない working tree の変更を開きます。追加行と削除行を、hunk 単位で確認できます。

コミット済みの変更を見る。 hunk show HEAD は、最新コミットの変更を同じ UI で開きます。作業中の差分だけでなく、commit 後の確認にも使えます。

ここまでは、手元のリポジトリにある変更を見る例です。もうひとつ便利なのが、変更内容だけを受け取って確認する使い方です。

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

Hunk では、この patch ファイルも通常の差分画面として開けます。

hunk patch change.patch

git diff の出力など、ファイルに保存せずパイプで渡す場合だけ、標準入力の形を使います。

git diff --no-color | hunk patch -

patch を Hunk で見る。 画面上部の before.js → after.js が「どのファイルからどのファイルへの変更か」を示します。緑の行が追加された内容です。保存済みの patch はファイル名で渡し、パイプラインでは標準入力から渡せます。どちらも通常の diff と同じ見た目で確認できます。

次の2枚は、エージェントに Hunk を操作させるときの画面です。人間が見る diff 画面とは別に、エージェントは hunk session と skill を使って Hunk セッションを読みます。

エージェントがセッション構造を読む。 通常は --repo . で現在のリポジトリに紐づくセッションを指定できます。同じリポジトリの Hunk セッションが複数開いている場合は、hunk session list で session id を確認し、hunk session review <session-id> --json のように id で指定します。

エージェントに Hunk の扱い方を渡す。 hunk skill path で表示された SKILL.md のパスをエージェントに読ませると、Hunk セッションの見方やコメントの残し方を指示できます。

• エージェントが変更を続けるなら、自動更新で見る。

hunk diff --watch

この段階の Hunk は、見やすい diff viewer です。複数ファイルの変更をサイドバーで追い、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" のように live comment を残します。

エージェントがコメントを残す。 hunk session comment add を使うと、live inline review note が hunk の近くに表示されます。説明と差分を同じ画面で確認できます。

役割を分けると、扱いやすくなります。

エージェントにレビューを完了させる必要はありません。人間が見るべき hunk を絞らせます。

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

Hunk と AI エージェントの相性は、主に3つあります。

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

AI エージェントの返答はチャット上の文章に見えます。開発作業として見ると、成果物はリポジトリ上の変更です。

確認するべき対象は、エージェントの「できました」ではありません。実際に変わったコードです。

Hunk は hunk diff で working tree の変更を読み、hunk show で commit を読み、hunk patch change.patch で保存済み patch を読み、2ファイル比較もできます。Git の working tree、commit、patch、file diff という入口を、レビュー用 UI に載せます。

hunk は、変更を局所的に見るためのまとまりです。AI が変えた場所、人間が確認したい場所、コメントを付けたい場所が、hunk 単位でそろいます。

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

Hunk の agent workflow では、人間が Hunk TUI を開き、エージェントが hunk session ... コマンドで live session を操作します。

`docs/agent-workflows.md` は、推奨ワークフローとして次の形を示しています。

github.com

流れを図にすると、人間・Hunk・エージェントの役割分担が見えやすくなります。

• 人間が別ターミナルで hunk diff または hunk show を開く

• Hunk TUI が local loopback daemon に session を登録する

• エージェントが hunk session list で対象を確認し、hunk session review --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" で live comment を残す。複数コメントを JSON として標準入力からまとめて渡す場合は hunk session comment apply --repo . --stdin を使う

チャットだけのレビューでは、エージェントは「src/App.tsx のこのあたりが問題です」と説明します。読む側はそれを見て、該当箇所を探します。Hunk を使うと、エージェントが該当 hunk に移動し、そこにコメントを残せます。説明がレビュー対象から離れません。

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

AI エージェントに巨大な diff を丸ごと読ませると、コンテキストを使い切ります。リスクの低い変更も混ざり、見るべき場所がぼやけます。

Hunk の workflow は、先に構造を読ませます。

hunk session review --repo . --json または hunk session review <session-id> --json は、読み込まれた file / hunk structure を返します。raw unified diff はデフォルトでは含まれません。必要箇所を絞ってから patch を読むときに --include-patch を付けます。

LLM にとっても、この順序は扱いやすい可能性があります。全文を読む前に構造を見る。どのファイルに何個の hunk があるかを把握し、必要な場所だけ読む。人間のレビューにも、エージェントのコンテキスト管理にも合う運用設計です。

今回の調査では、この効果を測ったベンチマークを確認していません。ただ、bundled `hunk-review` skill も「file/hunk structure を先に見て、raw diff は必要なときだけ使う」と明示しています。

github.com

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

AI エージェントの説明は、チャットに置くとコードから離れます。

「この変更は入力正規化のためです」

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

Hunk は inline AI / agent annotations を主要機能として掲げています。説明やレビューコメントを、該当するコード差分の近くに置けます。

bundled `hunk-review` skill も、コメントの対象を intent、structure、risks、follow-ups に絞るよう案内しています。エージェントは全 hunk にコメントする必要はありません。人間が見落としやすい判断材料を差分の横に置けば十分です。

操作画面では、live inline review note が対象 hunk のすぐ上に表示されます。チャットに説明を置くのではなく、確認する行の近くに判断材料を置く形です。

エージェントにはレビュー補助を任せます。最終判断は人間が引き受けます。

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

AI エージェントとの開発は、一発で終わることの方が少ないです。

生成する。見る。テストする。直す。もう一度見る。

hunk diff --watch は、working tree の変更を追う watch mode としてレビュー画面を開くときに使います。すでに開いている live session をエージェント側から更新する場合は、hunk session reload --repo . -- diff のように reload します。

レビュー画面を開いたまま、エージェントの編集を追えます。エージェントも、必要に応じて session を reload し、次に見るべき hunk へ案内できます。

AI が裏で編集し、人間が横で監督する。この形に Hunk は合います。

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

Hunk は CLI だけでなく、エージェントに読ませるための bundled review skill も提供しています。README は、hunk skill path が返す skill file をエージェントに読ませる流れを案内しています。

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

• エージェントは interactive な hunk diff や hunk show を直接起動しない

• ユーザーが Hunk TUI を起動する

• エージェントは hunk session * commands で live session を inspect / navigate / reload / comment する

• raw patch は必要なときだけ読む

• 全 hunk にコメントせず、人間が見落としやすい点に絞る

AI エージェントは、道具があれば正しく使えるわけではありません。TUI を起動して詰まる。diff 全文を読んでコンテキストを使い切る。重要でない箇所にコメントを量産する。Hunk は skill によって、エージェントの振る舞いをレビュー用途に寄せます。

実務ではこう使う

AI エージェントの変更を受け取るときは、次の順番にすると確認の観点をそろえやすくなります。

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

最初から細部を読まず、hunk diff で変更ファイルの一覧を見ます。

見るのは次の3つです。

• 変更ファイル数が想定より多くないか

• 触ってほしくない領域に変更が入っていないか

• 新規ファイルや削除ファイルが混ざっていないか

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

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

次に、エージェントへ Hunk skill を読ませ、live session を review させます。頼む内容は「全体の説明」より、見てほしい観点に寄せます。

このHunkセッションを見て、レビュー優先度が高いhunkを3つ選んでください。
理由は security / data loss / behavior change / maintainability の観点で短くコメントしてください。

この指示なら、エージェントは全 hunk に薄いコメントを付けず、人間が見るべき箇所を絞らせやすくなります。

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

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

• エージェントの説明と diff が一致しているか

• 変更前の挙動を壊していないか

• 例外処理、境界値、権限、永続化への影響がないか

• テストで確認できる変更か

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

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

エージェントに修正させたら、人間が開いている画面が hunk diff --watch なら watch mode で追えます。すでに開いている live session を明示的に更新するなら、次のように reload します。

hunk session reload --repo . -- diff

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

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

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

Hunk 単体では、次のことは保証しません。

• 変更が仕様を満たしていること

• テストが十分であること

• 実行時挙動が正しいこと

• 設計として長期的に妥当であること

• CI や policy enforcement を通過すること

• semantic correctness が検証済みであること

また、Hunk の live session workflow は、手元で開いている Hunk と AI エージェントが同じPC内で通信できることを前提にしています。

そのため、たとえばエージェントがクラウド上で動いている場合や、Docker コンテナ内で動いている場合、あるいはローカル通信が制限された sandbox 内で動いている場合は、hunk session list を実行しても、開いている Hunk セッションが見つからないことがあります。これは Hunk の agent workflow docs でも troubleshootingとして説明されています。

github.com

README の feature comparison は、参考にはなりますが、独立ベンチマークではありません。レビュー時間短縮や defect reduction についても、今回の調査では公開された定量データを確認していません。

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 coding agent の PR と人間の PR では、コミット数や触るファイル数などに違いがあると報告しています。

arxiv.org

少なくとも同論文の merged OSS PR データでは、AI の変更は「いつもの人間の PR」と同じ感覚で眺めれば十分、とは限りません。だからこそ、複数ファイルの差分を一覧し、hunk 単位で確認し、必要な場所にコメントを残せる面が効いてきます。

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

Hunk と AI エージェントの相性は、AI が書いたコードを人間が検査する面にあります。

この記事で押さえておきたい点は、次のとおりです。

• AI エージェントの成果物は diff になる

• 人間の確認は hunk 単位になりやすい

• Hunk はその差分を review-first UI に載せ、hunk diff / hunk diff --watch で人間が追える形にする

• inline annotation により、説明がコードから離れない

• hunk session により、エージェントが人間の見ているレビュー画面を操作できる

• review --json により、エージェントは構造から段階的に読める

• watch / reload により、反復的な編集に追従できる

• bundled skill により、エージェントの操作プロトコルまで明文化されている

Hunk は、AI エージェントが作った変更を人間が確認するための作業面を整える道具です。

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

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

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

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

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

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

もし少しでもご興味をお持ちいただけましたら、カジュアル面談に足を運んでいただけるとうれしいです！