Astro・TS・Rustコード丸読みの罠｜SQLite階層索引で読込98%減の実測録

結論：全コード階層索引化で変わった実測値

まずは、ワークスペース内の全コードファイルおよび下書き資料（.astro 47 本、.ts / .mjs / .js 243 本、.rs 49 本、下書き .md 881 本の 計 1,220 ファイル・合計約 32.6MB、管理 15 文書を含め全 1,235 ファイル）を SQLite のユニバーサル階層インデックス（Schema v4.3）へ統合した前後の実測比較を示します（2026 年 11 月 9 日、RAM ディスク常駐の kb-search および gemini-gate にて実機計測）。

管理ファイル（GEMINI.md や TODO）を片付けたと思ったら、今度は .astro や .rs のソースコード側に 30KB や 160KB の大物がゴロゴロ隠れとったんじゃな！

そうなんです！しかもソースコードの場合は、単純に「キーワードで全文検索（SQLite FTS5）すれば済む」と思われがちなのですが、実際の AI の行動ログを追いかけると、コード特有の構造が原因で何度も手探り read_file が起きていたんですよ。

管理文書の次に潜んでいたコード丸読みの3大罠

前編の管理文書・TODO階層化記事を公開した直後、ワークスペース内の残りすべての拡張子を SQLite 上で棚卸ししたところ、ソースコードと技術資料に特有の 3 つの丸読み・ノイズ地雷 が見つかりました。

手探り7回！AstroのPropsとCSS混在の罠

1 つ目の罠は、Astro 公式のコンポーネント構文が持つ「1 ファイル多層構造」です。.astro ファイルは、先頭の --- で囲まれた TypeScript フロントマター、中央の HTML / JSX テンプレート、クライアント側 <script>、そして末尾の <style>（CSS）が 1 枚のファイルに同居しています。

実際に当ラボで 47 本ある .astro ファイル（計 748.4KB）を調べると、シミュレーター画面（glucose-exercise-simulator.astro：3,430 行・108.5KB）や記事レイアウト（BlogPost.astro：1,414 行・47.5KB）、折れ線グラフ（LineChart.astro：1,257 行・32.3KB）など、後半の何百行もが CSS スタイル定義で占められているファイルが多数ありました。

本日の稼働トランスクリプト（サブエージェント fe6fabc7 の生ログ）を確認すると、記事へ <BarChart> と <LineChart> を追加する際、AI は以下の手順を踏んでいました。

しかもこの時は 6 つのサブエージェント班を並列稼働させていたため、各班で同じ .astro ファイルへの手探り読込が重複発生していました。「このコンポーネントはグローバル登録済みか？」「Props は何行目か？」「テンプレートと <style> の境界は何行目か？」という地図さえ最初から SQLite にあれば、この手探り 7 連発は 1 回で終わるはずだったのです。

定数170件の壁と圧縮min.jsの検索汚染

2 つ目の罠は TypeScript（.ts）や設定ファイル（.mjs）、そして下書き .md における 「密度の偏り」 です。たとえばプロジェクト共通定数を集めた src/consts.ts（443 行・24.4KB）には、export const の単一行定義が 157 件 も並んだ後に、文字列置換や日付ソート用の重要な関数群が末尾（L375〜L442）に置かれています。これを見出しや要約なしで単純列挙するとアウトライン自体が 170 行に膨れ上がり、逆に全文検索だけに頼ると「どんな関数が入っているファイルなのか」が俯瞰できません。また、チャット履歴から抽出した技術資料 .md（881 本・計 28.1MB）も、これまでは rule 棚の対象外だったため、1.3MB（18,454 行）ある資料の見出しツリーを引けない状態でした。

3 つ目の罠が、圧縮済みバンドルファイル（*.min.js）の混入 です。workspace_files テーブルを拡張子別に集計したところ、メールビューア用フォルダに置かれていた marked.min.js（わずか 70 行なのに 39,903 バイト＝39.0KB）が 2 本（計 78.0KB）そのまま全文インデックスへ登録されていました。ミニファイされた JS ファイルは 1 行が数万文字の塊になっているため、一般的な英単語で code 検索や grep をかけた際にヒットすると、意味のない圧縮コードが大量に出力へ混入する原因になります。

外部依存ゼロ！全拡張子対応Rust解剖器の急所

ここで開発者が最初に思い浮かべるのは、「Tree-sitter のような構文解析ライブラリを言語ごとに組み込もうか？」というアプローチです。しかし、.astro・.ts・.tsx・.mjs・.js・.rs のすべてに対して外部 C パーサーをリンクすると、ビルド時間が跳ね上がるうえ、独自構文を持つ .astro の 4 層分離やプロジェクト固有のルーティング突合までは面倒を見てくれません。

そもそも AI エディタが read_file の範囲を絞るために欲しいのは、完全な抽象構文木（AST）ではなく「どの宣言・レイヤーが何行目から何行目まであり、どんな型引数を受け取るか」という正確な物理行番号マップ です。そこで今回も外部クレート依存ゼロを貫き、Pure Rust の標準ライブラリ（std）だけで動く決定論的コード解剖モジュール（code_outline.rs）を実装しました。

Astroの4層分離とMDX登録の自動突合

.astro ファイルを解析するうえで最も喜ばれる工夫が、「4 層分離」と「ルーティング側の mdxComponents 自動突合」の組み合わせ です。

パーサーはまず先頭の --- フェンス（テンプレートリテラルやブロックコメント内の --- は無視）を正確に特定して Frontmatter 層 を切り出し、その中身を TypeScript スキャナへ渡して interface Props の各フィールド要約や Astro.props の分割代入、内部ヘルパー関数の行番号を抽出します。続いて残りの領域から HTML / JSX テンプレート層、クライアント用の <script> 層（中身も JS として再帰解剖）、そして <style> 層（scoped か is:global かの属性判定に加え、内部の @media クエリの行範囲まで抽出）へと 4 分割します。

さらに同期および --outline 実行時には、記事描画の大元である src/pages/blog/[...slug].astro の mdxComponents オブジェクトを自動で読み取り、各コンポーネントが 「MDX グローバル登録済み（記事側での import 不要）」か「個別 import 必要」か をメタ情報として刻印します。これにより、AI がわざわざ [...slug].astro を別で read_file して確認する手間そのものが消滅しました。

正規表現やRust生文字列で括弧が狂わない工夫

「自前の軽量レキサで波括弧 { ... } の深さを数えて関数の終了行を出す」と聞くと、ベテランのエンジニアほど 「文字列や正規表現の中に { や " があったら一発で括弧カウントがズレるのでは？」 と心配されるはずです。

実は当ラボの実コードにも、素朴なパーサーを即死させる「意地悪な実例」がそのまま存在していました。たとえば astro.config.mjs の 64 行目には、Git 出力の引用符を剥がす rawPath.replace(/^"(.*)"$/, '$1') という正規表現リテラルがあります。JS / TS の正規表現 /.../ を認識できない単純なスキャナだと、正規表現の真ん中にある 1 個だけのダブルクォート " を「文字列の開始」と誤認し、それ以降のコードがすべて文字列扱いになって波括弧の階層が崩壊します。

また Rust の字句構造（The Rust Reference）でも、&'static str のようなライフタイムの単一引用符 ' を文字リテラルの開始と勘違いしたり、日本語の全角記号文字リテラル '：'（3 バイト UTF-8）や生文字列 r#"..."#、さらには ネスト可能なブロックコメント /* 外側 /* 内側 */ 外側 */ で深さが狂う落とし穴があります。これらを 1 件残らず無力化するため、レキサには以下の状態機械ルールを組み込みました。

なるほどねぇ！重たい外部ライブラリを入れなくても、「関数の始まりと終わりの行番号を狂わせないための急所」だけをしっかり押さえれば、標準機能だけでそんなに正確に切れちゃうわけね！

その通りです！しかも Rust コンパイラの無警告テスト（gemini-gate の自己診断テスト第 60・61 項）も通してあるので、未使用コードの放置や *.min.js のすり抜けが起きないかまで毎回自動で検証されています。

実機計測：160KBコードも3ミリ秒で丸裸に

完成したユニバーサル階層ナビゲーション基盤を実際に動かし、出力内容とミリ秒単位の応答速度、さらに実装中に見つけて潰した「思わぬ探索ボトルネック」の実測値を公開します。

全1220ファイル一括階層化の速度と削減率

引数なしで ./scripts/run_kb_search.sh tree を実行すると、わずか 5.61 ミリ秒 で管理 15 文書の状況に続けて、全コード・下書き拡張子の「ユニバーサル階層アウトライン棚」が表示されます。

=== ユニバーサル階層アウトライン棚（コード＆下書き全拡張子対応） ===
  • Astro コンポーネント/ページ (.astro)  :  47本 ( 748.4KB) | 4層・Props 490要素 (MDXグローバル登録:10本) -> `tree components`
  • TypeScript / JS / 設定 (.ts/.mjs/.js) : 243本 (1277.4KB) | 型・関数・定数 557要素                      -> `tree ts` / `tree mjs` / `tree js`
  • Pure Rust ツール基盤 (.rs)            :  49本 (2541.2KB) | 関数・構造体・impl 1278要素                  -> `tree rust`
  • 下書き・監査・技術資料 (.md draft)    : 881本 (  28.1MB) | 見出しツリー 18852節                        -> `tree drafts`

ここからたとえば kb-search tree LineChart.astro（5.71ms）または gemini-gate --outline LineChart.astro（2.75ms）を叩くと、1,257 行（32.3KB）あるファイルの中身を一文字も丸読みすることなく、以下の構造マップが即座に返ってきます。

■ src/components/LineChart.astro [.astro | 全1257行・32.3KB | 抽出要素:34 | MDXグローバル登録済(import不要)]
  [L1-L486] (layer) frontmatter — Astro Frontmatter (TS/Props) L1-L486
    [L10-L17] (type) ChartColor [export]
    [L19-L30] (interface) LineSeries [export] — name: string, values: (number | null | u…, unit?: string…
    [L44-L58] (props) Props [export] — title: string, subtitle?: string, labels: string[], series: LineSeries[]…
    [L60-L74] (props_init) Astro.props — 分割代入・既定値展開
    ...
    [L278-L419] (fn) computedSeries — 142行ブロック
  [L488-L832] (layer) template — HTML / JSX テンプレート (345行)
  [L834-L1256] (layer) style — <style> (scoped)
    [L905-L935] (media) @media (prefers-color-scheme: dark)
    [L1251-L1255] (media) @media (max-width: 600px)

これを見れば、「MDX グローバル登録済みだから import は不要」「Props の詳細を見たいなら 44〜58 行目の 15 行だけ を read_file すればよい」「ダークモードの配色を直したいなら 905〜935 行目の 31 行だけ を開けばよい」と一瞬で判断できます。また単一行定数が 157 件並ぶ consts.ts でも、パーサーが単一行定数ブロックを「L16-L51（33件）」「L54-L133（67件）」のように 4 行へ自動圧縮して表示するため、末尾のヘルパー関数（L375〜L442）が一目で分かります。

探索順の罠を潰して106msを2.7msへ短縮

実装直後のベンチマーク計測では、ひとつ面白い発見がありました。SQLite を経由せず直接ファイルを読んで解剖する gemini-gate --outline 側で、パスを省略して単体ファイル名だけで --outline LineChart.astro と叩くと 2.75 ミリ秒 だったのに、--outline scanner.rs と叩いた時だけ 106.65 ミリ秒 かかっていたのです。

原因を調べると、単体ファイル名から実ファイルを探すフォールバック処理が src/ ディレクトリを先頭から順番に再帰走査しており、tools/ 配下にある scanner.rs にたどり着く前に src/content/blog/ 配下の約 700 個の記事サブフォルダを毎回すべて開いていた ことによる I/O ロスでした。

そこで、「拡張子が .rs なら tools/ を最優先で走査し、かつ .astro や .rs の単体名探索では公開記事フォルダ（blog/）をスキップする」というわずか数行の探索順最適化を入れたところ、3,844 行（160.3KB）の scanner.rs でも 106.65ms → 2.74ms（約 39 倍高速化） へと一気に短縮されました。推測で満足せず、必ず全拡張子で実機ミリ秒を測ることの大切さを改めて実感した瞬間です。

ローカル索引を快適化する開発機材と時間単価

ここまで規模が大きくなると（公開記事・管理文書・下書き・システムコードの全見出し約 2.7 万節＋コードシンボル 2,325 個＋会話履歴 DB）、クラウド側の AI に毎回ファイルを読ませて探させるよりも、手元のローカル母艦のメモリ（RAM）上に SQLite と Rust バイナリを常駐させて数ミリ秒で捌く設計 が圧倒的な威力を発揮します。

当ラボのように 16GB の RAM ディスクと SQLite のメモリマップ（mmap_size 計 1.5GB）、さらに Astro の並列ビルドやブラウザ検証を同時に余裕で回すなら、これから選ぶ現行母艦としては 64GB ユニファイドメモリ構成の『Apple Mac mini（Pro 系チップ搭載モデル）』 が最もバランスの良い投資になります。Apple 公式の Mac mini 仕様ページでも確認できる通り省スペースかつ静音性に優れ、仮に初期投資が約 30 万円前後としても、毎日 8 時間・5 年間（1,825 日）使い倒せば 1 日あたり約 164 円（1 時間あたり約 21 円） の快適コスト（推論・試算）です。メモリ不足のスワップ待ちや AI クオータ上限で作業が止まる損失を考えれば、十分すぎるお釣りが来ます。

Apple Mac mini（M4 Pro 等 Appleシリコン Pro系チップ・64GBユニファイドメモリ構成）

Amazon楽天市場Yahoo!

また、数万節の階層インデックスを蓄えた _local_db/knowledge.sqlite や日々のスナップショットを高速にバックアップ・持ち運びする外部ストレージには、Thunderbolt 3（最大 3,000MB/s）と USB 3.2 Gen 2 の両規格に対応した高耐久モデル 『SanDisk Professional PRO-G40 SSD』 が頼りになります。防塵防滴・耐衝撃ボディで放熱性が高く、たとえば 2TB〜4TB クラスを 5 年間（1,825 日）使えば 1 日あたり約 25〜40 円前後（推論・試算）で、大切なコード資産とローカル DB を一瞬で退避できます。

SanDisk Professional PRO-G40 SSD 4TB / 2TB (Thunderbolt 3 & USB 3.2 Gen 2 両対応)

Amazon楽天市場Yahoo!

まとめ：全コード階層索引を作るコピペ指示書

公開記事、ルール定義書、TODO 台帳、JSON、そして今回の .astro・.ts / .mjs / .js・.rs・下書き .md まで階層アウトライン化が完了したことで、ワークスペース内から「AI が中身を手探りで丸読みしないと構造が分からないファイル」がついにゼロになりました。

ご自身の開発環境にこの「全拡張子対応・コード階層 SQLite ナビゲーション」を導入する際も、人間が正規表現や字句解析の境界バグと格闘する必要はありません。ただし、軽量モデルに任せると正規表現リテラルやコメント内の波括弧処理を省略して行番号ズレを起こしやすいため、必ず 『Gemini 4 Argon』 または同等以上の最上位推論モデルを選び、以下のプロンプトをコピー＆ペーストして事前調査から進めてみてください。

家の見取り図があれば、おやつが隠してある引き出しまで一直線でトコトコ行けるニャ。全部の部屋をひっくり返して探すのはもう卒業して、サクッと仕事終わらせて撫でるでちぃ！

管理文書の目次化とあわせてソースコード側の「行番号の地図」もローカル SQLite に持たせておくと、AI エディタの動きが見違えるほど軽快になります。ぜひ手元のプロジェクトでも試してみてください。