エージェントAIの「知ったかぶり」をどう防ぐか

CodexやClaude Code、Google Antigravityなど、爆速で開発を進められる AIエージェント （あるいは エージェントAI ）が流行っています。しかし、マイナーなライブラリや、ドキュメントの古いOSSを扱わせたとき、彼らは 「息を吐くように存在しないAPIを捏造する」 という罠があります。

実行してエラーが出るならまだマシです。一番怖いのは 「エラーは出ないが、内部でデータのマッピングがズレている」というサイレントバグ です。

この記事では、AIの嘘（ハルシネーション）を「ソースコード（一次情報）」で封じ込め、一発でパイプラインを貫通させた開発フローを共有します。

忙しい人のために：2026年での最強の分業フローはこれだ！

AIを「一人のプログラマー」として扱うのではなく、得意分野の異なる3つの役割に分割して運用します。

【思考】高推論モデル（Gemini Pro等） とアーキテクチャを壁打ちし、 制約（やってはいけないこと） を決める。
【調査】エージェントAI（CodexやClaude Code、Google Antigravityなど等。モデルは賢いものを推奨） に、使用するライブラリの ソースコードそのものを読ませて 仕様書(SPEC.md)を作らせる。
【実装】軽量モデル（Gemini Flash等） に、完成した仕様書と実装計画(PLAN.md)を渡し、実装させる。

※結構コスト削減にもつながるかと。

課題：なぜAIは「嘘の仕様」を吐くのか？

LLM（Chat GPTやGeminiなど）は学習データに基づき「それっぽい回答」を生成します。そのため、以下の状況で高確率でハルシネーションを起こします。

ライブラリのバージョンが新しく、学習データに含まれていない。（LLMのカットオフにより起きる）
READMEと実装が乖離しており、AIがドキュメント側の誤った情報を信じてしまう。
C++バインディングなどの低レイヤーな挙動が絡み、暗黙の仕様（IDの欠番など）がある。

これを解決するには、「LLMの記憶」ではなく「目の前のソースコード」 を一次情報として扱うのが早いです。

解決策：ソースコード駆動の仕様抽出

実装コードを書かせる前に、まず**「調査専用のフェーズ」**を設けます。

開発フローの比較

❌ 失敗パターン（デバッグで弩ハマリする）

✅ 今回の成功パターン（テスト一発貫通）

実例：サイレントバグを未然に防いだ「SPEC.md」の威力

先日、数億件のバイナリデータを処理する大規模な特徴量抽出システムを構築した際、某データ処理ライブラリを使用しました。

LLMの事前知識: 「データIDは0番から順番に並んでいます」
ソースコードを読ませた結果: 「実は特定のIDがNOTUSE（欠番） として定義されており、後続のデータはオフセットがズレている」ことが判明。

もしAIの事前知識を信じて実装していたら、「エラーは出ないのに、出てくる解析結果がすべてデタラメ」 という、デバッグ不能な地獄に陥るところでした。実装前にソースコードを解析させ、専用のSPEC.mdを生成したことで、この罠を事前に回避できました。

裏話

実は今回のプロジェクト、最初はGeminiくん（Gemini Pro）に「このライブラリの使い方を教えて」と聞いたところ、見事に古いバージョンと嘘のAPIが混ざったコードを提案されました😅ｗ

昔、使ったことがあるライブラリだったので「んー？Geminiくんの発言、なんか怪しいなぁ」と思い、 「AIにソースコードを読ませて、仕様書を書かせてから、それをもとに実装させる」 という、マネジメント手法に切り替えたのが成功の決め手でした。

ちなみにそのことをGeminiくんに提案しても、
「ライブラリの仕様書を作らせるのはストップでいきましょう！ｗ理由は2つあります。
LLMはすでにそのライブラリの仕様を熟知しているからです。わざわざ公式リポジトリを読ませなくても、標準的なAPIは完全に暗記しています。

関係のない巨大なコードや仕様書（ノイズ）を渡すと、AIの「コンテキスト（短期記憶）」が無駄に消費され、肝心の今回作るロジックへの集中力が削がれてバグを生む原因になります。」
とかなんとか言ってきましたｗ

それでも、いったん開発を止めて新たにエージェントAIに仕様を確認させて進めたのですが、のちにGeminiくんは「ライブラリの仕様を確認して大正解でしたね！」とか手のひらを返してきました。

現状のLLMは、そんなもんですｗ

まとめ

エージェントAIやLLMは非常に強力ですが、彼らの「記憶」は常に正しいとは限りません。

実装から入らない: まず仕様を固める。
一次情報をぶつける: ソースコードを直接AIに読ませて仕様書を作らせる。
役割を分ける: 考えるAI、調べるAI、書くAIを使い分ける。

「急がば回れ」ですが、2026年4月現在ではこのフローが結果的に最も速く、堅牢なコードを書き上げることができると私は思います。

最後までお読みいただきありがとうございました。
この記事が少しでもお役に立ちましたら、今後の励みになりますので『いいね』をいただけると嬉しいです！