はじめに

前回の記事で、MCP × bge-m3 のナレッジ基盤を作った話を書きました。ただ、技術的に動くことと、実際にチームで使われることは別問題です。この記事は「動く」を「使われる」に変えるための設計の話です。

ツールが死ぬ理由は「導入摩擦」

ツールの一番多い死に方は、**「みんな良いと言うが、誰も使わない」**です。プラグインのインストール、MCP の設定、ナレッジ基盤の接続——どこか一箇所でも面倒だと、ユーザーは「いいね、今度試す」で止まり、二度と試しません。
なので勝負どころは「説得」ではなく、導入摩擦をほぼゼロにすることです。

三層に解耦する

設計の背骨は、更新頻度の違うものを 3 層に分けて疎結合にすることです。
層中身更新頻度コンテンツ層ナレッジ（md）+ git高い（規範が変わるたび）能力層MCP + パーサ低いアクセス層VSCode プラグイン低い
ポイントは「プラグイン更新」と「ナレッジ更新」を絶対に結合させないことです。規範を微修正するたびにプラグインを再リリースしていたら、運用が破綻し「ゼロ設定運用」が崩れます。プラグインは起動時に最新のナレッジ版本を自動で取りに行く設計にして、ナレッジが変わってもユーザーは何もしなくていい状態にします。
ゼロ設定 = 「入れたら即使える」
「ワンクリックインストール」で本当に効くのは、インストールの一瞬ではなく、入れた後に何の設定もいらないことです。

API キーを入れない
モデルを選ばない
プロジェクトパスを対応づけない

「入れたら即使える」——これが外部ユーザーが本当に使ってくれるかどうかの境界線です。

はじめにmd + git をナレッジと意思決定記録の両方に使う

ナレッジ源を md、版本を git で管理。規範・トークン・コンポーネント文書の変更がすべて diff・履歴・ロールバック可能になる
「ナレッジ基盤が更新された」が git 上の 1 回の更新として明確に追える
意思決定の記録も md にして、ナレッジと同じ版本管理に載せる。記録が別管理にならない

MCP はローカルプロジェクトのナレッジ基盤も担う
VSCode プラグインと MCP は役割が違います。

プラグイン：コードを書きながら規範を引く／コンポーネントコードを生成する
MCP：AI エージェントに「このプロジェクトのローカル文脈」を理解させる

両者は別の使い方を担うので、両方やるのは正しく、衝突しません。

採用戦略：全社一斉をやらない

知識管理システムは「全社で使わないと価値が出ない → 全社導入には部長・役員クラスの政治資本がいる → そこで詰む」という死に方をします。これを避ける設計にしました。

単一チームで即成立：全社一斉導入を必要としない
ボトムアップで自然拡散：使うと得をするチームから自発的に広がる
外部利用が内部採用を牽引：コンポーネントライブラリを使っている外部プロジェクトがこのツールを採用すると、それが内部採用を引っ張る

最初の一手は「広く呼びかけて自発的に来るのを待つ」ではなく、協力的なプロジェクトを 1〜2 個選び、自分で接続まで面倒を見て、"使っていて効果が出ている" 見本を 1 つ作ることだと考えています。

企業ナレッジ基盤の典型的な死因と、この設計の対応

典型的な死因この設計での回避外部 API 依存 → コスト失控・データ持ち出しbge-m3 ONNX のローカル推論・完全オフライン純ベクトル検索 → 精度不足語彙 + 意味のハイブリッド + 意図降権人手メンテ → 誰も更新しないgit hook で自動同期全社導入が前提 → 政治で詰む単一チームで成立、ボトムアップ技術スタック固定 → 1 チームしか救えないプラガブルなパーサ遅い → ユーザーが離れる約 50ms/query指標がない → 価値を証明できないP@1・Token 削減率・遅延などすべて定量化

まとめ

技術的に動くものを作るのは半分です。残り半分は、摩擦をなくし、層を解耦し、単一チームから自然に広がる経路を設計すること。後者を設計に織り込んで初めて、ナレッジ基盤は「使われ続けるツール」になります。