結論：管理文書のSQLite階層化で変わった実測値

まずは、プロジェクト直下の管理文書群（ルール定義・公理集・整合性マップ・進捗 TODO など全 12 文書、計約 886KB）を「従来の全文 1 レコード格納＋手探りファイル読込」から「SQLite 見出し階層ツリー＋構造化 TODO ナビゲーション」へ切り替えた前後の実測データを比較表で示します（2026 年 11 月 9 日、RAM ディスク常駐の Pure Rust バイナリ kb-search / gemini-gate にて実機計測）。

作業シーン	従来の動作（ベタ格納＋手探り読込）	階層ナビ導入後（tree / todo）	読込量・速度の変化
管理 12 文書の全体棚卸し	各ファイルのサイズ・行数を個別に確認	kb-search tree で 12 文書の行数・節数を一発一覧	応答 5.03ms （約 1.2KB の一覧出力のみ）
GEMINI.md（約 333KB）の章特定	検索語が曖昧だと数百行ずつ read_file で探索	tree GEMINI.md → tree 6.7 で節内トピック行番号まで直行	応答 4.65〜11.88ms （読込量を 95% 以上圧縮）
整合性マップ（114.2KB）の鎖確認	107 行しかないため read_file 1 回で 114KB 全量流入	tree cmap で全 50 論理鎖の行番号と連動記事数を即答	応答 4.71ms （114KB の丸読み暴発を完全遮断）
TODO（83.0KB）への末尾追記	最終番号と挿入位置を探して後半数百行（数万バイト）を読込	todo --tail が最終番号 #230 と追記 6 行範囲を即答	応答 3.57〜4.37ms （85,002B → 約 600B：約 99% 減）
特定の TODO 番号（例：#120）照会	ファイル内を検索して周辺ブロックを広めに読込	todo 120 で該当項目の状態・スラッグ・行番号を即答	応答 2.34ms （ファイルオープンすら不要）

灯台下暗し！688記事の裏で886KBが丸裸だった罠

なぜ「全文検索インデックス（SQLite FTS5）に入れてあるから大丈夫」と思い込んでいた管理ファイル群が、実はトークン消費の隠れた温床になっていたのか。実際の会話データベースを集計して浮かび上がった 2 つの構造的な罠を共有します。

会話2661件の集計で判明した本当の最頻参照ファイル

当ラボでは、公開記事（計測時点 688 記事、現在公開 707記事）と並行して、ルール定義書（GEMINI.md ＋分離公理マスター GEMINI_AXIOMS.md で合計 1,311行・約548KB）、全体整合性マップ（CONSISTENCY_MAP.md：114.2KB）、3 冊の進捗管理ロードマップ（TODO_ROADMAP.md・TODO_REVIEW_ROADMAP.md・TODO_NEW_REVIEW_TOPICS.md：計約 207.6KB）などの管理文書を運用しています。

手元のチャット履歴データベース（conversations.sqlite：全 2,661 スレッド、うち Antigravity IDE での開発セッション 1,798 本）を対象に、各管理ファイル名が何本のスレッドに登場しているかを conversations_fts で実測集計した結果が以下です。

※上記の件数にはエディタの自動フック通知によるファイル名言及も含まれますが、それを差し引いても、公開記事 1 本あたりの編集登場回数（平均数回〜十数回）とは比較にならない 「ほぼ毎回のセッションで読み書きが発生する一等地」 であることが一目で分かります。

ところが従来の知識データベース（knowledge.sqlite）の設計を確認すると、公開記事（.mdx）は見出し単位の article_sections テーブルへ綺麗に階層分割されていたのに対し、これら 12 本の管理文書は workspace_files テーブルに 「ファイル 1 冊＝巨大な 1 行（ベタ文字列）」 として格納されているだけでした。さらに見出し一覧を出す --outline コマンドに至っては、src/content/blog 配下の記事しか受け付けず、GEMINI.md を指定すると「記事が見つかりません」とエラーで弾いてしまう状態だったのです。

検索語が決まらない場面で全文検索は無力になる

「でも workspace_files_fts で全文検索できるなら、必要な行だけ引けるのでは？」と疑問に思われるかもしれません。実際に運用してみると、全文検索（キーワード一致）だけでは絶対に解決できない 2 つの場面 がありました。

1 つ目は、「検索すべきキーワード自体が存在しない構造操作」 です。たとえば新しい記事を書き終えて TODO_REVIEW_ROADMAP.md（441 行・85,002 バイト）の「新規作成レビュー記事」セクション末尾に次の通し番号で 1 行追記したい場面を考えてみてください。末尾に何番の記事が書かれているかは開くまで分からないため、検索ワードの打ちようがありません。結果として AI は「200 行目〜441 行目」のように後半をごっそり read_file でめくることになり、1 回の追記位置確認だけで数万バイトのテキストを読み込んでいました（しかもセクション見出しの表記は「全 228 記事」のまま、実際の末尾は #230 まで進んでいたため、見出しの数字を信じて書くと番号が重複する罠まで潜んでいました）。

2 つ目は、「行数は少ないのに 1 行が超長文なマップファイル」 の罠です。CONSISTENCY_MAP.md は全体で たった 107 行 しかありませんが、各行に十数本の関連ファイルパスと公理定義が並んでいるため、ファイルサイズは 116,974 バイト（114.2KB） もあります。「107 行なら短いから read_file で全部読もう」と AI が開いた瞬間、1 回のツール呼び出し上限（46,080 バイト）に激突して途中切断され、続きをめくるうちに 114KB 丸ごとがコンテキストへ居座り続けていたのです。

管理文書における『従来のベタ格納＋手探りめくり』と『SQLite階層ナビ基盤』の構造差

従来の盲点（クオータ浪費）

1ファイル1行格納＋手探りRead

• 管理12文書（約886KB）が workspace_files に丸ごと1行で格納され、章構造が見えない
• TODO末尾の通し番号や追記行を探すたび、83KBのファイルを数百行めくって探索
• 107行で114KBある整合性マップを不用意に開き、毎ターンの履歴再送コストが増大

今回の解決策（読込99%削減）

見出し木＋TODO構造化テーブル

• 全12文書の見出し197節を親子階層付きの doc_sections テーブルへ決定論的に分解
• 全812件のTODO項目を状態・番号・行範囲付きの todo_items へ構造化し追記行を即答
• 必要な6〜20行だけをピンポイントで read_file でき、応答も2〜12ミリ秒で完結

実装解剖：見出し木とTODO台帳のSQLite設計

この「灯台下暗し」を根絶するため、外部クレート依存ゼロの Pure Rust 製検索エンジン（kb-search）に専用の階層解剖モジュール（doc_nav.rs）を新設し、knowledge.sqlite へ 2 つの構造化テーブル（doc_sections と todo_items）を統合しました。実装時に特にこだわった技術的急所を 2 点解説します。

コード枠と凡例を除外する決定論パーサーの工夫

Markdown 文書を見出し（#）やチェックボックス（- [ ] / - [x]）で機械的に分割しようとすると、実務では必ず 「コードブロック内の誤爆」 と 「書き方見本（凡例）の混入」 という 2 つのバグを踏みます。

たとえば GEMINI.md や REVIEW_POST_RULES.md の中には、解説用のシェルスクリプト例（# コメント行）や Markdown 記法サンプルが大量に含まれています。これを単純な行頭一致で拾ってしまうと、シェルのコメントまで「H1 見出し」として誤登録され、階層ツリーが崩壊します。そこでパーサー側には以下の 3 重の境界防御を組み込みました。

さらに、GEMINI.md の 1 つの節（たとえば 15,000 字を超える 6.7 節）のように 1 セクション自体が大きい場合に備え、特定の節へ絞り込んだ際（kb-search tree 6.7）には その節の内部にある太字の箇条書き項目（- **項目名**:）の物理行番号まで第 4 階層としてオンデマンド展開 する仕組みも入れています。

棚一覧から行番号まで3段階で降りるナビの流れ

コーネル大学等の研究チームが発表した『DecisionRAG』論文（arXiv:2610.35868）（数理の詳細は『DecisionRAG』の仕組みと節約術の解説記事をご参照ください）では、軽量 AI モデルの 1 パス確率計算で階層ツリーを辿っていましたが、手元の管理文書であれば AI の推論すら 1 トークンも使わず、ローカル SQLite のクエリだけで数ミリ秒のうちに第 1〜第 3 階層を降りる ことができます。

管理文書とTODOを丸読みゼロにする3段階SQLiteナビゲーション

第1階層

文書棚・全体統計

kb-search tree や todo を叩き、管理12文書の行数・節数や未完了タスク数を1KB強で確認します。

5.0msで俯瞰

第2階層

章ツリー・末尾特定

tree 6.7 や tree cmap、todo --tail で目的の節や追記箇所の物理行番号を1行単位で特定します。

3.6〜11ms

第3階層

数行だけRead・編集

特定した StartLine〜EndLine（わずか6〜30行）だけを read_file で開き、最小トークンで安全に編集します。

実際に kb-search todo --tail を実行すると、わずか 3.57 ミリ秒 で以下のように「現在の最終項目」「次に振るべき通し番号」「read_file に渡すべき最小行範囲」がそのまま返ってきます。

■ TODO_REVIEW_ROADMAP.md [全441行・83.0KB]
  ├─ セクション: 🚀 新規作成レビュー記事 (計230件)
  │    最終項目: [L249-L249] #230 review/decisionrag-...
  └─ 👉 次の通し番号: #231 | 追記時は read_file(StartLine=247, EndLine=252) だけで完結

これまで 85,002 バイトあるファイルの後半を手探りで読み込んでいた作業が、247 行目〜252 行目の たった 6 行（約 600 バイト）を読むだけ に変わり、読込データ量は 約 99.3% 削減 されました。同時に gemini-gate --outline 側も、公開記事の自動修正（--fix）の安全境界は維持したまま、プロジェクトルート直下の正規 .md ファイル（GEMINI.md や TODO_*.md）のアウトライン抽出を 2.92 ミリ秒 で返せるように拡張しています。

生ログ計測：トークンと応答秒数の変化

コマンド単体のミリ秒計測だけでは、「実際の AI セッション全体でどれだけトークンと待ち時間が減ったのか？」までは見えません。そこで当ラボの計測コマンド（kb-search brain および token-dashboard）を使い、生の稼働トランスクリプト（transcript.jsonl）から導入直前と導入直後の API トークン消費量・ステップ数・所要秒数を直接計測しました。

手探り空振り10回ゼロ化とJSON読込撤廃

まず、同日 1 時間前の導入直前セッションと、階層ナビ基盤を導入した直後のセッションで、まったく同じ「進捗管理表への追記・整合性確認」と「デプロイ後の Playwright 実機ブラウザ検証」がどう変化したかを突き合わせた生ログ実測値が以下です。

計測対象フェーズ（生ログ比較）	導入前の実測（手探りRead・毎回JSON確認）	導入後の実測（階層ナビ＋定型引数コア化）	実測された削減効果
管理文書・TODO の追記位置探索	5 ステップ・手探り read_file 計 10 回 （空振り連発＋114KB 切断で 計 44,591 tok 流入）	todo --tail（3.57ms）→ 1 ステップ・計 13 行のみ （直後ステップの新規入力 4,694 tok ※他 2 記事確認含む）	手探り空振り 10回 → 0回 （流入トークン 約 89.5% 減）
Playwright 実機検証（JSON 引き締め）	mcp/playwright/*.json を毎回 4 本読込＋保存先エラー再実行で 6 ステップ・9 ツール・70 秒	定番 5 ツールの確定引数を常時コアへ昇格し 3 ステップ・3 ツール・40 秒（操作中の新規入力 計 5,079 tok）	JSON 読込 4回 → 0回 （検証ステップ 50% 減・時間 43% 短縮）
データ用 .json（705 行）の行特定	scripts/data/*.json が索引外で丸読み対象	workspace_files へ収録し kb-search code で即答	応答 3.97ms （20.1KB 丸読みを回避）

SQLite階層ナビ＆JSON引き締め導入前後の流入トークン比較

生稼働トランスクリプト（transcript.jsonl）による各フェーズの実測トークン量

TODO探索流入量:-89.5% (44,591→4,694 tok)手探り・JSON読込:計14回 → 0回

管理文書・TODO探索［導入前：手探りRead 10回］5ステップ・空振り連発＋整合性マップ114KB切断で大量流入

44,591 tok手探り空振り 10回

管理文書・TODO探索［導入後：todo --tail 3.57ms］1ステップ・計13行のみピンポイント読込（※他2記事確認含む）

4,694 tok-89.5% 削減・空振り0回

Playwright実機検証［導入後：定番5ツール常時コア化］3ステップ・3ツール・40秒で完結（スキーマJSON読込 4回→0回）

5,079 tokステップ50%減・時間43%短縮

Playwrightスキーマ4本読込［導入前の毎ターン底上げ分］導入前は6ステップ・9ツール・70秒にわたり毎ターン履歴へ加算

約2,050 tok/回導入後は 0 tok（完全撤廃）

データ用 .json（705行・20.1KB）行特定［導入後］workspace_files収録＋kb-search codeで行番号を即答（応答 3.97ms）

丸読み 0 tok（3.97ms）20.1KB丸読みを回避

生トランスクリプトを 1 行ずつ解剖して判明したのは、管理文書（.md）だけでなく 「隠れた JSON ファイルの毎回読込」 も同じ構造のクオータ泥棒になっていた事実です。遅延ロード型の MCP ツール（Playwright ブラウザ検証など）を使うたび、AI が毎回スキーマ定義（browser_*.json 4 ファイル）を read_file で開き、それだけで以降すべてのターンのキャッシュ読込ベースラインが 約 2,050 トークン 底上げされていました。

そこで管理文書の階層化とあわせて、以下の 「JSON 3 点引き締め」 を同時実装しました。

直近1万2千コールで見えた応答10秒短縮の法則

「でも AI には KV キャッシュ（過去履歴の再利用割引）があるから、一度ぐらいファイルを丸読みしても大差ないのでは？」と思われるかもしれません。直近 7 日間（2026 年 11 月 3 日〜11 月 9 日：全 365 会話・12,162 API コール、総プロンプト処理 15.73 億トークン、KV キャッシュ有効率 91.89%）の全ステップをバケット集計すると、丸読みが 「毎ステップの待ち時間（TTFT）」 を直撃していることが数字で証明されました。

1ステップあたりの新規（Fresh）入力帯	サンプル数	1ターン平均応答秒数	中央値（P50）	現場での体感差
2,001〜5,000 tok（ピンポイント検索帯）	2,133 回	17.93 秒	11.01 秒	階層ナビ＋数行 Read でサクサク進む状態
5,001〜15,000 tok（中規模 Read 帯）	971 回	20.97 秒	14.02 秒	複数ファイルの周辺ブロックを読んだ状態
15,001〜40,000 tok（丸読み 1〜2 本帯）	427 回	28.44 秒	15.79 秒	管理文書や長文記事の丸読みで 平均 +10.51 秒遅延

1ステップの新規（Fresh）入力トークン帯別のAI応答時間

直近7日間・全12,162 APIコールにおける1ターン平均応答秒数と中央値（P50）

ピンポイント帯平均:17.93秒丸読み時の平均遅延:+10.51秒 (28.44秒)

1ターン平均応答時間(秒)中央値（P50）(秒)

つまり、管理ファイルや JSON の丸読みを 1 回防いで「ピンポイント検索帯（5,000 トークン以下）」に収めるだけで、その 1 ステップあたりの AI 応答時間が平均 10.51 秒も速くなる のです。

実際に日次推移を見ても、11 月 3 日から 11 月 9 日の 1 週間で公開記事数は 575 本 → 692 本（約 20% 増）、ルール総規模は 404.9KB → 521KB（約 29% 増）へと拡大したにもかかわらず、前日（11 月 8 日）と本日（11 月 9 日：1,110 コール）の比較で以下の改善が記録されています。

ローカル索引を待ち時間ゼロで回す母艦と費用対効果

このように、クラウド側の AI に毎回巨大なテキストを送って考えさせるのではなく、「手元の PC 側で SQLite の階層インデックスと Rust バイナリを常駐させ、AI には数行の結論と行番号だけを渡す」 アーキテクチャへ切り替えると、日々の開発テンポと利用枠の持ちが劇的に変わります。

特にローカル SQLite を OS メモリマップ（mmap_size：知識 DB に 512MB、会話履歴 DB に 1GB）で RAM 上へ常駐させ、さらに 16GB の RAM ディスク上でビルドキャッシュとネイティブバイナリを並列稼働させる場合、最も効いてくるのが 手元の母艦 Mac のメモリ容量（64GB 以上） です。

これから長く使える現行の開発・執筆母艦を選ぶなら、64GB ユニファイドメモリ構成の『Apple Mac mini（Pro 系チップ搭載モデル）』 が最有力候補になります。初期費用として仮に約 30 万円前後かかったとしても、毎日使う仕事道具として 5 年間（1,825 日）で割れば 1 日あたり約 164 円（推論・試算、1 日 8 時間稼働なら 1 時間あたり約 21 円）です。Anthropic 公式コスト指針にある Claude Code の平均消費額（稼働 1 日約 13 米ドル＝約 2,000 円前後）や、メモリ不足のスワップ待ちで毎日奪われる自分の時間を考えれば、他人の目を気にする見栄の消費とは正反対の「最も確実に元が取れる環境投資」になります。

また、育て上げた SQLite データベース（_local_db/knowledge.sqlite や数百 MB の会話履歴 DB）とプロジェクト資産を Time Machine や定期スナップショットで安全に守る退避先には、USB 3.2 Gen 2（最大 1,050MB/s）対応のコンパクトな外付け SSD 『Crucial X9 Pro For Mac』 が重宝します。2TB モデル（実勢約 2.5 万円前後）を 5 年間（1,825 日）使えば 1 日あたりわずか約 14 円（推論・試算）で、万一のディスク障害から数年分の知見を丸ごと保護できます。

まとめ：管理文書を階層索引化するコピペ指示書

今回の検証で改めて痛感したのは、「立派な検索システムを作っても、毎日いちばん開く足元のルール書や TODO リストが丸読み状態なら、そこからトークンとクオータが漏れ続ける」 というシンプルな事実でした。

手元のプロジェクトで肥大化した管理文書や TODO リストを SQLite 階層化する際も、人間がゼロからパーサーや SQL を手書きする必要はありません。軽量モデル（Flash 系など）を使うとコードフェンス除外などの安全境界を読み飛ばす恐れがあるため、必ず 『Gemini 4 Argon』 または同等以上の最上位推論モデルを選び、以下のプロンプトをコピー＆ペーストして事前調査と設計合意から進めてみてください。

記事やソースコードの検索基盤を作った後は、ぜひ一度「毎日 AI が一番開いている管理ファイルはどれか？」を点検し、丸読みゼロ・ミリ秒応答の快適な開発環境へ仕上げてみてください。