社内文書RAGを作って、2か月で捨てた — 作って捨てて分かった「索引の鮮度」問題

プロジェクトの設計文書が増えてきて、AIコーディングエージェントに「関連文書を読んでから作業して」と言う回数も増えてきた。エージェントへの指示書（AGENTS.md）は膨らみ続け、会話が長くなると、AIは序盤に伝えたはずのルールを忘れる。それなら、文書をAIに検索させる仕組みを作ればいい——社内RAGを検討した動機がこれだ、という方には共感いただけるのではないかと思う。

当社もまさにそれで、2026年6月の初めに、設計文書を検索するための社内RAGを作った。そして7月31日に、全面的に廃止した。精度が低かったわけでも、費用がかさんだわけでもない。索引（index）の鮮度を、安全に、安く保証する方法が見つからなかったからである。

「社内の文書をRAGで検索できるようにする」は、生成AIの業務活用で最初に出てくる定番の企画だと思う。当社はその定番どおりに作り、定番には書かれていない理由で止めた。本稿はその2か月の記録である。先に言っておくと、これは「RAGは使えない」という話ではない。「動くRAG」と「信じてよいRAG」のあいだにある距離の話だ。

前提 — どんな現場の話か

EastCloudでは、デジタル庁がOSSとして公開した政府向け生成AI「源内」を、国産のさくらのクラウド上で動かせるかを検証するプロジェクトを進めている（経緯は1本目の記事にまとめた。未読の方はそちらから）。このプロジェクトは、AIコーディングエージェントが実装・レビュー・監査の実作業の多くを担い、人間は方針と判断に集中する体制で動いている。

当時、エージェントの頭脳として使っていたモデルはGPT-5.5である。いまとなっては一世代前のモデルで、使い込むほどに困りごとがはっきりしてきた。まず、ルールや設計上の決まりはAGENTS.mdに書けば制御できるのだが、大規模なプロジェクトではそのAGENTS.md自体が肥大化していく。次に、会話が長くなると、序盤に渡したはずのルールが忘れ去られる。入力が長くなるほどモデルの性能が落ちるこの現象は、のちにChromaが「Context Rot」という名前で体系的に測定しているが、体感としては当時から明確にあった。そして、毎回「この文書とこの文書を読んでから始めて」と人間が指定する運用は、文書が数十本を超えたあたりで限界が来る。

そこで、AIが作業前に関連文書を自分で探すための検索RAGを、社内ツールとして試作した。なお本稿で扱うのはこの開発チーム内部の道具の話であり、製品にRAG機能を組み込む話とは分けて読んでほしい。

何を作ったか

構成は、いま社内RAGを作ろうとしている人が思い浮かべるものとほぼ同じだと思う。

• 対象: 設計の正本文書（要件、アーキテクチャ、ADR、ロードマップ、引き継ぎ文書、段階ごとの報告書）。作業ログや議事録、ソースコードは対象外
• 処理: 文書を見出し単位の塊に分け、軽量な多言語embeddingモデル（MiniLM系、384次元）でベクトル化し、ローカルで動くベクトルDB（Qdrantのローカルモード）に索引として保存
• 使い方: AIエージェントが作業前にコマンドで検索し、ヒットした文書の原文を読みに行く。検索結果は「ヒント」であって正本ではない、というルール付き
• 規模: 7月中旬の時点で78ファイル、約1,360チャンク

ツール自体は小さなPythonスクリプトで、作るのに大した時間はかからなかった。問題はそこではない。

あわせて、AIエージェント向けの作業ルールにこう書いた。「設計文書を追加・更新したときは索引を更新すること。検索結果を判断の根拠に使う前に、関係する文書の更新後に索引が再構築されたことを確認すること」。ルールとしては正しい。だが、このルールを守り続けることのコストを、当時は見積もれていなかった。

最初はうまくいった

7月初旬の段階では、ちゃんと役に立っていた。効果を実感した順に挙げる。

一番効いたのは、ルール逸脱が減ったことである。前述のとおり、当時のGPT-5.5は会話が進むとAGENTS.mdやコンテキスト上の指示が薄れ、序盤に決めたルールを踏み外すことがあった。作業の前にRAGで該当ルールと関連する設計判断を引き当て、原文を読み直させる運用にしてから、この「ルール忘れ」は目に見えて減った。長大な指示書を最初に一度読ませるより、いま必要な数枚をその都度引かせるほうが、明らかに効いた。

「どの文書に書いてあるか」を探す往復も減った。人間がパスを思い出して指定する代わりに、AIが自分で当たりをつけて原文へ到達する。新しいAIコンテキストを立ち上げるときのキャッチアップも短くなった。

編集する人が実質1人（動かすAIのコンテキストも1つ）だったあいだは、「更新したら再構築」の運用で十分に維持できた。文書の数が少ないうちは、索引の鮮度は問題にすらならなかったのである。

何が詰んだか

崩れ始めたのは7月中旬から下旬にかけてで、原因は3つ重なっている。

1つ目は更新の頻度である。 設計文書は、7月14日の67ファイルから7月29日の84ファイルへ、2週間で2割以上増えた。数が増えただけでなく、同じ文書が1日に何度も更新される。技術選定が進む時期は、ロードマップ、選定の台帳、ADR、引き継ぎ文書が連鎖して変わるからだ。「更新したら再構築」は、更新のたびに再構築が必要だという意味であり、更新が1日数回あれば、再構築も1日数回になる。そして再構築は、実行して終わりではない。検証まで含めた更新一式に30分ほどかかることもあった。1日に何度も行えば、それだけで明確なタイムロスである。

2つ目は並行開発である。 7月中旬以降、複数のAIコンテキストが別々のgit worktree（同じリポジトリの作業コピーを複数並べる仕組み）で並行して動くようになった。データ層の選定を進めるコンテキスト、認証まわりの検証を進めるコンテキスト、全体を束ねるコンテキスト。それぞれの作業コピーでは、文書の状態が違う。未コミットの変更もある。ところが索引は1つしかない。「この索引は、どの作業コピーの、どの時点の文書を写したものか」が、もう説明できなくなった。

3つ目が一番たちが悪い。古い索引は、エラーを出さない。 壊れた索引なら気づける。だが古い索引は、最新に見える過去の答えを、自信たっぷりに返す。たとえば、ある構成を「必須」としていたADRが翌日に「任意」へ改訂されたとする。索引が前日のままなら、AIは前日の「必須」を根拠として引用し、それを前提に実装やレビューを進める。引用元のパスも行番号ももっともらしいので、読んだ人間も気づきにくい。図書館でいえば、本を入れ替えたのに目録カードだけ古いまま、という状態で、しかも司書はカードを信じて本を探しに行く。

この「頻繁に変わるものの索引は、作った瞬間から古い」という問題は、当社だけの発見ではない。AIコーディングエージェントのClineは2025年5月、公式ポストで「Clineはコードベースに索引を作らない。RAGも、埋め込みも、ベクタDBも使わない。これは制限ではなく、意図的な設計判断だ」と公言している。

理由の筆頭が索引の鮮度で、公式ブログの言葉を借りれば、索引とは定義からして「時間の止まったスナップショット」（”An index, by definition, is a snapshot frozen in time.”）であり、進化し続けるコードと必ずズレていくからだ。RAG構築の講座を主宰するJason Liu氏のような推進側の専門家までが、この判断への賛同を公言している。対象がコードか設計文書かの違いはあれど、「頻繁に変わるものを索引で追いかけない」という論理は、当社が痛感したものとまったく同じである。

鮮度保証を真面目にやったら、作業記録が200件になった

ここで当社が取った行動は、たぶん多くのチームと同じで、「ならば鮮度を機械的に保証する仕組みを作ろう」だった。7月21日から29日にかけて、段階的に仕組みを足していった。

• embeddingモデルの取得を固定する。どのモデルの、どの版の、どのファイルを使ったかをハッシュで記録し、ライセンスも確認して、別の人がレビューしてから使う
• 依存パッケージを丸ごと固定する。Pythonの実行環境に入っている全パッケージのファイルごとのハッシュを記録し、1バイトでも違えば起動しない
• 再構築を段階化する。いきなり現行の索引を上書きせず、別の場所に新しい索引を作り、検索で検証し、レビューを経てから差し替える。途中で失敗しても古い索引を失わない
• 索引の元になった文書の集合を固定する。どのブランチの、どのコミットの、未コミット分はどのファイルまでを含めたかを記録し、作成前後でファイルが1つでも変わっていたら止める

ひとつひとつは真っ当な対策だと思う。実際、この仕組みは何度も「正しく」止まった。実行ファイルのパーミッションが足りずに起動が拒否されたとき。パッケージ管理ツールが自動生成するメタデータに空欄のハッシュが2,700件以上あり、それを「改竄の可能性あり」と判定して停止したとき。モデルの取得にネットワークが要るのに、作業環境の外部通信が閉じていたとき。どれも、仕組みが設計どおりに疑って止めたのである。

だが、そのたびに原因を調べ、直し、別の担当がレビューし、監査し、もう一度試す。当社の開発は実装・独立レビュー・最終監査を分離しているので、1回の修理で3種類の記録が残る。9日間でこの内部ツールに関する作業記録は約200件に達した。そして気づいたときには、製品の機能でもなんでもない検索ツールの修理が、本来のフェーズの完了——データ層の技術選定を閉じること——を止めていた。鮮度を保証するための仕組みが、フェーズの完了条件に組み込まれていたからである。

7月31日の決断 — 直すのをやめ、捨てる

7月31日、プロジェクトの責任者が廃止を決めた。理由は3つに整理されている。

1. 並行する作業コピーと頻繁な正本更新に対して、索引の鮮度を安全かつ低コストに保証できない
2. 古い索引が最新の判断と誤認されるリスクを、運用ルールだけでは消せない
3. 製品の統制ではない内部ツールの修理が、フェーズ完了のクリティカルパスを塞いでいる

廃止の中身も、曖昧にしなかった。使わない、更新しない、再構築しない、検証しない、修理を再開しない。過去の検索結果を設計・実装・レビュー・監査の根拠に使わない。一方で、ツールのソース、テスト、固定した環境の記録、失敗や修理の記録は、消さずに読み取り専用で残す。「なかったこと」にはしない。

代わりに何をするか。正本文書を直接読む。それだけである。AIエージェントには、判断の根拠にした文書のパスと行、参照したブランチとコミット、未コミットの変更の有無を記録させる。並行するコンテキスト間の同期は、検索ではなく、人間の判断記録と明示的な引き継ぎ文書で行う。検索の便利さは失ったが、「何を根拠にしたか」は前より明確になった。

一般化 — 社内RAGを入れる前に確かめたいこと

当社の失敗を、社内RAGを検討している人向けのチェックリストにしておく。

• その文書群は、どのくらいの頻度で変わるか。月に数回なら「更新したら再構築」で回る。日に数回なら、再構築の運用そのものが仕事になる
• 文書を同時に編集する人（やAIのコンテキスト）は何人いるか。複数なら、索引が「誰の、いつの状態」を写したものかを説明できる仕組みが要る
• 古い答えが返ってきたとき、誰がどう気づくか。検索結果に「索引の作成時刻」と「元文書の更新時刻」を並べて出すだけでも、事故はかなり減る
• 索引が古いときの被害はどの程度か。社内FAQなら笑い話で済む。設計判断や監査の根拠に使うなら、古い索引は誤った判断を量産する
• 正本は別にあるか。RAGの検索結果が正本扱いされ始めたら、それは設計上の事故である。検索は入口で、根拠は原文、を守れるか
• そもそも、検索できないとどれだけ困るか。文書が100本程度で、一覧と目次が整っているなら、「全部の見出しを読む」ほうが速くて確実なことは多い

当社の場合、最後の項目に戻ってきた。設計の正本を数十本の範囲に保ち、索引を持たず、原文を読む。地味だが、いまのところ一番事故が少ない。

念のため書いておくと、ここでの比較は「RAG対ファインチューニング」ではなく「RAG対、原文を直接読ませる」である。そして、RAGが正解になる状況も明確にある。LlamaIndexのCEOであるJerry Liu氏は、長コンテキスト時代のRAGを論じた2024年3月のポストで、その前提を「ナレッジベースがコンテキストウィンドウに収まらないほど大きい場合」と置いている。

裏を返せば、収まる規模なら選択肢は変わるということだ。文書が数百・数千本あり、全部読ませることが物理的に不可能な組織では、いまもRAGが正道である。当社のように正本を数十本に絞れる現場かどうか、そこが分かれ目になる。

当社も、内部RAGを再導入する可能性を閉じたわけではない。ただし次にやるなら、鮮度の保証方法、並行する作業コピーとの境界、古い索引の拒否、失敗時の挙動、保守の担当者を、作る前に合格条件として決める。過去の索引が残っているから再開する、はやらない。

この判断の賞味期限

本稿は2026年7月末時点の、当社の特定の開発現場での判断である。文書の量、更新頻度、並行度が違えば結論は変わる。そもそも生成AI自体が日進月歩で、それを使った開発のベストプラクティスも数か月単位で塗り替わっている。本稿の困りごとの起点だった「長い会話でルールを忘れる」挙動にしても、モデルの世代が進めば様変わりしうる。本稿の判断は、当時のモデル（GPT-5.5）と道具立てを前提にした一つのスナップショットとして読んでほしい。「社内RAGはやめておけ」ではなく、「索引の鮮度を誰がどう保証するかを先に決めろ」という話として受け取ってもらえれば、賞味期限を超えて役に立つはずだ。

まとめ

• 設計文書を検索する社内RAGを6月初めに作り、7月末に全面廃止した。理由は精度でも費用でもなく、索引の鮮度を安全に保証できなかったこと
• 導入直後は効果があった。ルール忘れが減り、文書を探す往復が減り、新しいAIコンテキストの立ち上がりが速くなった
• しかし、更新が1日数回・並行する作業コピーが複数、という条件では「更新したら再構築」が破綻する。そして古い索引はエラーを出さず、最新に見える過去の答えを返す
• 鮮度を機械的に保証しようとした結果、内部ツールの修理が約200件の作業記録を生み、本来のフェーズ完了を止めた
• 廃止後は正本文書を直接読み、根拠のパス・行・コミットを記録する運用へ戻した。「索引を作らない」は、コーディングエージェント界隈でも設計判断として公言され始めている
• ナレッジベースがコンテキストに収まらないほど大きいなら、いまもRAGが正道。分かれ目は、文書の量と変わる速さにある

作ったものを捨てる判断は、作る判断より重い。ただ、今回は捨てたことで「何を根拠に判断したか」がむしろ見えやすくなった。便利さより追跡可能性を取った、というだけの話である。

よくある質問

Q1. 社内文書RAGとは何か

社内の文書をチャンクに分けてベクトル化し、質問と意味の近い部分を検索してAIに渡す仕組みである。AIが知らない社内情報を根拠つきで答えさせるために使われる。本稿では、設計文書をAIコーディングエージェントが作業前に探すための内部ツールとして試作した。

Q2. RAGのindex（索引）が古いとどうなるか

索引は作成時点の文書のコピーなので、元の文書を直しても自動では変わらない。古い索引は、エラーを出さずに過去の内容を最新の答えのように返すため、改訂前の設計判断が根拠として引用される事故が起きる。検出する仕組みがなければ、人間も気づきにくい。

Q3. 社内RAGの索引はどのくらいの頻度で更新すべきか

文書の更新頻度に合わせる必要がある。月に数回の更新なら「更新したら再構築」で運用できるが、日に数回の更新や複数人の同時編集がある環境では、再構築の運用自体が負担になる。本稿のケースでは、2週間で文書が67件から84件へ増え、同じ文書が日に何度も更新されたことが破綻の一因だった。

Q4. 社内RAGをやめる判断基準は何か

索引の鮮度を安全かつ低コストに保証できない、古い索引が最新と誤認されるリスクを運用ルールで消せない、ツールの維持が本来の業務のクリティカルパスを塞いでいる、の3つが揃ったときである。本稿では、製品の機能ではない内部ツールの修理が本来のフェーズ完了を止めた時点で廃止した。

Q5. 社内向けの文書検索RAGと、製品に組み込むRAGは何が違うか

開発チームが自分たちのために運用する内部ツールか、顧客へ提供する製品機能かという違いがある。製品に組み込む場合は、鮮度の保証に加えて、権限、監査、障害時の挙動まで要件として設計することになる。本稿の教訓——索引の鮮度を誰がどう保証するかを先に決める——は、どちらにも当てはまる。

Q6. AIコーディングエージェントに設計文書を読ませる方法で、RAG以外の選択肢はあるか

ある。設計の正本文書を数十本の範囲に保ち、一覧と目次を整えて原文を直接読ませる方法である。本稿では廃止後にこの方法へ戻し、根拠にした文書のパス・行・ブランチ・コミットを記録させている。文書が少ないうちは、検索より確実で速いことが多い。

Q7. 社内RAGを再導入するなら、どんな条件が必要か

鮮度の保証方法、並行する作業コピーとの境界、古い索引の拒否、ネットワークやキャッシュの扱い、失敗時の挙動、保守の担当者を、最初から合格条件として定義することである。過去の索引やモデルが残っているからといって、そこから再開しないことも重要になる。

参考リンク

• Cline公式ポスト「Cline doesn’t index your codebase.」（2025-05-27）
• Why Cline Doesn’t Index Your Codebase (And Why That’s a Good Thing) — Cline Blog
• Jason Liu氏のポスト「why your coding agents don’t need rag anymore」（2025-07-10）
• Jerry Liu氏のポスト「What does RAG look like in a long-context LLM future?」（2024-03-01）
• Context Rot: How Increasing Input Tokens Impacts LLM Performance — Chroma Research
• Qdrant Documentation
• sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 — Hugging Face
• 政府AI「源内」はさくらのクラウドで動くのか — OSS公開から3か月、国産クラウドでMVPを動かすまで
• プロンプト発見からCowork運用へ──「型作り」と「実行」の分業