UX / UI のデザインに強いWebシステムの開発と、BtoB Webマーケを支援するWeb制作を提供するN’s Creates (エヌズクリエイツ) 株式会社の西田です。

前回の記事では、Claude Codeで書いたコードをCodexにレビューさせる方法を書きました。その最後に予告したとおり、今回はもうひとつ日常的にやっていることを書きます。レビューに出す前に、Claude Codeに処理のフローをHTMLで図解させて、仕様と突き合わせることです。

全体の流れは、次のようになっています。今回書くのは、青枠で囲んだ3つのステップ（別セッションでの図解、仕様との突き合わせ、重点箇所を自分で読む）です。

差分を読むより、図のほうが全体をつかみやすい

AIに修正を頼むと、変更が複数のファイルにまたがることがよくあります。差分はファイルごとに分かれて表示されるので、処理全体がどうつながっているかは、頭の中で組み立て直さないと見えてきません。変更が大きくなるほど、これが難しくなります。

AIが書いたコードでも、レビューに出した時点でそれは自分のコードです。中身を理解したうえで出したい。そのために、まず処理の全体を図で見ることにしました。図にすると、処理のつながりが一目で分かり、どこを重点的に確かめるべきかも見えてきます。

図にすると、何が見えるのか

差分を上から順に読んでいくと、どうしても「この行は正しいか」という局所的な確認になります。一方で、仕様とのズレは、もっと大きな単位で起きていることが多いんです。

処理のフローを図にすると、次のようなことが一目で分かります。

・どこで分岐しているか、分岐の条件は何か
・失敗したとき、どこへ進むのか
・外部APIやDBを、どの順番で呼んでいるか

言葉だけだとイメージしにくいので、例で説明します（説明用に単純化した架空の例です）。ECサイトの「注文確定」の処理をAIに修正してもらい、差分が5ファイル・300行ほどになったとします。仕様は次のとおりです。

・カートが空なら、エラーを返す
・在庫が足りなければ、注文は作らずにエラーを返す
・決済（カードの利用枠を確保する「与信」）に失敗したら、注文を「決済失敗」として保存し、カードの再入力画面へ案内する。引当てた在庫（注文のために確保しておいた在庫）は解放する
・確認メールの送信に失敗しても、注文は成功扱いにして、再送キューに積む

この変更を、別セッションのClaude Codeにコードから図解させると、たとえばこんな図が出てきます。

300行の差分を読む前に、処理の全体像をつかめます。図によれば、決済APIでの与信に失敗するとリトライしていて、それでも失敗すると500エラーになります。メール送信に失敗したときの行き先は描かれていません。図中の青い番号1〜4は、このあと仕様と突き合わせたときに引っかかった箇所です。

ただし、この図はコードが正しいことの証明ではありません。図を描くのもAIなので、あくまで「どこを確かめるべきか」を見つけるための入口として使っています。この点は、後の節で詳しく書きます。

どう頼んでいるか

頼むときに入れている要素は、次の5つです。

1. 実装したセッションとは別のセッションで、コードから描かせる

前回の記事で書いたとおり、実装したセッションのAIは「何を作ろうとしていたか」という前提を持っています。そのまま図を描かせると、実際のコードではなく「作ろうとしていた処理」を描いてしまうおそれがあります。

図1の例でいえば、実装したセッションは「決済失敗時は『決済失敗』で保存する」という仕様を知っています。そのセッションに描かせると、コードがそうなっていなくても、図には「決済失敗で保存」と描いてしまうかもしれません。それでは、いちばん見つけたいズレが図から消えてしまいます。

確かめたいのは、意図ではなく、コードが実際にどう動くかです。なので、新しいセッションでコードを読ませて、そこから図を起こさせています。

2. 正常系だけでなく、エラーの経路も必ず描かせる

何も言わないと、正常系の流れだけを描いた図が出てきがちです。図1でいえば、真ん中の縦一列だけが描かれて、右側の赤い経路がまるごと省かれたような図です。でも、見落としが起きやすいのはエラーのときの経路のほうです。図1で引っかかった箇所も、4つとも失敗したときの挙動に関わるものでした。分岐とエラー時の行き先は、必ず描くように指定しています。

3. 図の各ステップに、ファイル名と行番号を書かせる

特に効果を感じているのがこれです。図1の「決済APIで与信を取る　payment.ts:88」のように、各ステップの下に場所が書いてあれば、図で引っかかったところからすぐにコードの該当箇所へ飛べます。図とコードをつなぐ目印がないと、図はただの「それらしい絵」で終わってしまいます。

4. 1ファイルのHTMLにする

HTMLにしているのは、ブラウザで開くだけで見られて、特別なツールがいらないからです。図1のように正常系とエラー経路を色分けしたり、外部APIやDBの呼び出しを枠の形で区別したり、各ステップに補足を書き添えたりと、見せ方の自由度も高いです。

5. 分からないところは、推測で埋めずに「不明」と書かせる

AIは分からないところを、もっともらしく埋めてしまうことがあります。図1の右側にある灰色の「このとき引当てた在庫の解放：不明」がそれです。もしこれが「在庫を解放する」ともっともらしく描かれていたら、自分は安心してそこを読み飛ばしていたと思います。

ここでの「不明」は、解放処理が存在しないという意味ではなく、図を描いたAIがコードから解放処理を見つけられなかった、という意味です。「不明」が残っていれば、そこが自分で確かめるべき場所だと図が教えてくれます。

実際の依頼文

5つをまとめると、実際の頼み方はたとえばこんな形です。1は依頼文ではなく、新しいセッションで頼むことで満たしています。

mainとの差分を踏まえて、注文確定処理（checkout.ts から呼ばれる範囲）全体のフローを図解したHTMLを1ファイルで作ってください。

- 意図ではなく、実際のコードから読み取れる処理を描いてください
- 分岐の条件と、エラー時・例外時の行き先を必ず描いてください
- 外部APIやDBの呼び出しは、ほかの処理と見た目で区別してください
- 各ステップに、対応するファイル名と行番号を書いてください
- コードから読み取れなかった部分は、推測で埋めずに「不明」と書いてください

図と仕様を突き合わせる

図ができたら、仕様と並べて見ます。見ているのは主に次の3点です。

・仕様に書かれている条件が、すべて分岐として図にあるか
・エラーのときの行き先が、仕様と同じか
・仕様にない処理が、図に紛れ込んでいないか

図1を仕様と並べると、次のようになります。番号は図1の青い番号と対応しています。

番号	仕様	図に描かれた処理	気づいたこと
1	仕様に記載なし	決済APIの呼び出しが失敗したら、最大3回呼び直す	仕様にない処理。タイムアウトのように結果が分からない失敗でも呼び直しているなら、1回目が実は通っていて、利用枠が二重に確保されるおそれがある（売上確定まで進めば二重請求）
2	注文を「決済失敗」で保存し、カード再入力画面へ	例外を投げて500エラー	行き先が違う。ユーザーにはシステムエラー画面が出てしまう
3	メール送信に失敗しても注文は成功扱い、再送キューへ	失敗時の分岐がない	分岐がない。メールが送れないと、注文は保存済みなのにエラーが返るかもしれない。ユーザーが再送すれば二重注文になりうる。逆に例外を握りつぶしていれば、メールが黙って失われる
4	決済失敗時は、引当てた在庫を解放する	不明	図では判断できない。自分でコードを読んで確かめる

3のように、仕様にあるはずの処理が「ない」ことは、300行の差分を読んでいても見落としがちです。図にすると、本来あるはずの矢印が「ない」ことが見えます。

1は、AIが気を利かせて足した処理かもしれません。リトライは一見親切ですが、決済APIを呼び直すなら、同じ注文には同じキーを付けて送り、決済側で重複を1回分として扱わせる仕組み（冪等性キー）が必要です。仕様にはその検討がありません。図のとおりにリトライが入っているなら、まずそこをコードで確かめる必要があります。

図は「正しさの証明」ではなく「地図」

ここは誤解されたくないところです。図を描くのもAIなので、図とコードが食い違っている可能性はあります。図を見て「問題なさそう」と判断して終わり、ではありません。

自分は図を、「どこを重点的に読むかを決める地図」として使っています。図で処理全体を見渡せるので、仕様とのズレや、間違えたときの影響が大きい箇所を踏まえて、どこから確かめるかの優先順位をつけられます。

・仕様と突き合わせて引っかかった箇所（図1の1〜3）
・仕様上いちばん大事な処理（図1なら決済まわり）
・お金や個人情報など、間違えたときの影響が大きい処理
・図に「不明」と書かれた箇所（図1の4）

こうした箇所は、図に書かれた行番号からコードを開いて、自分の目で確かめます。図1の例なら、payment.ts の88〜102行目あたり、mailer.ts の送信まわり、在庫の引当て・解放まわりを重点的に読むことになります。図で全体をつかんでから、どこを重点的に読むかを決めている、という感覚です。

逆に、図では分からないこともあります。細かい計算の正しさや、性能、セキュリティの問題は、フローの図にはまず現れません。たとえば図1で「引当てできた？」という分岐があることは分かっても、引当てる数の計算そのものが正しいかまでは分かりません。そこは前回書いたCodexのレビューや、テストで確かめます。

おわりに

AIが書くコードの量が増えて、差分を上から順に読むだけでは、処理の全体像をつかみにくくなってきました。

AIが書いたコードでも、レビューに出す以上は自分で理解しておく必要があります。だからこそ、まず全体を図で把握して、仕様と突き合わせて、大事なところは自分の目で確かめる。図は地図であって、正しさの証明ではありません。AI前提の開発現場で、レビューに出す人間の責任の果たし方は、こういう形に変わってきていると感じています。

N’s Createsでは、こうしたAIとの付き合い方をチームで日常的に共有しています。こういう開発の進め方に興味があれば、採用情報ものぞいてみてください。