AI にコードを書いてもらう量が増えてから、書く時間より読む時間のほうが長くなりました。
できあがった差分を git diff やエディターのgit変更箇所で上から眺めても、ファイルはパスの順に並んでいるだけなので、処理の流れを追うのは大変です。AI に説明させると今度は長文になって、読むのに時間がかかる。これを何度か繰り返したあとで、「読む側の道具が無いだけだな」と思い、自分用に作ったのがこの記事のツールです。
差分を 処理の流れの順に、1 ステップずつ 読むためのローカルの画面です。説明を書くのは AI(Claude Code か Codex)で、読むのは人。ツール自体は自分の読み方に寄せて作ったものなので配っていませんが、どんなものを作ったかだけ紹介します。
画像は、AI に作らせたダミーの掲示板(スレッドに書き込むと、新着をチャットに通知する機能)を読んだときの画面です。
困っていたこと
- diff はファイルの並び順で出る。処理の順番で読みたいのに、ファイルを行ったり来たりすることになる
- AI の説明が長い。大事な所がほかの説明に埋もれる
- 別の案件に移って戻ってくると、どこまで読んだか、何の変更だったかを思い出す所から始まる
どれも「書く側」の問題ではなく「読む側」の問題でした。
作ったもの
まず、読む所を選り分ける
開くと、変更が 必読 / 確認 / 機械に任せる の 3 列に分かれて出ます。印は AI が変更の中身で付けますが、理由を見て納得できなければ自分で付け替えられます。
※画像はサンプルデータで作成したものです
必読は、外部への送信・DB への書き込み・失敗したときの戻り先の判断。確認はルート定義や入力の検証。機械に任せるはテストや表示だけの画面などです。「次へ」は既定で必読だけを渡るので、この例だと 12 ステップのうち 5 ステップを読めば終わります。
1 ステップずつ、コードの行に説明が付く
読む画面はコードが主役で、説明は行の頭の印を押すとその行の下に開きます。分岐の行と、設計書とずれている行は最初から開いています。
設計書と照らした結果も行に付きます。一致した行には一致の印、設計書に無い処理には「資料に無い追加」の印が付くので、読みながら「ここは設計どおりになっているか」を目印で確かめられます。ずれている所は、設計書が古いのか実装が違うのかをその場で人が判断します。
外部に送る項目を 1 つずつ照合する
通知 API など外部へ送るステップには、送る項目の照合表が付きます。資料の値・実装で送る値・判定(一致 / 違いあり / 送っていない / 資料に無い / 環境の値)が並び、コード側の行にも札が出ます。
実装の値は AI の推測ではなく、テストで実際に送った中身を取って書く決まりにしています。ここを推測で書かれると照合の意味が無いので。
「見た」が残る
「見た → 次へ」を押すと、いま読んでいるステップに「見た」の印が付きます。見出しの「このファイルを見た」を押すと、ファイル単位でも印が付きます。右の一覧では、見たファイルが薄く表示されます。
同じ内容が Markdown のチェックリストにも書き出されるので、ブラウザを閉じても VS Code で進み具合が分かります。別の案件に行って戻ってきても、続きから読めます。
分からない行は、その場で AI に聞ける
読んでいて引っかかった行をドラッグして選ぶと「AI に聞く」が出ます。質問を書いて送ると、答えが同じ行の下に、ほかの注記と同じ吹き出しで出ます。
答えるのは、その説明書を書いた AI のセッションです。コードを会話に貼り直して聞く往復が無くなりました。質問と答えはファイルに残るので、あとから見返せます。すぐ聞くほどではない所には「気になる」の印を付けておいて、あとでまとめて AI に渡すこともできます。
作ってみて思ったこと
一番効いたのは、画面そのものより「必読を絞る」ことでした。全部を同じ重さで読まなくていい、と最初に決めてもらえるだけで、読むのが楽になります。
Anthropic の Claude Code チームも、変更の危なさに合わせて人が見る所を絞っているそうです。
見たい範囲だけを読めるのも、使ってみて分かった利点です。大きい機能はコミットを分けたり、git worktree でブランチを分けて作ることが多いのですが、そのときも「このブランチの分だけ」「このコミットより後だけ」を説明書にできます。全部をまとめて読まなくていいので、分けて作った意味がそのまま読む側にも効きます。
もう 1 つは、機械で止められる所は機械で止めること。AI の説明を差分と照らして、漏れや必読の付け忘れがあれば画面が出ないようにしました。中身が合っているかは、人が読みます。
あとは、読む資料を人が先に決めること。AI に「設計書と照合して」と言うだけだと、どの資料を正とするかが毎回ぶれました。機能ごとに読む資料の一覧を表で置くようにしてから、照合が安定しました。
おわりに
AI に書かせる量が増えるほど、読む側にも道具が要ると感じています。全部を読まない、危ない所は機械に拾わせる、読んだ跡を残す。この 3 つを 1 つの画面にしました。
参考
- How the Claude Code team does code review(claude.dev Blog)：Anthropic の Claude Code チームのコードレビューの進め方。変更の危なさに合わせて、人が見る量を変えている
- 人間がコードを読まずにPRをマージする技術 ─ それでも、品質は手放さない(Zenn、karamage さん)：上の Anthropic の記事を紹介しながら、読む仕事を機械に任せて、人は危ない所と作るべきかの判断に集中する進め方をまとめた記事