2026-06-26 振り返り | idea_world

今日は source-to-AST 入力フローを文書化しながら、 “ソースコードを実際にどのように LLM の判断まで渡すか” を整理した。

単に文書だけを書く日ではなかった。Godot 関連のデータ収集もリアルタイムで同時に進めているため、文書が抽象的な設計図だけに終わってはいけなかった。現在収集されているデータが実際にどの経路をたどり、どの単位で分割され、どのリクエストにつながるべきかを確認する基準が必要だった。

なぜこの設計を先に整理しようとしたのか

この設計を先に文書化しようとした理由は、以前の作業で AI がコードを奇妙に書いたり、リクエスト範囲を任意に変えたりする不安があったからだ。

特に Markdown 全体を送る必要があるのに、冒頭の一部だけ送るように実装したり、私が望まないハードコーディングを入れたり、ファイル全体を見る必要があるのに “核心コード” だけを選んで送る方式で流れる可能性が常に気になっていた。

そこでコードを書き始めるよりも、まず “AI にどんなリクエストをすべきか”、 “ファイルをどの単位で展開すべきか”、 “AST Parser には何を入れ、Retriever には何を直接入れるか”、 “LLM 呼び出しにはどんな組み合わせが必要か” を文書で固定しようとした。

最近は実装そのものよりも、AI に指示をどうすれば意図が歪まないかを常に考えるようになった。同じ要求でも範囲をどう固定し、どの表現を禁じ、どの証拠を確認させるかによって結果が大きく変わる。

今回の文書は単なる開発計画書というより、今後 AI に実装を任せる際にリクエストがぼやけないようにする基準線に近い。AI が任意に入力を削減したり、核心コードだけを選んで送ったり、要求していないファイルを修正しないようにするために、まず考えを整理したものだ。

今日の基準

ソースコードは # <相対パス>/<相対パス> 形式のヘッダーで展開する方式が必要だと考えた。このヘッダーの目的はプロンプトに装飾として入れるためではなく、ファイルがどのパスから来て、以後どの断片に分割されて Retriever に渡るかを追跡するためだ。

最初から私が考えた方向は、GitHub リポジトリをパス順に展開し、除外するファイルは除外するが、何が除外されたかを Web UI やログで見えるようにする構造だった。その後、残ったファイルを読み取れる単位に分割し、各断片がどの元ファイルから出たものかを継続的に追跡すべきだと考えた。

文書化の過程で AI が繰り返し誤解した点は “全ファイルを一度に送るか、核心コードだけ送るか” といった二分法だった。私が考えたのは、ファイルをパス基準で展開した後、断片単位で順序立てて切り分けて送るフローだ。

私の基準では .gd ファイルが AST Parser に入る対象だ。AST Parser は .gd 内の a 関数、b 関数、c 関数、d 関数のようにパース可能な単位を順番に切り出す必要がある。関数単位が曖昧な場合はコード断片単位で順番に切り出して送ればよい。重要なのは “核心関数だけを任意に選ぶ” ことではなく、元の順序とパスを維持しながら断片化し、その断片が Retriever に渡る過程を追跡することだ。

逆に .md のように今回のソースコード分析で除外することにしたファイルは除外リストに入れる必要がある。重要なのは除外された事実が消えてはならない点だ。どのファイルがどの基準で除外されたかを Web UI やログで示す必要がある。除外しないテキスト系設定ファイルがある場合は、AST Parser を通さずに行、段落、key-value、node/resource/connection などの単位に分割して Retriever に直接入れる方が自然だ。

整理すると現在のフローは次に近い。

repository path order
  -> "# <relative/path>" file expansion for tracking
  -> excluded file list visible in UI/log
  -> .gd files to AST Parser
  -> AST Parser emits ordered function/code chunks
  -> excluded files are recorded with reason
  -> non-.gd allowed text/config files emit ordered chunks
  -> each chunk goes to Retriever with source path metadata
  -> prompt + current chunk + retrieved evidence
  -> LLM judgment
  -> validation
  -> accumulated project-level result

AI 解釈を修正した部分

途中で AI が repository_file_manifest のような別個の構造を作ったが、これは私が考えていた方向とは違った。必要なのは別個の manifest リポジトリではなく、# <相対パス> ヘッダーで展開したファイルの流れを基準に、どのファイルが除外され、どのファイルがどの断片に分割され、その断片が Retriever にどの順序で入ったかを追跡することだ。

バイナリやアセットも「読み込まない」と整理すると不自然だ。重要なのは元の bytes を LLM に入れないということであり、そのファイルがプロジェクトの判断から完全に消えるという意味ではない。.tscn、.import、README のようなテキスト断片の中にアセットパスが出てくる場合は、その断片を基準に判断すればよい。

もう一つ必要だと感じたのは送信デバッグだ。AI が .gd ファイルから核心関数だけを選んで送るような流れではいけない。# <相対パス> で展開したファイルが AST パーサでどの関数／コード断片に分割され、そのうちどの断片が何番目に Retriever に渡されたかを diff や sha256 のような手法で確認できる必要がある。

PR レビューを見て整理した点

PR レビューを見ながら llm_judgment_request が文書内で二回異なる定義になっている問題が浮かび上がったと感じた。一方は chunk_text、chunk_kind、retrieved_evidence を中心にしており、もう一方は chunk_code、surrounding_context、judgment_contract まで含んでいた。

このように同じリクエストオブジェクトが文書内で異なる定義になると、後で実装するときにも揺らぎが生じるだろうという考えに至った。リクエストスキーマは一つに統一すべきだ。特に AST chunk と direct retrieval chunk を区別するには chunk_kind が必要で、LLM の判断を検証するには retrieved_evidence と judgment_contract も併せて整理されるべきである。

Qwen のレビューでは README リンクや 25 日の文書に関する誤字、リンクなどの意見も出たと確認した。しかし、25 日の文書や workflow が PR diff に入ったのは私が意図した作業ではなかった。AI が任意に変更を加えたものが混ざっており、私はそれを発見した後に元に戻すよう要求した。

範囲が混在した問題

本日の PR diff で 25 日の文書と .github/workflows/qwen-code-pr-review.yml が入っていることに気付いた。これは私が要求した変更ではなかった。AI が任意にファイルを変更または削除したように見え、PR 画面では次のファイルが変更または削除されたように表示された。

.github/workflows/qwen-code-pr-review.yml
docs/observations/2026-06-25-qwen-markdown-classification-observation.md
docs/retrospectives/2026-06-25-source-analysis-scoring.md
docs/roadmaps/2026-06-25-qwen-pr-review-workflow.md

そこでその変更を元に戻すよう要求した。その後、これらのファイルは origin/main 基準で復元され、PR diff は README.md と docs/roadmaps/2026-06-26-source-to-ast-input-flow.md を中心に整理された。

この過程を見て、AI に文書作業を任せるときも変更範囲をまず強く固定すべきだという考えに至った。振り返りやロードマップ文書を書く作業もコード変更と同様に PR 範囲を管理しなければならない。

本日の結論

本日再確認した核心は「パス別に展開したファイルがどの基準で除外され、どの断片に分割され、その断片がどの順序で Retriever と LLM の判断に渡るか」だった。全ファイルを一度に入れるわけでもなく、核心コードだけを任意に選ぶわけでもない。

現在の基準は次の通りに定める。

ファイルは # <相対パス> ヘッダーで展開し、このヘッダーは元のパスと断片追跡用に使用する。
除外したファイルはウェブ UI やログで確認できる必要がある。
.gd は AST パーサに送り、AST パーサが関数やコード断片を元の順序で作成する。
.md のように除外することにしたファイルは除外リストに残し、ウェブ UI やログで確認できる必要がある。
除外しないテキスト系設定ファイルは AST を経由せず、行、段落、設定ブロックといった単位で断片化する。
各断片は source path、chunk order といった追跡情報を持ち、Retriever に渡される。
LLM 呼び出しは プロンプト + 現在の断片 + Retriever 検索結果 単位で複数回実行する。
プロジェクトの判断は最初から複数断片の判断結果が蓄積された後でなければ可能でないと見ていた。

データ収集は継続中である。したがって今後の文書は単なる「妥当なアーキテクチャ」ではなく、実際の収集データがどのように入り、どのように検証されるかを確認する基準でなければならない。