はじめに
フロントエンドのコンポーネントライブラリを保守しています。AI コーディングアシスタントをチームに浸透させようとしたとき、3 つの壁にぶつかりました。
幻覚（hallucination）：AI がコンポーネントの API やプロパティを「それっぽく」でっち上げる
Token コストの肥大化：プロジェクト全体を毎回プロンプトに突っ込むと入力 Token が爆発する。2026 年 6 月に GitHub Copilot が従量課金へ移行する関係で、標準的な使い方でもプラン枠を超えるリスクがあった
ナレッジが個人に閉じる：AI ツールが各自バラバラに使われ、ノウハウがチーム・組織に蓄積されない
この 3 つを「同じ 1 つのアーキテクチャ」で同時に解くことを設計目標にしました。
アーキテクチャ：3 層構成
Project Repo → MCP Server → LSP Repo
（プロジェクト） （検索の核・不変） （言語別パーサ）
MCP Server：FastAPI + uvicorn によるローカルサービス。完全オフライン動作で、外部 API へのデータ送信は一切なし
検索の核は MCP Server に集約し、言語スタックへの非依存を実現
言語ごとの差分は LSP Repo 側のパーサに閉じ込める（後述の拡張性につながる）
検索エンジン：ハイブリッド + 意図感知降権
純粋なベクトル検索だけだと、コードや技術ドキュメントでは精度が伸びません。そこで以下を組み合わせました。
語彙検索（lexical）：シンボル名の完全一致に強い
セマンティック検索：bge-m3 を ONNX Runtime でローカル推論（1024 次元）
意図感知降権（intent-aware deweighting）：クエリの意図に合わない候補のスコアを下げる
bge-m3 を ONNX 化してローカルで回すことで、埋め込みのために外部 API を叩く必要がなくなり、コストとデータ持ち出しの問題が同時に消えます。
AI Agent Skills：3 スキル設計
AI エージェントから叩く窓口を 3 つに絞りました。
Skill役割search_kbナレッジ検索describe_kb記述・説明の取得update_kbナレッジ更新
自動同期：git hook → 増分ベクトル再構築
企業ナレッジ基盤が腐る最大の理由は「誰も更新しない」ことです。これを仕組みで潰しました。
git hook をトリガに、自動で増分ベクトル再構築を走らせる
つまり「コードを書く＝ナレッジ基盤が更新される」。更新は人間の自律ではなく、ツールの自動的な副産物になる
実測ベンチマーク
検索精度 P@1 = 90%以上（bge-m3 混合モード）
LLM への入力 Token を 80%以上 圧縮
検索遅延 約 50ms/query（体感閾値より 1 桁低い）
品質テスト 5 套件すべて通過（シンボル精確命中／隔離性／Barrel 導航／フィールド型検索／公開シンボル網羅）
完全プライベート・オフライン（外部 API・データ送信なし）
拡張性：プラガブルなパーサ
言語スタックへの非依存は「設計思想」だけではなく、実装パスがあります。
MCP Server（不変）
ハイブリッド検索 + bge-m3 + 意図降権
│
┌────┼────┬────────┐
Flutter------TS-------Python -------------Java/etc
(本番) (設計) (設計) (設計)
新しい言語に対応するには パーサを 1 つ足すだけで、検索の核は触りません。実測済みのものは「本番」、設計レベルで対応済みのものは「設計」と区別しています。
まとめ
外部 API に依存せず、混合検索で精度を担保し、git hook で維持コストをゼロにする——この 3 点が「使われ続けるナレッジ基盤」の条件だと考えています。