【ITニュース解説】My AI agent copy-pasted SEO tags across 20 files instead of generating them

この記事は、AIエージェントを使ってウェブサイトを開発する際に直面した具体的な問題と、そこから得られた重要な教訓について解説している。システムエンジニアを目指す上で、AIツールを効果的に活用し、同時にその限界を理解することは非常に重要だ。

筆者は、北キプロスの物件リスティングサイトを開発していた。このサイトは、HTML、CSS、JavaScriptのみで構成され、余分なライブラリに頼らないシンプルな作りが特徴だ。Cloudflare Pagesというサービスを利用して公開されており、英語、ロシア語、トルコ語、ポーランド語の4つの言語に対応している。これにより、合計で20個の異なるHTMLファイルが存在する複雑な多言語サイトとなっていた。開発にはAIコーディングエージェントであるClaude Codeを活用していた。

最初の大きな問題は、ウェブサイトのSEO（検索エンジン最適化）情報、具体的にはページのタイトルや検索エンジンに表示される説明文が、AIエージェントによって各HTMLファイルに直接、手作業で書き込まれていたことだ。これは、例えばサイトのタイトルを変更しようとしたときに、20個すべてのファイルを手動で修正しなければならないという手間を生む。その結果、一部のファイルの修正が漏れたり、言語によって内容に微妙なズレ（「drift」と表現されている）が生じたりする可能性があった。筆者は多言語サイトの品質に強いこだわりがあったため、このズレを見つけられたが、AIエージェント自体はこの問題をエラーとして認識しなかった。この状況は「シングルソースオブトゥルース（Single Source of Truth）」の欠如を意味する。データが複数の場所に重複して存在すると、どれが正しい情報なのか分からなくなり、管理が非常に困難になるのだ。AIエージェントは、作業環境に用意されていた「データは一元管理すべき」といった筆者の求める開発指針を、明示的に指示しない限り適用しなかった点も注目に値する。

この問題を解決するため、筆者は既存の汎用的なテンプレートエンジン（HugoやEleventyのようなツール）を使うのではなく、独自の小さなプログラムを開発した。汎用的なテンプレートエンジンは、サイト全体の構造を作り変える必要があるため、SEO情報という一部の問題を解決するためだけに導入するのは大掛かりすぎると判断したからだ。筆者の開発したプログラムは、build/seo-data.jsというファイルにすべてのページのSEO情報を一元的に集約し、build/generate-seo.jsという別のプログラムが、このデータを読み込んで各HTMLファイルの指定された箇所に自動で埋め込む仕組みだ。これにより、SEO情報の変更はseo-data.jsという一箇所を修正するだけでよくなり、多言語サイトにおける情報のズレは構造的に解消された。HTMLファイル自体は手書きのままで、プログラムの知識がなくても編集できる柔軟性も維持されている。また、このプログラムには--checkという検証機能が備わっており、実際にファイルを書き換えることなく、SEO情報が最新の状態であるかを確認できるようになった。

しかし、この解決策には、さらに別の問題が潜んでいた。筆者が新しい言語（ドイツ語）をサイトに追加するテストを行った際に、この問題が明らかになった。言語リストに「de」というドイツ語のコードを追加したものの、ドイツ語に対応するページのパスやラベル情報が不足していたにもかかわらず、ジェネレータープログラムはエラーを発生させずに動作してしまったのだ。結果として、ジェネレーターは存在しないURLを指す壊れたリンク（href="https://girne-apartment-sale.comundefined"のような形）を、既存の20ページすべてに書き込んでしまった。そして、先の--check機能は「out of date」（更新が必要）と報告した。これは、開発者が意図的にSEO情報を修正し、まだプログラムを再実行していない場合と同じメッセージだったのだ。つまり、--check機能は「開発者が意図的に変更した」場合と「ツールがサイトを破損させた」場合を区別できなかった。これは検証（チェック）として不十分であり、単に「期待する状態と現在の状態に差がある」という「差分検出（diff）」に過ぎなかった。

この二つ目の問題の解決策として、筆者はデータを書き込む前に実行されるvalidateData()という検証処理を追加した。これにより、必要なデータが不足している場合は、プログラムがエラーを発生させ、具体的な不足情報を明示的に表示するようになった。

この記事から得られる教訓は、システムエンジニアを目指す皆さんにとって非常に価値がある。AIエージェントは、目に見える範囲、つまりユーザーが直接確認できるウェブサイトの表示などについては、非常に効率的に「動くもの」を生成できる。しかし、その裏側にあるデータ構造やコードの整合性といった「一つ下の層」に、問題が潜んでいることが多い。AIは、構造化を考えるよりも、単純なコピー＆ペーストで問題を解決しようとする傾向があるため、データやコードの重複を生み出しやすい。そして、この重複が、後になって情報のズレ（drift）という形で現れる。人間が手作業でコピー＆ペーストを繰り返すことで生じる問題と本質的には同じだが、AIはそれをはるかに高速に、そして広範囲のファイルにわたって実行するため、問題が急速に拡大する可能性がある。さらに厄介なのは、個々のファイルは見た目上問題がないように見えるため、問題が発見されにくいことだ。

AIツールは強力な味方だが、その出力は常に批判的な目で検証し、特にデータの整合性や構造的な問題については、人間が責任を持って確認する必要がある。単に「動く」だけではなく、「正しく」「保守しやすい」システムを構築するためには、AIの挙動を深く理解し、適切な検証プロセスを設計することが不可欠なのだ。