実装をAIに任せ、レビューもAIに任せたら、見た目のズレだけが残っていた

このブログのトップページを改修した。設計は Claude Code、実装は GPT-5.6、そしてレビューを設計と同じ Claude Code にやらせた。前に実装を丸ごとAIに任せたら、テストは通ったが画面は誰も見ていなかったという記録を書いたが、今回はその続きにあたる。前回の反省を計画書に全部入れて、レビュー工程まで足した上で、それでも何が残るかの記録だ。

きっかけ

トップページには直したい点が4つあった。サイト名の見出しが重複している、長いタイトルの記事で日付だけが折り返す、一覧が下線だらけでうるさい、記事間の余白が足りない。この程度の改修だが、前回と同じ「設計と実装を別のAIに分ける」形をもう一度やることにした。今回足したのは、実装の成果物を設計側のAIにレビューさせる工程だ。

最初に考えていたこと

前回の教訓は「受入条件の設計で結果が決まる」だった。だから設計メモにはかなり書き込んだ。

• 変更する値と変更しない値を全部列挙(色は HEX、余白は rem 単位まで)
• 受け入れ確認を6項目に明文化(h1が1つだけ、日付が折り返さない、下層ページが壊れていない、など)
• 実装AIにそのまま渡せるプロンプト。検証コマンドの実行方法(パイプで終了コードを潰さない)や「テストを弱めるのではなく新構造の検証に書き換える」まで指示
• 見た目の確認(ライト/ダーク、モバイル幅、hover、フォーカス)も完了条件に入れた

前回「テストの外にあるものは抜ける」と学んだので、テストの外の確認項目を人間の言葉で足したわけだ。これで穴は塞いだつもりでいた。

実際にやったこと・起きたこと

実装は数時間で返ってきた。報告は「全項目完了」。変更6ファイル、テストは17ファイル131件全部通過、ビルド37ページ成功、ブラウザでの見た目確認も済み。完了条件6項目すべてに「完了」が付いていた。

レビュー側のAIには、まず申告の検証をさせた。typecheck・テスト・ビルドを全部再実行し、生成されたHTMLの構造を機械的に確認する。結果を先に言うと、申告は全部本当だった。数字にも嘘はなく、手抜きもなかった。

それでも、指摘が1件だけ出た。「トップページだけ、ヘッダーのサイト名が下層ページより大きく表示される」。

原因はこうだ。設計メモには「トップページでのみサイト名を h1 にする」と書いてあった。これは検索エンジンと支援技術向けの意味論の変更で、見た目は変えないのが設計の意図だった。実装はその字面どおり h1 化した。ただ、h1 には既定の大きな文字サイズと余白が付いてくる。見た目を従来のヘッダーと揃えるCSSは、誰にも指示されていないので、書かれていなかった。

意地の悪いことに、このズレは完了条件の目視確認でも見つからない種類のものだった。トップページ単体で見れば、サイト名が少し大きいだけで破綻はない。ズレは「下層ページと見比べたとき」に初めて分かる。実装AIの「ブラウザ確認済み」も、その意味では嘘ではなかった。

修正はCSS6行。サイズと余白に加えて行の高さも揃えた(揃えないとヘッダーの高さが約8ピクセル変わる)。mainへのpush後、40秒以内に本番へ反映された。

原因を調べる

前回と同じで、実装したAIの落ち度とは考えていない。仕様の書き方の問題だ。

1. 仕様の字面と意図が分離していた。「h1 にする」は書いたが、「見た目は変えない」は書かなかった。意図はワイヤーフレームの図には表れていたが、受け入れ確認6項目には入っていなかった。明文化された条件だけを満たすのが実装の仕事なので、条件の外にある意図は落ちる
2. 一貫性の確認は、単ページの確認項目に分解できていなかった。「ライト/ダークを確認」「モバイル幅を確認」はページ単位の指示だ。「ページ間で同じに見えること」は比較の指示であり、書いていなければ誰も比較しない

分かったこと

事実: テスト131件は全部通り、完了申告6項目も全部本当だった。それでも、仕様の意図とのズレが1件残っていて、それを見つけたのは申告の再検証ではなく、設計をしたAIによる意図との突き合わせだった。

そこからの解釈:

• 申告の検証と、意図との突き合わせは、別の作業。 前者は「言ったとおりか」を確かめ、後者は「言うべきだったことまで含めて合っているか」を確かめる。今回、前者からは何も出なかった。レビューの価値は後者にあった
• レビューを設計者にやらせる意味はここにある。 仕様書に書き漏らした意図は、仕様書を読んでも分からない。書いた本人(今回は設計したAI)だけが、字面と意図の差分を知っている
• 「見た目を変えない」は、仕様に書くべき立派な要件。 変更点だけを仕様に書くと、変えないことが未定義になる。今回の設計メモにも「変更しないもの」の章はあったのに、ヘッダーの見た目はそこに入れ損ねていた

次からどうするか

• 意味論だけの変更(HTML構造の変更で見た目を保つもの)には、「見た目は変えない」を明文の受け入れ条件として付ける
• ページをまたぐ一貫性は「AとBを並べて比較する」という形の確認項目にする。単ページの確認をいくら並べても代わりにならない
• 実装の申告の再検証はレビューの前半として残す。今回は空振りだったが、空振りだと分かること自体に意味がある(申告を信じてよい実装者かが分かる)

同じことをする人へのポイント

• AIの実装レビューは「動くか」より「意図どおりか」を見させると仕事をする。仕様書と成果物だけ渡すより、設計の経緯を知っているAI(またはセッション)にレビューさせる方が、字面と意図の差分を拾える
• 「テストが通りました」「確認済みです」という申告は、再実行すれば検証できる。検証して本当だったとしても、それは仕様の意図まで保証しない。前回の「テストはテストの範囲しか保証しない」の一段上に、「仕様書は書いた範囲しか伝えない」がある
• 変更しないものを仕様に書く。変更点のリストだけでは、現状維持が未定義になる

前回の記事で「確認するまで正しさは分からない」と書いた。今回それをレビュー工程として仕組みにしたら、確認は仕組みで回るようになり、最後に残ったのは仕様に書き損ねた意図だった。穴は一段ずつ小さくなっている。この改修を経たトップページが、いま表示されているこのブログだ。

この記事は、運営者自身の実践記録に基づいています。