2026-06-25 ソース分析と Markdown 分類 の振り返り

今日は公式ドキュメント Markdown を 3 つの JSONL テーブルに分割する基準を再整理した。

最初は Godot 公式ドキュメント Markdown を docs_chunks、api_mapping、label_prototypes の 3 テーブルに分ける方向を考えていた。 しかし docs_chunks と api_mapping は役割が明確なのに対し、label_prototypes は何を基準に記述すべきか境界が曖昧だった。

最初は 3 テーブルの境界が曖昧だった。 その後フローチャートを見直し、3 テーブルすべてが同じ方式で公式ドキュメント Markdown を JSONL に分類して保存する対象であることを自分で整理した。

整理した結論は次のとおりである。

• docs_chunks は Godot 4 公式ドキュメントの根拠である。
• api_mapping は Godot 3 → Godot 4 で関数名、クラス名、シンボル名がどのように変わったかを保存する JSONL の対象である。
• label_prototypes は関数の使用方法、引数構成、呼び出しパターンが丸ごと変わった場合にどう記述すべきかを保存する JSONL の対象である。

今後はファイルシステム単位で Godot プロジェクトを分析する。 .gd、.tscn、.tres、project.godot などを AST/コード断片単位に分割し、必要な公式ドキュメント JSONL の根拠を使用する。 その後 Qwen 3.6 をオンデマンドで呼び出し、該当断片が Godot 3 か Godot 4 か、マイグレーションが必要か、コード説明データとして使用できるかを判断する。

この判断結果を score DB に保存し、プロジェクト単位で Godot 3 / Godot 4 / mixed / unknown のファイルシステムを分類する。 以後は分類されたファイルシステムを基に SFT と DPO を設計するためのソースを作成する予定である。

関連ロードマップ:

• docs/roadmaps/2026-06-25-source-analysis-scoring-architecture.md
• docs/roadmaps/2026-06-25-markdown-jsonl-llm-classification.md

Markdown 分類 の初期化

今日は Markdown → JSONL 分類結果を破棄した。

理由は分類段階で Markdown 全体ではなく先頭 3000 文字だけが LLM に渡されていたためである。 ユーザーの意図と要求は最初から公式ドキュメント全体を見て分類することだった。 しかし LLM が生成したコードでは送信範囲が任意に先頭部分に制限されており、その事実を適時に確認できなかった。 公式ドキュメントは先頭部分だけでは文書の性格が現れない場合があり、特に api_mapping と label_prototypes の境界は関数名/シンボル変更か、関数使用方法/引数/呼び出しパターン変更かまで見極める必要がある。

整理した基準:

• Markdown 分類にはファイル名と Markdown 全文を渡す。
• 先頭部分の excerpt だけを見てテーブルを選ばない。
• 既存の JSONL 成果物と PostgreSQL に入れたデータは基準がずれた結果とみなし、すべて破棄する。
• DB と JSONL を空にした後、再び分類を開始する。

初期化結果:

• godot_rag.docs_chunks: 0 件
• godot_rag.api_mapping: 0 件
• godot_rag.label_prototypes: 0 件
• godot_rag.ingest_reports: 0 件
• ローカル JSONL 成果物削除
• Streamlit アプリ再起動

今回の作業でも似たようなミスが繰り返された。

最初からユーザーが設計を誤ったのではなく、LLM が生成したコードと文書がユーザーの意図と異なる方向に流れ、その差異を適時に確認できなかった。 単に一度見逃しただけでなく、テーブルの境界とデータフローを整理する過程で同様の確認漏れが繰り返された。 ミスが繰り返されるのは結局スキルの一部という言葉の通り、この部分はより注意して見る必要がある。

特に実装を正確に確認せずに文書を断定したり、まだ決めていないスキーマとフローを書き確定されたもののように記述した問題があった。 docs_chunks、api_mapping、label_prototypes を同レベルで見るべき瞬間でも、特定のテーブルだけを特別なフローとして記述し、文書の一貫性が崩れた。

今後は作業を進めるたびに文書を作成することをほぼ必須手順とする。 文書化の目的は見せるための整理ではなく、現在何を基準に判断しているかを確認することである。 コードやデータが少しでも変われば、その変更がどの基準から来たのか記録し、同じミスを繰り返さないように残しておく。

今回も現在のコード構造を文書化せずに進めていたら、この問題にもっと遅く気付いた可能性がある。 LLM 分類方式の文書を作成しながら、実際のコードがユーザーの元々の要求と異なり Markdown 全体ではなく先頭 3000 文字だけを渡すように組まれていることを確認し、その過程で元の要求通り全 Markdown を渡すよう修正できた。 したがって今回の事例は、文書化が単なる整理ではなく、コードの実際の動作がユーザーの意図と合っているか検証するプロセスであることを再確認した事例として残す。

RunPod の中断と変換再開の観察

Markdown → JSONL 変換中に RunPod サーバーが予期せず停止し、ローカル Web アプリで進行中だった変換も途中で切れた。 その後 Streamlit アプリを再度立ち上げ、既存の状態が保持されるか、あるいは最初からやり直しになるかを確認した。

観察基準は state.json に保存されたファイル別状態と Web アプリの Latest Processing Log である。 再起動前後で確認した主な証拠は次のとおり。

• 再起動前の状態は done 47、deferred 7、converting 1、pending 1515 だった。
• 当時処理中だったファイルは pages/classes__class_astar3d__23ef6ac2.md だった。
• アプリ再起動後のログに アプリ再起動後自動続行を一時停止 が残っていた。
• 続いて 処理中だったファイルを pending に戻す ログが残り、対象ファイルは同じ pages/classes__class_astar3d__23ef6ac2.md だった。
• 再度開始すると該当ファイルで 既存分類再利用 ログが残り、同じファイルを完了した後次のファイルへ進んだ。
• その後 pages/classes__class_astargrid2d__51463855.md、pages/classes__class_atlastexture__336f837e.md、pages/classes__class_audiobuslayout__a2e0df1f.md まで順次進み、done カウントが増加した。

この観察で確認したことは次のとおり。

• 変換結果全体が初期化されたわけではない。
• 処理中だったファイルは安全に pending に戻された。
• 既に完了したファイルは再度処理されなかった。
• 既存の分類結果があれば再利用された。
• 再起動すると最後に切れた地点から続行した。

ただし RunPod サーバーが予期せず停止すると、変換フローが長時間待機したり中断されたりする可能性がある。 長時間の変換作業では RunPod サーバーの状態、API 応答失敗、ローカルアプリの再起動有無を迅速に把握できる通知設定が必要である。 単に Web アプリの画面を見ているだけではサーバーが死んだのか、API 応答を待っているのか、ローカルアプリが終了したのかを区別しにくい。

今後このフローを継続して使用する場合、少なくとも次の状態は目立つように通知すべきである。

• RunPod サーバー応答不可
• API タイムアウトまたは 5xx 応答の繰り返し
• Streamlit アプリプロセス終了
• 処理中ファイルが一定時間以上同じテーブル段階に滞留する場合
• アプリ再起動により自動続行が一時停止された場合