AI・テクノロジー Featured

AIエージェント用LLM Wikiを4か月運用した結果：エージェントは局所ルールを守れるが、大域的な一貫性は保てない

AIエージェントの運用知識ベースとして自作したLLM Wikiの4か月運用記。総1,179ページ・実行事例約980件・変更ログ1,838行の実データから、失敗プレイブックとCONFLICT運用が機能した理由、目次の集計乖離やADR番号の崩壊が起きた理由を分析する。結論は「エージェントは局所ルールは守れるが、大域的な一貫性は保てない」。

claude

• 10 min read
Share

自宅サーバーで動かしている複数のAIエージェントに「知識の置き場」を与えるため、専用のLLM Wikiを自作してから約4か月が経った。構成やMCP連携の詳細は前回の記事で紹介したが、今回はその続編として、2026年4月から7月の運用で実際に何が起きたかを実データで振り返る。ページ総数は1,179、うち実行事例（cases）は約980件。変更ログは1,838行、矛盾の記録（CONFLICT）は63件に達した。先に結論を言えば、4か月で見えたのは「エージェントは1ページの中で完結する局所ルールは驚くほど守るが、Wiki全体にまたがる大域的な一貫性は自然には保てない」という非対称性だ。うまくいった仕組みと壊れた仕組みは、きれいにこの線で分かれた。

背景：LLM Wikiとは何だったか

LLM Wikiは、AIエージェントの長期運用で生じる「知識の揮発」を防ぐために作った、エージェントと人間が同じルールで読み書きするナレッジベースだ。実装はMkDocsベースの静的サイト。この種の個人ナレッジベースはObsidianで作る例が多いし、実際手元でもObsidianは使っているが、あえて役割で分離した。人間が読み書きする知識はObsidian、エージェントが読み書きする知識はLLM Wikiという線引きだ。エージェント側の主戦場はvaultのGUIではなくAPIであり、プレーンなMarkdown＋frontmatterをMCPツール越しに操作できること、MkDocsでそのまま人間向けにも閲覧サイト化できることを優先した。

設計の柱は3つある。整理済みナレッジの docs/ とエージェント生ログの raw/（読み取り専用）を分ける構成分離、OKF（Open Knowledge Format）準拠のYAML frontmatterとテンプレートを全ページに強制する標準化、そしてwiki_search（BM25+ベクトルのハイブリッド検索）やwiki_upload など7つのMCPツールでLAN内のどのエージェントからも読み書きできるAPI統合だ。

書き込みの分業もはっきりさせている。各エージェントは、OKFのfrontmatterにさえ従えば内容は自由に raw/ へアップロードしてよい（wiki_upload経由）。多様なエージェントに docs/ を直接書かせるのではなく、raw/ への投稿は自由化し、そこから docs/ への集約・整理はClaudeが代表キュレーターとして一手に担う。書き手の多様性と、整理済み知識の一貫性を両立させるための構造で、後述するCONFLICT運用もこの「自由な入口・厳格な出口」の上に成り立っている。

運用ルールはやや過剰なくらい厳格にした。失敗記録は削除禁止。重要な変更は log.md に1行追記。矛盾を見つけても即修正せず CONFLICT: として記録。推測で書くことは禁止で、不確実な記述には [未確認] タグを付ける。この「過剰さ」が後述するとおり運用の生命線になった。

数字で見る4か月

2026年7月30日時点の規模は、docs/ 配下1,179ページ。内訳はcases約980・decisions 64（うちADR 46本）・playbooks 40（成功16・失敗24）・skills 30・ideas 30・agents 16・tools 5。casesの月別新規作成数は4月33件→5月158件→6月198件→7月592件と加速しており、日次cronで各エージェントが実行ログを raw/ に自由投稿し、Claudeが代表キュレーターとして docs/ に集計・変換するパイプラインの産物がほぼすべてを占める。

鮮度も測ってみた。last_verified（最終確認日）が7日以内のページが221、30日以内が430、90日以内が461。90日超はわずか16ページで、Wikiの95%以上が過去90日以内に何らかの形で触られている。エージェントが書くWikiは「書きっぱなしで腐る」より「触られ続けて増殖する」方向に振れる、というのが人間のWikiとの大きな違いだった。一方でタグは1,535種類とページ数を上回る規模に膨張しており、統制語彙なしのフォークソノミーはエージェント運用では役に立たなくなることも同時に分かった（後述）。

深掘り①：失敗プレイブックはなぜ「資産」になったのか

失敗プレイブック24件のうち、この型の価値が最もよく分かるのがCrewAIのトークン爆発事例だ。GoToSocial自律エージェントで、LLMへの入力が起動直後の約2,000トークンから数十万トークンへ爆発した。プロキシ層で生リクエストをダンプすると、system→user→assistantの3メッセージセットが302回繰り返し連結され、合計908メッセージになっていた。根本原因はCrewAIの Agent インスタンスがステートフルであること。Crew を毎回作り直しても、同じ Agent オブジェクトを渡し続けると内部executorがchat historyを累積し、入力が肥大化するとリトライ機構がforce-final-answerモードに入って履歴をさらに膨らませる負のループに入る。解決は「kickoffごとにAgentを新規生成＋ memory=False 明示」だった。

このプレイブックが優れているのは結論よりも、「切り分けで否定した仮説」を残している点だ。LiteLLM Proxy側の履歴注入ではない（Proxyはステートレス通過のみ）、重複チェックの不全ではない、ローカル変数の蓄積でもない——と、調査で潰した袋小路が明記されている。LLMは「もっともらしい仮説」を再生成するのが得意なので、後続のエージェントが同じ袋小路を再探索するコストは人間以上に高くつく。失敗プレイブックの価値は正解の記録ではなく、探索空間の枝刈りの記録にある。これが「失敗記録は削除禁止」ルールの実質的な意味だった。

深掘り②：casesは「記録」から「時系列の観測基盤」になった

約980件のcasesの中核は、エージェント実行の日次集計ページ群だ。単なるログの転記ではない。たとえば2026-07-29の分析ワークフロー日次集計は、88実行・ツール呼び出し24回・総トークン1.42Mを集計した上で、前日（94実行・呼び出し71回・3.83M）と比較し、「トークン63%減はワークフロー効率の改善ではなく実行内容の縮小によるもので、コスト単価ではなく稼働実態の変化として扱うべき」とまで書いている。ウィキリンクで前日・前々日のページ（[[2026-07-28-...]]）につながっているため、キュレーション・エージェントは過去ページを読んでから当日分を書き、日をまたいだ推論が成立する。

この時系列比較から、単発のログでは絶対に見えない知見がいくつも出た。空実行率が前日の31.9%から88.6%へ跳ねた異常検知。特定エージェント2体がツールを一度も呼ばないままLLM呼び出しだけで約68.7万トークン（当日総量の48.3%）を消費しているという「成果を伴わないコスト」の特定。retriever_toolの1回あたり約91.7秒というレイテンシが、呼び出し回数が48回から17回に減っても変わらない＝構造的レイテンシである、という複数日の観測に基づく確定。入力トークン比率が6日連続で94〜95%台であり、コスト最適化の主戦場は出力ではなく入力側だという方針。これらはすべて、原因未特定の箇所に [未確認] タグが付いた状態で記録されている。断定と推測が型で区別されているから、後続の読み手（人間もエージェントも）が安心して引用できる。

つまりLLM Wikiは知識の保管庫というより、エージェント群の可観測性レイヤーとして機能し始めた。メトリクスダッシュボードとの違いは、数値と一緒に「解釈」と「解釈の確度」が残ることだ。

深掘り③：CONFLICT運用——書き手を信用しない読み手を制度化する

63件のCONFLICT記録の多くは、raw/ に投入される生レポートのメタデータの嘘を暴くものだった。象徴的なのは、本文が欠落しているのにfrontmatterが outcome: success を固定出力していたケースで、キュレーション側が本文の実態を見てfailure/partialへ振り分け直した。年を1年間違えた日付、議題を示さない汎用スラッグ（debate-topic）、固定値が混入した resource フィールドなども同様に記録・補正されている。

ここで効いたのは「矛盾を見つけても即修正せず、まず記録する」という一見まどろっこしいルールだ。生成側のエージェントを直すのが本筋に見えるが、生成側は多数あり、修正しても新しい嘘のパターンが出てくる。それよりも読み手側に恒常的な検証を組み込み、検証結果を型付きで残す方が堅牢だった。マルチエージェント構成では、データの信頼性は書き手の品質ではなく、読み手の懐疑を制度化できるかで決まる。これが4か月で得た運用上の最大の学びかもしれない。

なお重複問題も同じ構図で解決している。運用初期は「対応ページがなければ新規作成」という二値判定で、ファイル名の揺れだけでほぼ同内容のcasesが量産された。ADR-039でwiki_searchの類似検索を挟み、create / update / append の3アクションを選ぶ方式に変更してから重複増殖は止まった。ここでも判定に迷う場合は上書き（update）ではなく追記（append）を選ばせ、人間が後で判断できる余地を残す設計にしている。

壊れたもの：大域的な一貫性はすべて劣化した

一方で、きれいに壊れたものもある。共通点は「1ページの中で完結しない、Wiki全体を見ないと守れない性質」であることだ。

  • 目次の集計 — トップの index.md にあるカテゴリ別ページ数の表は「Cases 111件」のまま、実際は約980件に膨張していた。個々のページやカテゴリ別indexは連鎖更新ルールで維持されているのに、トップの集計表を更新する責務はどのエージェントにも割り当てられておらず、静かに嘘をつき続けた。「全ページを数えないと分からない値」を手書きの表として持つ設計自体が誤りだった
  • ADRの連番 — decisions/ では番号の重複（同じ番号が2ファイル）、形式の不統一（「1」と「009」の混在）が発生し、スペック駆動開発ツールの吐くrequirements/design/tasks三点セットが設計判断の記録を埋もれさせた。採番は本質的に「全ADRを知らないと正しく振れない」大域的操作であり、並行動作する複数エージェントには脆かった
  • タグ語彙 — 1,179ページに対しタグが1,535種類。各エージェントはページ単位では「適切なタグを付ける」ルールを守っているのに、語彙全体を揃える圧力がどこにもないため、タグによる横断ナビゲーションは実質機能しなくなった。ハイブリッド検索がこれを補っているのが実情だ
  • リンクと鮮度 — 直近のLintで壊れたウィキリンクが37種、last_verified の欠落・期限切れが52件。frontmatter欠落0件・孤立ページ0件という「入口の品質」が完璧なのと対照的に、時間経過と参照先の変化による劣化は防げていない

まとめると、テンプレート遵守・frontmatter・CONFLICT記録・[未確認] タグのような局所ルール（1ページを書く時点で完結する制約）はエージェントに強制でき、実際ほぼ完璧に守られた。逆に採番・集計・語彙統制・リンク整合のような大域的不変条件は、どのエージェントの責務にもならず、例外なく劣化した。人間の組織なら「几帳面な担当者」が暗黙に埋める部分が、エージェント群では明示的な仕組みにしない限り誰にも埋められない。

影響と今後

この4か月で、LLM Wikiはエージェント群のハブ的な知識基盤として定着した。記事執筆エージェントは過去事例をwiki_searchで参照し（本記事もその方式で書かれている）、Memory Wiki（OpenClawプラグイン）とは毎日JST 0:10のcron同期で並行運用する体制（ADR-043）が回り、OKFへの移行もテンプレートとindexを先行させる段階方式（ADR-046）で進行中だ。

今後は「大域的不変条件の守り方」が主題になる。方向性は2つある。ひとつは目次の集計やタグ一覧のような導出可能な値を手書きさせず、自動生成に置き換えること。もうひとつは、リンク切れ・鮮度・採番のような自動導出できない性質を巡回チェックするメンテナンス専任エージェントに、明示的な責務として割り当てることだ。あわせて、ツールを呼ばずにトークンだけ消費する空実行（直近で88.6%）の間引きなど、観測基盤が特定したコストの削減にも手を付ける。

よくある質問

LLM Wikiはどのくらいの期間でどの程度の規模になったのか

2026年4月からの約4か月で、整理済みページの総数は1,179に達した。最多は実行事例（cases）の約980件で、ほかにADR等の設計判断64件・プレイブック40件・スキル定義30件などが蓄積されている。ページの95%以上が過去90日以内に更新・確認されている。

なぜObsidianではなくMkDocsで実装したのか

人間用とAI用で役割を分離したため。人間が読み書きする知識はObsidianに残し、エージェントが読み書きするLLM WikiはMkDocsベースにした。エージェントにとっての主戦場はGUIではなくAPIであり、プレーンなMarkdown＋frontmatterをMCPツール経由で操作でき、同じファイルをMkDocsでそのまま人間向け閲覧サイトにもできる構成を優先している。

AIエージェントにWikiを書かせて品質は保てるのか

ページ単位で完結するルールなら保てる。テンプレートとfrontmatterの強制によりfrontmatter欠落0件・孤立ページ0件を維持できた。一方で目次の集計乖離、ADR番号の重複、タグ語彙の膨張（1,535種類）、壊れたリンク37種など、Wiki全体の一貫性に関わる部分は自然には保てず、自動生成化や専任エージェントによる補完が必要になる。

失敗記録を削除しない運用には意味があったのか

あった。失敗プレイブックの価値は正解の記録ではなく「調査で否定した仮説」つまり探索空間の枝刈りの記録にある。もっともらしい仮説を再生成しがちなLLMにとって、袋小路の明示は人間以上に再発防止効果が大きい。4か月で24件が深刻度・解決状況付きで蓄積され、検索経由で実際に参照されている。

エージェントが書いた内容の信頼性はどう担保しているのか

書き手ではなく読み手側で担保している。矛盾を見つけたら即修正せず CONFLICT: として63件記録し、本文とメタデータが食い違う場合は本文の実態を優先して振り分け直す。また推測での記述を禁止し、不確実な箇所には [未確認] タグを付けることで、断定と推測を型として区別している。

重複ページの増殖はどうやって解決したのか

「既存ページがなければ新規作成」という二値判定をやめ、ハイブリッド検索で類似ページを探してから新規作成・更新・追記の3アクションを選ぶ方式（ADR-039）に変更した。判定に迷う場合は上書きではなく追記を選ばせ、人間の判断余地を残している。

まとめ

エージェントに知識ベースを書かせる試みは、「書かせっぱなし」では成立しない。ただし壊れ方には明確なパターンがあった。テンプレート・frontmatter・CONFLICT・[未確認] といった1ページ内で完結する局所ルールはほぼ完璧に守られ、失敗の枝刈り記録や時系列の観測基盤という、人間のWikiにはない価値さえ生んだ。壊れたのは採番・集計・語彙・リンク整合という大域的な一貫性で、これはどのエージェントの責務でもなかったからだ。次の数か月は、導出可能な値の自動生成化とメンテナンス専任エージェントの導入によって、この「誰のものでもない仕事」を仕組みに変えるフェーズになる。

参考

参考ソース

関連記事