AIのハルシネーションの見抜き方｜開発現場で気づく型
AIに「このライブラリでこう書ける」と教わって、その通りに書いたらそんな関数は存在しなかった。 あるいは、自信たっぷりに案内されたパッケージ名を install しようとして、レジストリに見つからない——そんな空振り、ありますよね。
これが「ハルシネーション」、AIがもっともらしく、でも事実でないことを返してくる現象です。 やっかいなのは、口調がいつもと同じくらい自信に満ちていること。だから読んでいる側は「たぶん合っている」と思って、そのまま使ってしまう。動かなくて初めて気づくならまだ運がよくて、動いてしまうと気づけないこともあります。
この記事は、AIのハルシネーションを開発の現場でどう見抜くかの型をまとめたものです。一般論で終わらせず、エンジニアが実際に出会う形——存在しないAPI、危ないパッケージ名、古い仕様、捏造された出典——に絞って、気づくサインと裏の取り方を深掘りしました。長く見えますが、全部は不要。まず効く所から拾えば回ります。
30–60秒のファストパス（最低ライン）
- 知らない関数・引数が出た：エディタ補完/定義ジャンプ or 公式リファで「実在だけ」確認（30秒以内）
- 提案パッケージが出た：install前にレジストリ検索＋素性をざっと見る（発行元/更新履歴/定番名と一致）（60秒以内）
- 自信満々の説明が出た：結論を支える前提を1点だけ自分で検証（30秒以内）
※ここで迷ったら一旦保留でOK。深掘りは後述の手順へ。
結論：ハルシネーションは「AIの賢さ不足」ではなく、AIがありそうな続きを作る仕組みから生まれる正常な副作用。根絶はできません。疑う観点を持ち、一次情報で裏を取るのが現実解です。まず効くのは、①APIの実在確認 → ②パッケージは入れる前に素性確認 → ③断定説明は前提1点だけ検証。動いた＝正しい、ではありません。
AIを疑うのは、AIを否定するためではありません。 安心して使い続けるために、確かめる場所をひとつだけ決めておく——それだけです。
そもそもハルシネーションとは何か
LLMは、正解を引いてくる装置ではなく、学習したパターンから「次に来そうな言葉」を組み立てて返す装置です。つまり、文章のなめらかさと事実の正しさは別軸。実在のAPIと同じくらい自然に、実在しないAPIも「ありそうな名前」で作れてしまいます。
前提として持っておくと楽になるポイント：
- 自信の強さは正しさの証拠ではない
- 曖昧な質問ほど「よくあるパターン」で埋められやすい
- 学習後の更新（新仕様・新ライブラリ）ほど弱い
- 根絶はできない。出る前提で確かめる場所を決める
開発現場で現れる5つの型
ハルシネーションは、だいたい次の5型です。地図を持っておくと、気づきが速くなります。
| 型 | どう現れるか | 危なさ |
|---|---|---|
| ①存在しないAPI・メソッド | それっぽい関数・引数・オプションを案内 | 動かない（気づきやすい） |
| ②存在しないパッケージ | レジストリに無い名を install させようとする | 動かない／悪用時に危険 |
| ③古い・誤った仕様 | 廃止/変更後の書き方を今も有効と説明 | 動くが間違い（気づきにくい） |
| ④捏造された出典 | それらしいURL・規格番号・引用を作る | 根拠ごと誤る |
| ⑤自信に満ちた誤説明 | 滑らかな理由づけで誤結論を断言 | 最も気づきにくい |
下にいくほど、動いてしまう・もっともらしいぶん、すり抜けます。
型①：存在しないAPI・メソッド
都合よくハマる名前は要注意。AIは「あったら自然な名前」を作れます。補完に出ない・定義に飛べない・ドキュメント記憶がないのに妙に便利、は赤信号。
型②：存在しないパッケージ（安全に直結）
install は実行行為。ここは手前で止めます。AIが作りがちな「ありそうな名」を、第三者が本物のレジストリに登録しておく手口（スロップスクワッティング／typosquatting／dependency confusion など）があります。存在しないはずの名が、たまに「存在してしまう」。install できた＝本物でも安全でもありません。入れる前に見るのが筋です。
型③：古い・誤った仕様
コードは動くが推奨でない・挙動が変わっている、が静かに起きます。バージョン指定なしの断定、「最新」と言いながら根拠が薄い、時期感のズレはサイン。
型④：捏造された出典
出典要求で安全、とは限らない。URLを開く・規格を発行元で引き直すまでが確認。開けない・無関係なら捏造を疑う。
型⑤：自信に満ちた誤った説明
筋は通って聞こえるが、前提が誤り・因果が逆。結論を支える前提を1点だけ自分で確かめると、早めに外せます。
見抜くための手順——一次情報で裏を取る
全部を毎回やる必要はありません。いま扱う型に合う関所だけ通せば十分です。
手順1：API・メソッドは公式リファ or 型定義で「実在」確認
- 公式ドキュメントで関数名・引数を検索
- エディタの補完・定義ジャンプ（型のある環境）で存在を確認
- 補完に出ない／定義に飛べないなら、いったん「無い」扱い
エコシステム別の即確認テク（30秒で切り上げ）
- Node/TypeScript：定義ジャンプ・型ヒント・npm info で実在チェック
- Python：REPL の help()/dir()・pip show で存在と由来を確認
- Go：go doc / pkg.go.dev でシンボルとパッケージを確認
- CLI系：--help/--version でコマンド・フラグの「旗振り」確認
社内/私有APIの実在確認
- 社内Swagger/OpenAPI・型定義・内製Wiki（一次情報）→メンテ担当に確認、の順で優先
- リンクが古い/到達困難なら、担当に「現行の参照先」をもらってから採用判断
手順2：パッケージは「入れる前」にレジストリと素性を確認
- 公式レジストリで実在検索（似名・タイポに注意）
- 素性をざっと見る：公開元、リポジトリ有無、更新履歴、使われ方の気配
- 定番名と一致しているか確認（迷ったら定番を自分で再検索して一旦見送る判断も可）
安全確認の自動化ヒント（軽くでOK）
- 隔離環境で試す：仮想環境/コンテナで導入テスト
- 中身を先に覗く：npm pack・pip download で展開して確認
- 既知脆弱性の素早いスキャン：npm audit・pip-audit などSCA系を流す
手順3：仕様は「バージョンを添えて」一次情報で確認
- 相談時に対象バージョンを明示
- その版のドキュメントとCHANGELOG/リリースノートで裏を取る
- 非推奨・廃止予定の表示を特に見る
- 学習後の変更点はAIの答えをたたき台にし、公式情報で確認
手順4：出典は「たどって」確認、無ければ無いと扱う
- URLは開いて主張と対応するか確認（404・無関係は捏造疑い）
- 規格・仕様は発行元で引き直す
- 出典が出せないものは根拠なし扱い
手順5：断定説明ほど「前提を1点だけ」自分で検証
- 結論を支える前提を抽出
- その1点を一次情報や小さな実験で確認
- 前提が崩れたら結論ごと保留。「なめらかさ」は信頼度に足さない
補助：プロンプト側でも減らす（過信しない）
- 「わからない場合はわからないと答えて」と許可
- 「実在を確認できないものは明記を」と依頼
- 「出典は、たどれる形で示して」と依頼（自分でたどる前提）
- バージョン・前提・制約を渡して推測余地を縮める（AIにコードを書かせる前に渡す前提と制約）
リスクベース運用（強度は段階化、②は常に厳しめ）
| 対象/場面 | 検証強度の目安 | ②パッケージ | ③〜⑤ 仕様/出典/説明 |
|---|---|---|---|
| PoC/検証用 | 速さ優先（隔離前提） | 実在＋素性を簡易確認 | 重要前提を1点だけ確認 |
| 社内ツール | バランス重視 | 実在＋素性＋隔離で試験 | 版と出典を確認 |
| 本番/基盤 | 厳格 | 実在＋素性＋中身確認＋SCA | 版・出典・前提を複数点で確認 |
閉域/オフライン現場の代替手段
- 社内レジストリ/ミラーとallowlist運用
- Zeal/Dash等のドックセットをローカル配備
- pre-commitやCIで未承認パッケージの導入をブロック
ありがちな落とし穴
- 動いた＝正しい、と考える（必要条件であって十分条件ではない）。動作確認の型は生成コードの動作確認チェックリスト
- 断定口調を正しさと取り違える
- 出典を出させて満足する（開いてたどるまで）
- パッケージをそのまま入れる（②は実行前確認が肝）
- カットオフを忘れる（新しい話題ほど弱い）
- 一度信じたら再検証しない（要所は聞き直す）
チームで回すときの落とし穴と対策
- ロックファイルの徹底・バージョンのピン留め（意図せぬ更新を防ぐ）
- 依存変更時はCHANGELOG/リリースノートなど一次情報をIssue/PRにリンク
- パッケージ採否の決定ログを簡易テンプレで残す（何をどこまで裏取りしたか）
- 新規パッケージは承認リスト経由にし、CIで未承認の導入をブロック
明日からやること（小さく始める3つ）
- 知らない関数は、採用前に公式リファ or 型定義で実在確認（補完に出ないものは一旦「無い」扱い）
- 提案パッケージは、
install前にレジストリと素性を確認（迷ったら見送る） - 自信たっぷりの説明は、前提を1点だけ自分で検証
この3つだけでも、もっともらしい誤りの多くは手前で止まります。慣れたら、出典確認やバージョン明示を足していけば十分です。
ハルシネーション対応チェックリスト
「関係する行だけ見る」が前提。全部に○は要りません。いま扱う型に関わる所だけ、さっと確認します。
運用ガイド（回すコツ）
- 最低ライン（ファストパス）：①未知の関数は補完/公式で存在だけ確認、②パッケージはinstall前にレジストリ＋素性だけ確認、⑤断定説明は前提1点だけ検証（各30–60秒上限）
- 優先順位：必須=②（常に実施）。高=①/③（影響が出る改修や新規採用時）。中=④（外部ドキュメントを根拠に意思決定するとき）。中=⑤（設計判断に効く説明のとき）
- 免除条件：長期運用の既存リポジトリでロック済み依存は②の素性チェックを省略可／社内承認リスト掲載パッケージは②を簡略化可／既知APIで変更なしは①省略可／PoC・使い捨ては隔離前提で②の素性を簡略化
- 代替策：公式リファ不在/到達困難→エディタ定義ジャンプ/型定義/REPLのhelp()で代替。URL検証が重い→発行元トップから仕様名で再検索。パッケージ判断に迷う→「定番名と一致しているか」だけ先に確認し、見送る判断も可
API・メソッド（型①）
- 使う関数・引数を公式リファレンスで確認したか
- 補完・型定義に実在しているか
- 「都合がよすぎる名前」を疑ったか
パッケージ（型②）
-
install前にレジストリで実在を確認したか - 公開元・更新履歴・利用実績など素性を見たか
- 一般的な定番名と一致するか確かめたか
- 隔離環境で試し、必要に応じて中身/既知脆弱性を確認したか
仕様（型③）
- バージョンを明示して聞いたか
- そのバージョンのドキュメント／変更履歴で確認したか
- 非推奨・廃止予定が無いか見たか
出典（型④）
- URLを実際に開いて内容を確認したか
- 規格・仕様を発行元で引き直したか
- 出せない出典は「根拠なし」として扱ったか
説明の中身（型⑤）
- 結論を支える前提を1つ自分でたどったか
- 「動いた」を「正しい」と取り違えていないか
- 自信の強さを信頼度に足していないか
最後に
ハルシネーションは、AIの故障ではなく「ありそうな続きを作る」性質の裏側です。出る前提で受け取り、確かめる場所をひとつ決めておく。それだけで、AIは安心して使い続けられる道具になります。
今日ひとつ、「知らない関数は採用前に実在確認する」ができたなら、それはもう、もっともらしい誤りを一つ手前で止める確かな一歩です。 そして、確かめたコードも、最後はやっぱり人が一段見ます。受け取った後に何を見るかはAI生成コードのレビュー・検証チェックリストに、そもそも何を任せ何を任せないかは「AIで何とかしろ」と言われたら｜まず確認する6つにまとめました。疑い方の型と、確かめ方の型。この2つがそろうと、AIとの付き合いはぐっと落ち着きます。