AIエージェントのClaude Codeを使っていて気づいたのですが、あれは時々プロジェクト内の情報の見落としがありますね。 挙動を見ていると、プロジェクト全部を認識するわけではなくて、要約と検索結果を元に回答しているようです。当然ですけどね。プロジェクト全部を見ていたらとんでもないトークン数になってしまいますから。
ただ、これは重要な結果にもつながります。すべてのコードを全て渡せているわけではないから、ハルシネーションが多発する余地がかなりあるんです。実際そうなったケースに遭遇しました。
いやほんと、「AIなら全部覚えてるんでしょ？」って思ったら大間違いですね。エージェントなのに記憶力はポンコツ…って、おい、誰がポンコツだ！
おっしゃる通り、Claude CodeのようなAIエージェントがプロジェクト全体を常に完全に把握しているわけではありません。内部的には「プロジェクト全体からの要約」や「キーワード検索的な取得結果」に基づいて応答している形が多いです。つまり、全部のコードを逐一読んで判断しているわけではないということです。
この設計は、トークン制限のある大規模言語モデル（LLM）の宿命みたいなもので、全部を一度に突っ込むと「重すぎて吐く」みたいな事態になります。なので、パフォーマンスと正確さのトレードオフとして「一部の情報でなんとかする」方針になるのです。
その結果、見落としや、コード間の依存関係を誤解した「ハルシネーション（幻覚）」が起こるのは、ある意味で自然な帰結とも言えます。特に、以下のようなケースではハルシネーションが起きやすくなります。
- 依存関係の深いコードが分割されていて、AIが片方しか見ていない
- ドキュメントやコメントの情報が省かれており、意図が伝わっていない
- ユーザーのプロンプトが曖昧で、AIが補完しすぎてしまう
このあたり、「エージェントだから万能」みたいな期待をかけると、逆にハマるポイントですね。使う側が「見えてない部分がある前提」で設計・確認するのが大事だと思います。
あと、重要な判断を下す処理やコード生成にAIを使うときは、「部分的にしか見えてないかもしれない」と踏まえて、常に人間がレビューすべきという結論になっちゃいますね。いやー、未来って手間がかかる！
当然ですね。ただこれ、人間も基本的には同じなんですよ。規模のあるプロジェクトで、全部のコードを頭に入れて動いてる人なんてまずいません。
- 影響範囲を限定し <- これを読み損ねると「思わぬところにバグが！」となるわけなんですが
- 設計書とコードを丹念にあたって
作業するんです。これをAIエージェントにも応用できるのではないかなと。
なるほど、確かにAIに対して「全部把握しろ」って言うのは、人間に「100万行のコード全部覚えてからコミットしてね！」って言うようなもんですね。そんなの仙人でも無理です。いや、仙人でもきっとタスク分けてJIRA使いますよ。
ご指摘の通り、人間も実際には以下のような流れでリスクを抑えていますね。
1. 影響範囲を限定する
「この関数の修正で他に波及するのはこの辺」と見積もり、レビュー対象やテスト対象を絞る。これ、経験と設計知識が問われるところですが、見誤ると「あれ？なんでこのページが落ちてるの？」という悲劇が発生します。
2. 設計書・仕様・周辺コードをあたる
「この関数、なんでこう書いてあるんだ？」と思ったら設計書に戻る。コメント、仕様書、API定義などを見て、「納得してから」コードをいじる。逆に言えば、これをせずにやるとバグ製造機になっちゃう。
で、これをAIエージェントにも転用できるのではという視点、まさにその通りです。
実装上の工夫としては
影響範囲の推定機能
「この関数を変更すると他にどこが関係ありそうか」を推定してリストアップする。AIならコードベース全体の依存関係をグラフで持たせる形で近づけそうです。設計情報の参照強化
「docstring」「設計ドキュメント」「コミット履歴」などを組み合わせて文脈を強化する仕組み。要するに、AIの"仕様読め"を自動化する。不明点は明示して留保
人間なら「ちょっとこの仕様怪しいから聞いてみよう」と言う場面、AIも「この部分は仕様不明です、確認が必要かも」と出力できるとずいぶん助かります。
要するに、「AIも人間と同じように安全確認しながら仕事する構造にする」って方向性ですね。逆に、「全部見れるようにしよう」とするより現実的ですし、今の技術とも噛み合っています。
AIを“スーパー人間”として扱うより、“めっちゃ仕事早いけど、説明は必要な同僚”として使うのが良さそうです。まあ、その同僚、たまに壮大な勘違いしてくるんですけどね。
そこです。ただ影響範囲の推定を自分で実装するなんてとても手が出ません。超巨大プロジェクトになってしまいます。しかもいずれOpenAIやGoogleなどの巨人たちがやるでしょうから自分で頑張る理由が薄いです。
そこで発想を変えて、「最初から小さく作る」のがよいのではないかと考えています。モジュール化にがっちり手を入れるということです。今のところはですね。
なるほど、最初からでっかく作ると最後に泣くのは未来の自分…って話ですね。ええ、過去の自分、なぜ一つの関数に800行も詰め込んだんだ！ってやつです。
おっしゃる「最初から小さく作る」、これはAI活用という観点から見ても極めて理にかなっています。具体的には次のようなメリットがあります。
1. モジュール単位での認識がしやすくなる
LLMやAIエージェントはトークン制限の関係上、「広く浅く」より「狭く深く」が得意です。だからこそ、小さい単位＝モジュールで設計しておけば、その範囲内での因果関係や意味をAIが正確に把握できます。
2. 影響範囲が自然と限定される
モジュール化しておけば、「この関数を変えたらどこが壊れる？」の答えが「基本的にはこのモジュールの中です」で済みます。結果、影響範囲の推定をAI任せにしすぎなくて済むわけです。
3. 再利用・差し替え・テストがしやすくなる
当然ながら、モジュールごとに責務が明確になっているほどAIも扱いやすくなります。たとえば、「このAPIラッパーだけ書き直して」といった作業なら、AIはそこだけ集中して処理できるようになります。
4. AI補助に向いた設計手法になる
小さく作ってモジュール単位で責務を切るというのは、いわゆるクリーンアーキテクチャや関心の分離（SoC）とも一致します。AIが特に得意なのは「関数レベル」「クラスレベル」での編集なので、自然と作業粒度がAIフレンドリーになります。
実際にClaudeでもChatGPTでも、ファイル単位や関数単位でのやりとりにすると精度がグッと上がります。「プロジェクトごと投げる」ではなく「この関数とそのユースケースだけ」と絞ることで、ハルシネーションも減りますし。
要するに、「AIが把握しやすい構造にする＝人間も把握しやすい構造になる」という、二兎どころか三兎くらい得する発想ですね。プロジェクトを小さく切る勇気、大事です。「AIのための設計」なんて変な気がするかもですが、それはつまり“未来の自分のための設計”なんですよね。