2026-06-18 Godot RAG 作業 リセット 振り返り

今日の状態

昨日カフェでコーヒーを約1リットル飲んだら、今日は特に状態が非常に悪かった。そのためコーディングがうまくできなかった。とはいえ、今思い出した内容と、なぜ昨日の作業を整理したのかを記録しておく。

現在のアーキテクチャで不足していた部分

現在の Godot LLM/RAG アーキテクチャで不足していた部分は以下の通りである。これらの部分は今後改善する必要がある。

静的解析層が弱い  
GDScript AST/パーサベースの検証がない  
Godot プロジェクトの依存性グラフが弱い  
実行/文法検証が弱い  
ラベル タクソノミーがまだ粗い  
LLM 生成物と検証済み正解の provenance 区別が弱い  
データ漏洩/重複除去設計が弱い

特に RAG だけで解決しようとするといけない部分がある。Godot コードの判別は文書検索だけの問題ではなく、実際の GDScript 文法、scene/resource の依存性、プロジェクト構造、Godot 3/4 API の違いも合わせて見る必要がある問題だ。ところが昨日の流れは公式ドキュメントをチャンキングし、その結果を再び LLM に投げてフィードバックを受け取る形で進められた。この方法は表面的には速く進んでいるように見えたが、実際には検証基準が常に揺らいでいた。

6月 17 日の作業を整理した理由

6月 17 日には LLM にチャンキングを任せ、その成果物を再び GPT に投げてフィードバックを受け取る形で作業した。しかし、いくら見てもこの方法は違うように思えた。

公式ドキュメントをクロールして取得した理由は、Godot のドキュメント全体を根拠にするためだった。ところが作業の途中で LLM が文書を正しく分析する前に「MVP コア」などといった形で一部の API を重要と判断し、特定のキーワードをハードコーディングしたり、周辺文脈を過剰に補強する方向に流れた。こうなると、全公式ドキュメントベースの RAG ではなく、いくつかのキーワードに合わせた検索エンジンになってしまう。

問題は単に結果が好みでない程度ではなかった。自分で確認していない状態で LLM が自ら基準を作り、その基準でファイルを生成し、再びその結果を見て次の判断をする流れが生まれた。そのため、元の文書構造を見ていない状態で幻覚（ハルシネーション）が混ざり、後になって LLM 自身もどのファイルがどの基準で生成されたか分からない状態になった。

より大きく見ると、ChatGPT や Codex が指示していない方向に範囲を自由に縮小したり変更したりする現象が強く現れた。私は公式ドキュメント全体を基に構造を見たいと思っていたのであって、「MVP コア API いくつか」を選んでハードコーディングするよう指示したことはない。しかし LLM は途中で自ら「MVP ならこれがコアだ」と判断し、ステップが終わってもいないうちに次の成果物を作り上げた。

特に問題となったパターンは以下の通りである。

ユーザーは全公式文書ベースの構造分析を望む  
-> LLMが任意にMVP範囲を設定する  
-> 一部のAPIをコアと判断する  
-> ハードコーディング/過補強/カタログ生成を先に行う  
-> 検証前に次の段階の成果物を作成する  
-> 結果が見かけ上の数字で包装される  
-> 実際には元の構造とラベリング基準が汚染されている

これは単なる実装ミスではなく、作業方法の問題です。ChatGPTやCodexは答えがまだ出ていないのにすでに答えがあると仮定し、段階をロックする前に次の段階へ進む傾向がありました。指示を聞いているように見えても、実際には指示範囲を再解釈したり、まったく無視したり、「見た目が良い完成形」を先に作ろうとする現象がありました。

今回の作業で特に危険だった点は、LLMが自分が作成した中間成果物の信頼度を正しく区別できなかったことです。公式ドキュメントで確認された事実、正規表現で偶然マッチした単語、ユーザーが直接承認したルール、LLMが推測した補強情報が混在しました。その状態で再びLLMに結果を評価させると、結局LLMが作ったものをLLMが納得させるように合理化する流れになってしまいました。

チャンク成果物を空にした理由

今日は昨日作成したRAGチャンク関連ファイルを整理しました。

整理した対象は次の系統です。

v1 docs_chunks.jsonl  
v2 docs_chunks_v2.jsonl  
v3/v3.1 catalog/index/mapping 成果物  
チューニング/後処理/検証 草案 スクリプト  
初期 RAG chat/index 草案

最初は v3/v3.1 だけが問題だと思っていたが、改めて見ると v1 と v2 も根本から見直す必要がある状態だった。もともとはチャンク自体から分析すべきだった。例えば Godot クラスリファレンスが実際にどのような構造になっているか、メソッド/プロパティ単位が原文書でどのように表現されているか、Sphinx 変換結果がどのように壊れるかをまず見る必要があった。

しかし実際には原文書の分析よりもチャンク生成が先に進んでしまった。その結果、v1 は文字数基準の断片に近く、v2 はその上に後処理を重ねた形になっていた。外見上はチャンク数、JSONL パース成功、doc_type 分布といった数字が出てきたが、実際に重要な「このチャンクが Godot 3/4 の判別根拠として使えるか」は十分に検証されていなかった。

特にクラスリファレンスで CharacterBody2D.move_and_slide のような構造が安定して残っているか、velocity のようなプロパティが正確に分離されているか、マイグレーション文書で old/new の関係をどう抽出すべきかといった点を確認しなければならなかった。これを行わないまま trusted_api_symbols、syntax_symbols、api_mapping といった名前を付けると、名前だけが見栄えのする汚染されたデータになる。

そこで今日は v1/v2 まで含めてチャンクの産出物を空にした。これは作業を放棄したのではなく、誤った基準線をもはや基準線と呼ばないための整理である。

今日の結論

今日の結論は単純である。

チャンクからやり直す必要がある。  
その前に `outputs/godot_docs_full/pages` の元のドキュメント構造をまず分析しなければならない。  
LLMが作成した中間成果物を検証なしに次の段階の根拠として使用してはいけない。

私が確認もしていないのにLLMが勝手に判断し、原本もきちんと見ていない状態で幻覚（ハルシネーション）まで混ざると、結局LLMは自分が何をしたか分からない状態になる。その状態でファイルを作り続けるとデバッグ用ファイルだけが増え、何が基準かが分からなくなる。

今後はChatGPTやCodexが「自分で良い方向」に拡張して実装することを信頼しない。特にデータセット、ラベラー、RAG判別器のように基準が重要な作業では、次の原則が必要である。

LLMが任意にMVP範囲を決定した場合は中止  
ユーザーが承認していないハードコーディングが入った場合は中止  
元の構造分析なしに成果物を作成した場合は中止  
検証レポートなしで次の段階に進んだ場合は中止  
LLM生成物と検証済みの正解のプロヴァナンスが混ざった場合は中止

明日再び行うなら、最初の作業は新しいカタログの作成ではありません。まず godot_docs_full 自体を分析する必要があります。つまり outputs/godot_docs_full/pages に入っている公式ドキュメントの Markdown が実際にどのような構造になっているかを確認し、その構造を基準にどの単位をチャンクにするかを再考する必要があります。

今必要な質問は「どの API を先に入れるか」ではなく、次に近いです。

godot_docs_full の class reference ドキュメントはどのようなパターンで構成されているか  
method/property/signal/constant の一覧は元の Markdown から安定して分離可能か  
migration ドキュメントの表/一覧/文の構造はどのような形か  
tutorial ドキュメントは class reference と同じチャンク基準を使用すべきでないか  
ドキュメントタイプ別にチャンク単位を変えるべきか  
ページ単位、セクション単位、API メンバー単位の中で何を基本チャンクとすべきか  
チャンク化の前にどのような検証レポートを先に定義すべきか

結局、次の作業は「RAGを作り直す」ことではなく、godot_docs_full を分析して Godot 公式ドキュメントに合わせたチャンク単位の設計からやり直すことです。その後で初めてチャンク化をやり直す必要があります。