エージェントが読むリポジトリ知識に仕様ができ始めている - LLM Wiki・OKF・OpenWiki

こんにちは。 Legalscape (採用情報) でエンジニアをしている kazukitash です。

AI が開発の場に浸透してきてしばらく経ちました。どうでしょうか？ AGENTS.md はこまめにメンテしていますか？正直面倒くさいです。エージェントに任せる開発が増えるほど必要なコンテキストも増えるのに、コードが変わるたびにドキュメントはずれていくし、何をどこまで書けば効くのかもよく分かりません。

幸い、標準化の流れがきているようです。

時期	出来事
2025-12-18	Anthropic が Agent Skills をオープン仕様として公開
2026-04	Karpathy が LLM Wiki パターンを提示
2026-06-12	Google Cloud が Open Knowledge Format（OKF）を公開
2026-07-16	LangChain の OpenWiki が 0.2 で OKF 対応。コードベースの wiki を OKF で出力

パターンの提示から仕様化、生成ツールの対応まで一通り出揃ってきました。この記事では、OKF の仕様を読んで分かったこと、生成側の実装がどこまで来ているかを書きます。最後に軽く自分たちのモノレポの現状を調べた結果を書きます。

LLM Wiki パターン — エージェントに wiki を維持させる提案

OKF のベースになっているのは、Karpathy が 4 月に公開した LLM Wiki パターンです。プロダクトではなく「エージェントに渡す構成の提案」で、gist が書かれています。

Most people's experience with LLMs and documents looks like RAG: you upload a collection of files, the LLM retrieves relevant chunks at query time, and generates an answer. This works, but the LLM is rediscovering knowledge from scratch on every question. There's no accumulation.

RAG は動くが LLM は毎回ゼロから知識を発見し直していて蓄積がない、という指摘です。当然エージェントに docs/ を読ませても、前回の調査で分かったことは次のセッションには残らないので、ここで提案されたのはエージェント自身に wiki を継続的に構築・維持させるというアプローチです。

この話が出る以前にも、Devin の DeepWiki などエージェントにリポジトリの情報を wiki にさせる仕組みはありましたが、改めて体系化してくれたためバズっていたと思います。

構成のポイントは 3 つです。

raw sources — 取り込んだ元資料。immutable。エージェントは読むが書き換えない
the wiki — エージェントが生成・所有する markdown 群。人は読むだけ
the schema — CLAUDE.md や AGENTS.md。wiki の構造と規約、取り込み・照会・維持の手順を書く場所

AGENTS.md がドキュメントではなく wiki の運用規約 として位置づけられているのが印象的です。また、wiki への操作は ingest（資料を取り込んで関連ページに波及させる）・query（出典付きで答え、良い回答は wiki に書き戻す）・lint（矛盾・孤立ページ・古い記述の検出）の 3 つで、lint が操作として定義されているのが重要だと思いました。生成した知識は現物とずれていきますが、普通の型チェックやテストはずれても落ちません。検知する操作を明示的に定義しておく必要があるということですね。

OKF — 知識の出自と検証状態を機械可読にする仕様

Google Cloud が 6 月に出した OKF（Open Knowledge Format）は、このパターンを仕様化したものです。仕様は 1 ファイルで自己完結していて、冒頭にこう書かれています。

The format is intentionally minimal: a directory of markdown files with YAML frontmatter. There is no schema registry, no central authority, and no required tooling. If you can cat a file, you can read OKF; if you can git clone a repo, you can ship it.

Open Knowledge Format のご紹介 | Google Cloud 公式ブログでも、設計の 3 つの原則の 1 つとして「プラットフォームではなく、形式」ということが書かれています。

OKF はドキュメントに対する以下の問いに答えられるように定義されています。

何から作られ、どう検証されたか（provenance）
どれだけ信頼していいか（trust）
まだ正しいか（freshness）
これは最新版か（lifecycle）
この数値は決めた手順で出されたものか（attestation）

仕様を詳しく見ると、バンドルの構造と trust 関係のフィールドでそれが担保されているように感じました。

バンドルの構造

path/to/bundle/
  index.md                 # ディレクトリの一覧
  log.md                   # 時系列の変更履歴
  <concept>.md             # コンセプト文書
  <subdirectory>/
    index.md
    <concept>.md

index.md と log.md が予約ファイル名です。Karpathy パターンの「索引」と「ログ」が、そのままファイル名として固定されています。frontmatter の必須フィールドは type 1 つだけで、title / description / resource / tags は推奨に留まっています。

trust と lifecycle のフィールド

中心になるのがこのあたりのフィールドです。

generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }
verified:
  - { by: human:boku, at: 2026-06-25T09:00:00Z }
  - { by: process:ci, at: 2026-06-26T02:00:00Z }
status: stable # draft | stable | deprecated
stale_after: 2026-09-23

generated は「誰がいつ書いたか」、verified は「誰がいつ確認したか」で、分けられています。書いた主体と確認した主体は別、ということです。verified はリストなので、人間の承認と夜間バッチの確認を両方持てます。

ここから信頼段階が導かれます。

`verified` の状態	段階
キーが無い	unverified
`human:` 以外のアクターのみ	machine-confirmed
`human:<id>` のアクターを含む	human-reviewed

生成 AI が書いた文書を人が全部レビューするのは、すでに無理です。だから レビュー済みかどうかを機械可読にして、エージェント側に判断させる と割り切る仕様になっていますね。仕様には「Trust tiers are advisory signals, not access control」と明記されています。

OpenWiki — コードベースから OKF の wiki を生成する CLI

仕様が求めるものは分かりました。では、生成する側はどこまで出せているのでしょうか。OKF をコードベースに当てているのが LangChain の OpenWiki です。MIT ライセンスの npm CLI で、内部では、ファイル操作やサブエージェントを備えた LangChain の Deep Agents を使って、ドキュメント生成エージェントを動かしています。

npm install -g openwiki
openwiki --init          # 対話でプロバイダとモデルを選び、openwiki/ に出力

code（リポジトリ）と personal（個人の知識）の 2 モードがあります。README を読んで、実装として参考になった点が 3 つありました。

1 つ目は、AGENTS.md への差し込み方です。code モードの実行ごとに、リポジトリルートの AGENTS.md と CLAUDE.md を維持して、コーディングエージェントを wiki に向けます。このとき自分のブロックだけを書き換えます。

<!-- OPENWIKI:START -->
...
<!-- OPENWIKI:END -->

手で書いた部分は触りません。生成ツールが AGENTS.md に相乗りするときのやり方として妥当だと思いました。

2 つ目は、指示を生成物と分けていることです。リポジトリ固有の指示は openwiki/INSTRUCTIONS.md に書きます。OpenWiki は読むが通常の実行では書き換えないファイルで、Karpathy パターンの「schema」に対応します。人が書く層と生成される層を分けておくのは、docs/ を整理するときにも真似できそうです。

3 つ目は、CI で回して差分がなければ何もしないことです。GitHub Actions / GitLab CI / Bitbucket Pipelines のスケジュール実行で、変更があればドキュメントの PR を開きます。実行後に openwiki/ のスナップショットを取り、実際に変わったときだけメタデータを記録するので、定期実行が空コミットを積みません。

まだ OKF に完全に対応していない部分もある

README では OKF 対応をうたっていますが、出力は v0.1 形式なので trust 系フィールドが含まれていません。

v0.1 は generated / verified / sources / stale_after が入る前の版で、書き込まれるメタデータは実質 timestamp（いつ生成したか）だけです。整理するとこうなります。

情報	仕様	生成側（OpenWiki）
いつ書かれたか	`generated.at`	`timestamp`（旧形式）
誰が書いたか	`generated.by`	なし
誰がいつ検証したか	`verified`	なし
何を元にしたか	`sources`	なし
いつ失効するか	`stale_after`	なし

OKFは「出自と検証状態を持て」と言っているが、生成側（OpenWiki）はまだ出せていません。ここは今のところ人間側の運用で埋めるしかありません。

Legalscape のモノレポで足りていないもの

最後に、自分たちのモノレポが今どのような状態になっているか調べてみます。トークン数は o200k_base での概算です。

置き場所	ファイル数	トークン	載るタイミング
`AGENTS.md`（実体）	20	33,965	毎リクエスト（一部）
`docs/`（`AGENTS.md` から参照）	28	61,333	参照されたときだけ
Skills	10	33,023	説明のみ常時、本体は必要時

合計すると約 13 万トークンあります。ただし、エージェントが毎回これを全部読むわけではありません。AGENTS.md はルートと作業中のパッケージにあるものだけがコンテキストに載るので、いくつかのパッケージで AGENTS.md のルートと対象パッケージの組み合わせで足し合わせると大体 4,020〜11,156 トークンでした。詳細を docs/ に逃がし、重い手順を Skills に置く構成は、必要なときだけ必要な知識を読ませる仕組みとしてこの部分については自分たちのrepoもうまく機能していると思いました。

足りていないのは、知識の状態を判断するための情報です。今の docs/ には frontmatter がなく、人が書いたページと生成したページを区別できません。いつ確認されたか、何を根拠にしているかもエージェントには分かりません。

ここで OKF の generated、verified、sources、stale_after が必要になります。AGENTS.md は作業規約と入口として残し、生成した wiki は別の層として置く。CI で再生成し、差分を PR にして確認する。OpenWiki を使ってこのような運用を始めていきたいと思います。

まとめ

OKF の仕様を読んで印象に残ったのは、エージェントが継続的に維持するものであることが明示されていることでした。知識は人間が書いて読まれるものではなく、エージェントが書き維持するものになった。だから誰が書いたか・誰が確認したか・いつまで正しいかを機械可読にするということが仕様に明記されているのが良かったです。

一方で、生成側はまだ追いついていません。OpenWiki の出力には verified / sources / stale_after が出てこないので、信頼まわりは人間の運用で埋める段階です。

私たちはまず、 OpenWiki をモノレポ内で運用するところから試していきます。まだOpenWiki自体も対応しておらず私たち自身の verified の運用や、stale_after の活用なども決まっていませんが、それでもいずれ lint で期限切れのページを列挙できるようになったりするだけで、冒頭に書いた「面倒くさい」は減ると思っています。その運用もAIに構築してもらえば良いわけですからね。

さいごに

Legalscape では、この記事で紹介したような最新の技術動向を継続的に追いかけ、実際のプロダクトや開発プロセスに取り入れる試みを続けています。AI エージェントとの協働を楽しめるエンジニアと一緒に働きたいと考えています。もしこの記事を読んで興味を持っていただけたなら、ぜひ Legalscape で一緒に挑戦してみませんか。