idea_world_labDEV JOURNAL
2026年6月27日土曜日

2026-06-27 振り返り

今日は 26 日に作成した source-to-AST 入力フロー文書の一貫性を改善することを目標にしたようだ。

昨日までは全体レイヤーが頭の中では区別されていたが、文書やコードではあまりにも抽象化された段階にとどまっていた。AST、Retriever、LLM 検証、JSONL 根拠といった言葉は区別できていたが、実際のプロジェクトが入ってきたときにどのファイルがどの順序で展開され、どの本文が AST Parser に入り、どのチャンクが Retriever にそのまま渡されるかまで具体化されてはいなかった。

頭の中では理解していると思っていたが、その状態でコードを書き始めると自分の望む方向に実装されないのではないかという不安感がかなり強かったようだ。そこで今日はまず全体構造を再構築し、その構造を人が目で確認できる GUI 形式で設計しようとした。

具体化が必要だった理由

AST と Retriever の役割は実際には区別されていた。

.gd ファイルは AST Parser に入り、関数や宣言単位で切り分けられる必要がある。Retriever はその結果として得られたコード片を受け取り、DB から関連する JSONL 根拠を検索しなければならない。そして LLM 検証はプロンプト、現在のチャンク、検索された JSONL を見てその根拠が実際に関連しているか判断する。

しかしこれを言葉だけで整理するとずっと曖昧になってしまう。特に実際のプロジェクトフローではファイルがまず # <相対パス> 形式で展開され、その下の本文がファイル単位で分かれ、.gd ファイルの特定の関数や宣言がチャンクとなり、そのチャンクの chunkText だけが Retriever に渡される必要がある。

私はこのフローをきちんと見たいと思った。どのファイルのどの本文がどのチャンクになったのか、Retriever が受け取った入力が本当にそのチャンクそのものか、ファイルパスや行番号、プロンプトが検索入力に混ざっていないかをウェブ画面で直接確認したかった。

そこで単に文書を書くのではなく、ユーザーが見やすい GUI で確認できるツールが必要だと考えた。

Source Flow Debugger

結果的に Source Flow Debugger を作りながら AST と Retriever のフローを一画面で見られるようになった。

最初はソースコードをどう AST 側に渡すか整理しようとしたが、やっているうちに AST チャンク、direct チャンク、Retriever 入力、DB 検索ボタン、Qwen 検証プレビューまでが一画面に詰まった。いつの間にか AST と Retriever、LLM 検証が統合された構造になり、思ったよりも便利になったようだ。

なかなか頭を使った点は、これを最初から完成したシステムにしようとせず観察ツールとして作ったことだ。現在の段階で必要なのは「正解を自動で出すツール」ではなく、私が意図したフロー通りにデータが移動しているか確認するツールだった。

今日確認したことは次のとおり。

  • Godot プロジェクトを # <相対パス> 形式で展開する。
  • .gd ファイルは AST 性質のチャンクに分割する。
  • .godot、.tscn のようなテキストリソースは direct チャンクに分割する。
  • README.md のような文書ファイルは source-analysis モードから除外し、除外理由を画面に残す。
  • Retriever 入力にはファイルパス、行番号、プロンプトを入れず chunkText のみを入れる。
  • 各チャンクの下で docs_chunks、api_mapping、label_prototypes をテーブル別に検索できるようにする。
  • その後 Qwen 検証は prompt + chunkText + retrieved JSONL 構造で渡される。

小さな Godot プロジェクトを入れたとき 5 files、14 chunks、AST 9、Direct 5 に分解されることも確認した。この程度でチャンク単位に分割するフローはある程度成功したようだ。

GPT デモテスト

もともとは収集した JSONL セットを基に関連する GitHub リポジトリを探し、そのリポジトリをクローンしてテストしようとしていた。

しかし考えてみると必ずしも最初から実際の GitHub リポジトリを探す必要はなかった。今確認したいのは「検索された JSONL が現在の Godot コードチャンクと本当に関連しているか LLM が正しく判定するか」だった。そこで GPT にデモ用の Godot チャンクと関連 JSONL、無関係 JSONL を作らせて先にテストする方が早いと考えた。

そこで意図的に Godot 3 コードチャンクを作り、それに合わせた Godot 3 → Godot 4 変換 JSONL と全く関係のない JSONL を一緒に作ってテストした。

最初は単純にこう尋ねた。

このJSONLはソースコードに該当する内容を含んでいますか？  
回答ははい／いいえのみです。

そうすると、関連する JSONL も 예、無関係な JSONL も 예 と出ました。

最初は残念に思えるかもしれないが、むしろ幸いだと思った。現在の段階でこの問題が表面化しなければ、後で実際の DB 検索を組み込んだときに、関係ない JSONL でも LLM が自分の知識で納得できるようにつなげてしまう可能性があっただろう。

それで、プロンプトをより強く変更した。

## 日本語訳

あなたは JSONL 根拠マッチング判定器です。

以下の **SOURCE_CODE** に対して、下記の JSONL が直接的な変換根拠を含んでいるか判定してください。

### 判定基準
- JSONL の `source_api`、`source_pattern`、`match_terms`、`required_when_seen_in_code`、`before_code` のいずれかが **SOURCE_CODE** 内の実際の文字列または API 呼び出しと **完全に一致** している場合のみ「**例**」です。
- 単に `Godot`、`Godot3`、`Godot4`、`migration`、`2D`、`physics` などの広い語句が同じであっても、関連性はありません。
- JSONL に「does not describe」「not related」「unrelated」「does not apply」などと **否定的に記載** されている内容は根拠として認めません。
- JSONL が別の API、別のノード、別のシステムに関する内容であれば「**いいえ**」です。
- あなたが持っている Godot の知識は使用せず、JSONL に記載された文字列根拠だけを使用してください。
- 回答は必ず「**例**」または「**いいえ**」のいずれか **一つだけ** 出力してください。

このように変更しよう 関連 JSONL は 예, 無関係 JSONL は 아니오 に分けられた。

今日この実験で得た基準は重要である。Retriever が JSONL 候補を取得した後、LLM に検証させる際には広い意味での類似度を見るべきではない。JSONL 内の source_api, source_pattern, match_terms, required_when_seen_in_code, before_code といったフィールドが現在のチャンクの実際の文字列/API 呼び出しと直接一致しているかをまず確認する必要がある。

明日のやること

明日はデモセットをさらに作成する必要がありそうだ。

Godot チャンクに関連する JSONL、無関係 JSONL を複数作成し、Qwen が回答をどのように導き出すかを何度もテストする必要がある。1、2 回成功しただけで基準とするにはまだ早い。

特に次のケースをさらに確認する必要がある。

  • 関連 JSONL が複数混在したとき、Qwen が実際の根拠をうまく選択できるか
  • 無関係 JSONL がテーマ語だけ似ているとき 아니오 と正しく除外できるか
  • api_mapping と label_prototypes の違いを Qwen が文字列根拠ベースで正しく区別できるか
  • docs_chunks のような説明文書性の JSONL も同様の方法で検証可能か
  • Godot 3 のコードのように見えても JSONL 根拠がないときに任意のマイグレーションを行わないか

今日は全体的に抽象的な構造を実際の画面と入力フローに落とし込んだ日だった。頭の中ではすでに知っていると思っていたことも、実際にウェブで展開し、分割し、検索入力で表示するとずっと明確になった。

次のステップは実際の DB 検索と Qwen 検証を何度も繰り返し、このフローが揺らがないか確認することだ。