Grandream
「Markdownのフォルダ」で組織の知識を持ち運ぶ — Google発の新仕様 OKF をざっくり読み解く
2026年6月、Google Cloud が「Open Knowledge Format（OKF）」という仕様の v0.1 を GitHub で公開しました。AIエージェントに組織の知識を読ませるための、特定ベンダーに縛られないオープンな形式です。
仕様書を開いて、正直ちょっと拍子抜けしました。やっていることは「YAMLフロントマター付きのMarkdownファイルを、フォルダにまとめる」だけ。専用のSDKも、新しいランタイムも、凝った圧縮形式もありません。リポジトリは GoogleCloudPlatform/knowledge-catalog、ライセンスは Apache 2.0 です。
この記事では、なぜこんなにシンプルな仕様がわざわざ提案されたのか、そして実際に何をどう書くのかを、仕様書を追いながら整理していきます。
そもそも何を解決したいのか
LLMやAIエージェントがどれだけ賢く振る舞えるかは、結局「どんな文脈（コンテキスト）を渡せたか」でほぼ決まります。ところが、その文脈のもとになる知識は、たいてい社内のあちこちに散らばっています。
たとえばこんな具合です。メタデータカタログにはベンダー独自のAPI経由でしかアクセスできず、運用ノウハウはWikiや共有ドライブに眠り、肝心の定義はコードのコメントやノートブックの中、そして一番大事なところはベテランの頭の中にしかない、というように。
「週次アクティブユーザーをイベントログからどう計算するんだっけ？」とエージェントに尋ねるたびに、これらの断片をかき集めて組み立て直すことになります。やっかいなのは、ベンダーごとにAPIもスキーマも違うこと。新しいエージェントを作るたびに、このコンテキスト集めをイチから作り直す羽目になります。OKFが狙うのは、まさにこの「毎回の組み立て直し」をなくすことです。みんなが同じ形式で知識を置いておけば、誰が書いたものでも、どのエージェントからでも読めるようになる、という発想です。
あえて「決めない」という設計
OKFの面白さは、機能を盛り込むのではなく、徹底して削ったところにあります。設計の柱は次の3つです。
ひとつめは、できるだけ規定しないこと。必須フィールドは type ひとつだけで、あとは書き手の自由に任されています。ふたつめは、書く側と読む側を切り離すこと。「誰が知識を書くか」と「誰がそれを使うか」を分離し、両者をつなぐのはフォーマットという約束ごとだけ、という割り切りです。みっつめは、プラットフォームではなくフォーマットに徹すること。特定のクラウドやデータベース、モデルに依存せず、専用SDKやアカウントも要りません。
要するに「ただのMarkdown、ただのファイル、ただのYAML」です。どんなエディタでも開けて、GitHubでそのまま表示でき、gitでバージョン管理できる。人間が読むものと、エージェントが読むものが同じになる、というのが効いてきます。
中身を見てみる
ファイル1枚はこう書く
OKFのドキュメント1枚は、YAMLフロントマターと本文（Markdown）の組み合わせです。たとえばBigQueryのテーブルを説明するなら、こんな形になります。
---
type: BigQuery Table
title: Orders
description: 完了した注文1件につき1行。
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, revenue]
timestamp: 2026-05-28T14:30:00Z
---
# Schema
| Column | Type | Description |
|--------|------|-------------|
| `order_id` | STRING | グローバルに一意な注文ID |
| `customer_id` | STRING | [customers](/tables/customers.md) への外部キー |
# Joins
`customer_id` で [customers](/tables/customers.md) と結合。
フロントマターのフィールド
使えるフィールドはごくわずかです。
type（唯一の必須項目）… その概念が何なのかを表す短い文字列。"BigQuery Table"や"Metric"、"Playbook"といった具合に、自明な名前を自由に付けます。中央で管理された語彙リストのようなものはなく、ルーティングやフィルタリング、表示の手がかりとして使われます。title（推奨）… 表示名。省略するとファイル名から導かれます。description（推奨）… 一文の概要。検索結果のスニペットなどに使われます。resource（任意）… 元になっている資産のURI。抽象的な概念には付けなくて構いません。tags（任意）… 分類のための短い文字列のリスト。timestamp（任意）… ISO 8601形式で、最後に意味のある変更をした日時。
これ以外のキーも自由に足せます。重要なのは、読む側は知らないキーが出てきても、それを理由にドキュメントを拒否してはいけない、と仕様で決められている点です。これが、形式をあとから拡張しても壊れにくい理由になっています。
フォルダ全体が「知識のグラフ」になる
ファイルが集まってフォルダになると、今度はそれ全体がひとつの知識ベースとして機能します。
sales/
├── index.md
├── tables/
│ ├── orders.md
│ └── customers.md
└── metrics/
└── weekly_active_users.md
仕組みはシンプルです。ファイルのパスがそのまま概念のID（識別子）になります（tables/users.md なら tables/users）。ドキュメント同士はふつうのMarkdownリンクでつなぎ、/ で始まるバンドルルートからの相対リンクが推奨されています（たとえば [customers](/tables/customers.md)）。リンクは「型のない関係」を表すだけのゆるいもので、リンク切れがあっても許容されます。
index.md は「目次」、log.md は「履歴」
このディレクトリに登場した index.md には、特別な役割があります。これはそのフォルダの目次にあたるファイルで、中を開く前に「ここに何があるか」をざっと見渡せるようにするためのものです（仕様では progressive disclosure、段階的な開示と呼んでいます）。
書き方も決まっていて、index.md には基本的にフロントマターを付けません。本文は見出しと箇条書きのリストで、各エントリにはリンク先ドキュメントの description を添えることが推奨されています。実際にはこんな見た目になります。
# Tables
* [Orders](/tables/orders.md) - 完了した注文1件につき1行。
* [Customers](/tables/customers.md) - 顧客マスタ。1行が1顧客。
# Metrics
* [Weekly Active Users](/metrics/weekly_active_users.md) - 週次のアクティブユーザー数の定義。
index.md はどの階層にも置けて、必須ではありません（無い場合は読む側が動的に生成してもよい、とされています）。ひとつだけ例外的なルールがあって、フロントマターを書けるのはバンドルのルートにある index.md だけ。そして、そのバンドルがどのバージョンのOKFに準拠しているかは、ここに okf_version: "0.1" と宣言します。
---
okf_version: "0.1"
---
# Sales Knowledge Base
* [Tables](/tables/index.md) - 売上系のテーブル一覧。
* [Metrics](/metrics/index.md) - 主要指標の定義。
もうひとつの予約ファイル log.md は、そのスコープの変更履歴です。新しいものを上にして、日付ごとにエントリをまとめます。日付の見出しは ISO 8601 の YYYY-MM-DD 形式が必須。各行の先頭に Update や Creation といった太字ラベルを付けるのは慣例で、必須ではありません。実物はこんな雰囲気です。
# Changelog
## 2026-05-28
* **Update** [orders](/tables/orders.md) に `customer_id` の結合説明を追記。
* **Update** [weekly_active_users](/metrics/weekly_active_users.md) の定義を、退会済みユーザーを除外する形に修正。
## 2026-05-14
* **Creation** [customers](/tables/customers.md) を追加。
* **Deprecation** 旧 `legacy_orders` テーブルのドキュメントを削除。
v0.1で「準拠している」と言える条件
ここまで読むと身構えそうですが、適合条件は拍子抜けするほど少ないです。予約名以外のすべての .md が解析可能なYAMLフロントマターを持っていること、そのフロントマターに空でない type があること、予約ファイル名（index.md と log.md）を規定どおりに使っていること。満たすべきはこれだけです。
配布形式は、gitリポジトリが推奨ですが、tarballやzipでも、リポジトリ内のサブディレクトリでも構いません。
既存の仕組みとどう違うのか
OKFは何かを置き換えるというより、すでにあるものの「共通の置き場所」を決める仕様です。いくつか引き合いに出される技術と比べてみます。
ひとつは、いわゆるLLM-wikiパターン。Andrej Karpathy が「LLMは飽きないし、参照の更新を忘れないし、一度に15ファイルでも平気で触れる」と指摘したように、人間がサボりがちな個人Wikiの保守こそ、実はエージェントが得意とするところです。各チームが思い思いにやっていたこのやり方を、相互運用できる形に標準化したのがOKFだと考えると分かりやすいです。Obsidianのvaultや AGENTS.md も、同じ土俵に乗ってきます。
RAGとの違いもよく聞かれます。RAGが「検索して本文を引っ張ってくる」仕組みなのに対し、OKFは構造化されたメタデータと本文を、キュレーションしてバージョン管理した状態で持っておくものです。役割が重なるというより、RAGに渡す手前の知識をきれいに整えておく、というイメージに近いです。
MCP（Model Context Protocol）とは補完関係です。MCPは「どうアクセスするか」をリアルタイムでつなぐプロトコルで、OKFは「何を知っているか」を静的に蓄えておく知識ベース。OKFが知識そのもの、MCPがそこへの経路、と整理すると住み分けが見えてきます。
Google Cloudの製品とのつながり
リポジトリには参考実装も付いています。エージェントがBigQueryのテーブルやビューを走査してOKFドキュメントの下書きを自動生成し、既存のドキュメントを参照しながら結合パスやスキーマの説明を補強して、最後にGitHubへコミットする、という流れが示されています。また Google Cloud Knowledge Catalog は v0.1 の取り込みに対応済みで、サンプルバンドルとしてGA4のeコマースデータ、Stack Overflow、Bitcoinの公開データセットが用意されています。
おわりに
OKFの賭けはわりとはっきりしています。複雑になりがちな知識のやりとりを、AI時代でもっとも枯れていて移植性の高い「Markdown + YAML + フォルダ + git」に落とし込んでしまえば、ベンダーの垣根を越えて知識が流通するはずだ、という見立てです。
v0.1 はあくまで出発点で、完成した標準ではありません。書き手と読み手が増えるなかで、後方互換を保ちながら育てていくと明言されています。組織の知識を「コードと同じように」扱いたいと思っていたチームにとっては、いますぐ試せる最小単位として悪くない選択肢だと思います。
出典
Grandream
株式会社グランドリーム
AI・システム開発のプロフェッショナルチームです。AIエージェント・業務自動化・Webシステム開発などを手がけています。