AI agent の PR は diff だけ見ても足りない

AI agent が作った PR で一番怖いのは、巨大な diff ではなく、妙にきれいな小さい diff だと思っています。

人間が書いた PR なら、「ここ、なんでこうしたんですか」と聞ける。返事が雑でも、少なくとも本人の頭の中に作業の文脈があります。

agent の PR は違います。説明文は自然に書ける。でも、その説明が本当に作業の流れを反映しているのかは別です。特に frontend repo では、diff が 20 行でも、CSS の当たり方、viewport、form state、route の境界、Playwright の失敗条件が絡みます。

なので agent PR の review は、最終 diff だけを読む作業ではなくなります。作業ログを読む作業になります。

review 対象を diff から work log に広げる

GitHub Copilot Chat が agent session を参照できるようになった話は、かなり象徴的です。agent の途中経過が、単なる裏側の実行ログではなく、review や follow-up の材料になっていく。

Claude Code や Codex のような tool も、terminal、browser、MCP、hooks、remote task など、作業面が広がっています。便利です。ただ、そのぶん PR の diff だけでは「何を確認したのか」が見えにくい。

最低限、reviewer が見たいのはこのあたりです。

• PR diff
• agent session log / chat context
• 実行した command
• 見た CI / test log
• browser preview / screenshot / Playwright の確認
• agent が確認していない範囲

ここで大事なのは、agent の説明を信じるためにログを見るのではない、ということです。疑う場所を減らすために見る。

「pnpm test を実行しました」なのか、「対象 test だけ実行しました」なのか。「mobile screenshot を見ました」なのか、「desktop の happy path だけ見ました」なのか。ここが混ざると、review は急にしんどくなります。

PR template に agent review note を入れる

まずは PR template に、小さい work log 欄を入れるのが手堅いです。

## Agent review note

- Task:
- Changed paths:
- Commands run:
- Logs inspected:
- Browser / screenshot checks:
- Tools used:
- External context touched:
- Not verified:
- Human review focus:

全部を埋められない PR は、それだけで review の入り口が決まります。情報がない場所を人間が見る。

たとえば SearchPanel の mobile layout 崩れを agent に直させたなら、こういう粒度で十分です。

## Agent review note

- Task: SearchPanel の mobile layout 崩れを修正
- Changed paths: `src/components/SearchPanel.tsx`, `src/components/SearchPanel.css`
- Commands run: `pnpm typecheck`, `pnpm test SearchPanel`
- Logs inspected: failed Playwright trace from `search-mobile.spec.ts`
- Browser / screenshot checks: local 390px viewport screenshot
- Tools used: terminal, browser preview, Playwright
- External context touched: none
- Not verified: Safari, production build, dark mode
- Human review focus: CSS selector scope and mobile overflow

この欄があるだけで、reviewer は最初に見る場所を選べます。

SearchPanel.css の selector が global に漏れていないか。390px だけでなく 768px ではどうか。dark mode を見ていないなら、色や border の変更を重点的に見る。そういう判断ができます。

frontend repo で特に見るところ

agent PR の review で、frontend は地味に難しいです。build が通っても画面が壊れるし、test が通っても CSS の影響範囲は見落とされます。

自分なら、まずこの 5 点を見ます。

CSS の変更が局所的か

CSS は小さい diff でも被害が広がります。

-.search-panel .button {
+button {
   width: 100%;
 }

こういう変更は、typecheck では絶対に止まりません。agent が「layout を修正しました」と書いていても、selector scope は人間が見た方がいい。

Tailwind でも同じです。class が 1 つ増えただけに見えて、responsive prefix や dark mode の条件が抜けることがあります。

state / validation が変わっていないか

UI 修正のつもりで、form state や validation の条件まで変わっている PR は要注意です。

// 見た目の disabled 修正のつもりが、submit 条件も変えている
const canSubmit = hasInput && !isLoading;

disabled の class を直すだけならいい。でも canSubmit の条件まで変わっているなら、review 対象は layout ではなく仕様変更になります。

route / loader / server component の境界をまたいでいないか

Next.js や Remix では、component の修正に見えて loader、server action、cache の境界を触っていることがあります。

agent が動くと、関連 file をまとめて直してくれることがあります。それ自体は助かる。ただ、境界をまたいだ時点で review の温度は上げた方がいいです。

screenshot は失敗しやすい viewport を見ているか

「browser で確認しました」は弱いです。

frontend の PR では、どの viewport を見たかを書いてほしい。

Browser / screenshot checks:
- 390x844: search panel open / keyboard hidden
- 768x1024: sidebar collapsed
- 1440x900: default desktop layout

全部の PR で 3 viewport 見る必要はありません。でも mobile bug を直したなら mobile screenshot はほしい。逆に desktop しか見ていないなら、Not verified に mobile を書くべきです。

test が「何を見ていないか」が書かれているか

pnpm test が通ったことより、何を test していないかの方が役に立つことがあります。

- Commands run: `pnpm test SearchPanel`, `pnpm typecheck`
- Not verified: production build, Safari, visual regression, real API response

この書き方なら、人間は補うべき確認をすぐ決められます。

session log は監査ログではない

agent session log をありがたがりすぎるのも危ないです。

ログがあるから正しい、ではない。agent は間違った仮説で file を読んでいるかもしれないし、失敗した command を見落としているかもしれない。途中で「たぶんここ」と判断して、必要な画面確認を飛ばしていることもあります。

それでも、ログは役に立ちます。

• どの file を読んだか
• どの command で失敗したか
• 何を再実行したか
• どの tool / MCP / hook を使ったか
• 外部 context に触ったか

この情報があると、reviewer は「全部を最初から読む」状態から抜けられます。

説明文のうまさではなく、作業の跡を見る。agent PR ではこれがかなり効きます。

小さい PR ほど template が効く

大きい agent PR は、まず分割した方がいいです。これは人間の PR と同じ。

ただ、小さい PR でも template は必要です。むしろ小さい PR の方が、「まあ大丈夫そう」に流れやすい。

## Agent review note

- Task: ProductCard の price 表示崩れを修正
- Changed paths: `src/components/ProductCard.tsx`
- Commands run: `pnpm test ProductCard`
- Browser / screenshot checks: none
- Not verified: currency locale, mobile layout, discounted price
- Human review focus: 表示条件と locale formatter

この PR は merge していいかもしれません。でも、screenshot がないなら UI は人間が見る。locale を見ていないなら formatter を見る。review の焦点がはっきりします。

逆に、これがないとこうなります。

ProductCard の表示崩れを修正しました。
テストは通っています。

これだけだと、reviewer は結局 diff を全部読むしかない。agent に任せたのに、人間側の認知負荷が減っていません。

repo 側に observability layer を作る

AI agent の PR review は、賢い agent を信じる話ではないです。

repo 側に、作業の跡を読みやすくする型を置く話です。

最初にやるなら、これくらいで十分だと思います。

1. PR template に Agent review note を足す
2. Commands run と Not verified を必須にする
3. frontend bug fix では viewport / screenshot 欄を用意する
4. MCP、hooks、external context に触ったら明記する
5. 大きい agent PR は分割してから review する

地味です。でも、この地味さが必要です。

agent が作った PR を diff だけで読むのは、CI log を見ずに flaky test を判断するのに近い。たまたま通ったのか、ちゃんと確認したのかが分からない。

これから agent workflow を repo に入れるなら、最初の observability layer は PR template でいいと思っています。立派な dashboard より先に、reviewer が「何を見ればいいか」を迷わない形にする。

それだけで、agent PR はかなり読みやすくなります。

Source notes

• GitHub Changelog: Copilot Chat now sees your agent sessions
• GitHub Copilot app: agent-native desktop experience
• OpenAI Codex remote workflow
• Claude Code docs