はじめに
AIを使った個人開発ではAIが突然おかしな挙動をし始めたように見える瞬間に出会うことがあります。
私も単語アプリを開発している中で原因がすぐには分からない不具合に遭遇しました。
結果的にこの問題の切り分けに何時間も使ってしまい、AIの挙動に振り回されてしまいました。
この記事では「どういうデバッグ手順に切り替えたら安定して原因特定できるようになったか」をAI個人開発者向けのデバッグ方法としてまとめます。
前提
アプリの構成は次の通りです。
- 入力：ユーザーが検索した英単語
- 処理：AI がその単語の辞書エントリ（意味・品詞・例文など）を JSON形式で生成
- 出力：生成された JSON をそのまま UI に流して表示
起きた現象
例えば look という単語を検索しているにもかかわらず画面上では undefined という単語が検索されたことになっている という現象が起きました。
この時点では「AIが勝手におかしな単語を選んでいるのでは？」と感じてしまい、AIの出力やプロンプトそのものを疑い始めていました。
しかし、結果的にこの問題の切り分けに何時間も使ってしまいAIの挙動に振り回されてしまいました。
ブラックボックス化したAIの生成過程をどう切り分けて観測したか
そこでAIの生成過程を 2点だけ に分けて観測する方針に切り替えました。
見るのは次の2か所です。
- 入り口
- AIに渡しているプロンプト
- 出口
- AIが返してきたrawの状態のレスポンス
①入り口でAIに渡すプロンプトを観測する
まず確認するのはAIに実際に渡しているプロンプトの最終形です。
テンプレートではなく、${word} などの変数がすべて展開された状態を console.log で出力します。
const prompt = wordPrompt(word)
console.log('PROMPT (final):', prompt)
ここで確認するのは次の点です。
- 検索語が
undefinedや空文字になっていないか - 想定外の文字列が混ざっていないか
- JSONの雛形やルール文が壊れていないか
この入り口の内容が正しいことを確認します。
② 出口でAIのレスポンスを raw のまま観測する
入り口に問題がないことを確認できたら次に AIの出力 を確認します。
const rawText = await res.text()
console.log('AI RAW:', rawText)
return JSON.parse(rawText)
ここで次の点を確認します。
- 出力が単一の JSON オブジェクトか
-
{で始まり}で終わっているか - 余計な説明文や Markdown が混ざっていないか
この切り分けで得られたこと
この2点を順番に観測することで
- 入り口が壊れている → こちらのコードの問題
- 入り口は正しいが出口が壊れている → プロンプト設計や制約の問題
と、原因を機械的に切り分けられるようになりました。
今回のバグはどう対応したか
今回のバグも最終的には プロンプト上で検索語を主語として固定できていなかった ことが原因でした。
NEVER replace the wordのような制約を追加したところこの挙動は再現しなくなりました。
ただし重要なのは原因そのものではなく、入り口（プロンプト）と出口（AI raw）を切り分けて観測していたからこそこの結論に辿り着けたという点です。
console.log で過程を可視化することが最重要
今回の経験から強く感じたのは、
AI個人開発ではまず console.log で生成過程をフェーズ別で可視化することが最重要
という点です。
- 入り口（プロンプト）
- 出口（AI raw）
この2点を確認したら最終的にプロンプトの精査を開始します。
NEVER や MUST といった制約を 意味のある形で追加できます。
まとめ
- ブラックボックスなAIは分解して観測する
- デバッグは責務がAIなのかシステムなのかを切り分けるために行う
AIは気まぐれに見えますが、こちらが渡した情報と制約の中で合理的に振る舞っているだけでした。
また他にも良い方法があると思いますが、こちらは個人の知見として同じようにAIの挙動に振り回されている個人開発者の参考になれば嬉しいです。