OKF-seedling ロゴ

エージェントにも人間にも読める知識バンドルを作る

ドキュメントを エージェントに読める形で整え、公開する Quarto テンプレートツールです。

LLM やエージェントに知識を読ませたいのに、検索がズレて回答がハズレる — それは文章が悪いのではなく、知識が「形式」に沿って整理されていないからです。

  • Why: 人間向けの文章のままでは、エージェントは概念の区切り・メタ情報・鮮度を正しく読めない
  • What: OKF（Open Knowledge Format）は知識を「1 概念 1 ファイル + frontmatter」に構造化する形式
  • How: .qmd を書くだけで、人間用 HTML と 機械用 OKF バンドル、さらにリンターチェックまでが同時に生まれる

Online Editor で試す テンプレートを入手（quarto use template） 読み始める順番を見る

まず読んでほしい

OKF や知識バンドルが初めての方は、この順で読んでください。

  1. 0. What is OKF — OKF・バンドル・用語の基礎（10 分）
  2. 1. Create a Bundle — 実際に作ってみる
  3. 2. Concept Types — 6 種の型の書き方
  4. 3. Deploy — 公開する
  5. OKF × RAG Synergy — なぜエージェントに効くのか

flowchart LR
    Q["concepts/*.qmd<br>書く（1 概念 1 ファイル）"] --> L["quarto render"]
    L --> H["_site/<br>人間用 HTML"]
    L --> O["okf/<br>機械用 OKF バンドル"]
    O --> V["validate-okf リンター<br>準拠 + 品質警告"]

ヒントブラウザで試す

ローカル環境なしで OKF 概念ファイルを編集・コミットできます。Online Editor または Quarto Editor PE を開いてください。

  • エージェントにも人間にも読める .qmd をソースに
  • quarto use template 一発でバンドル雛形を生成
  • レンダリングで 人間用 HTML と 機械用 OKF バンドル を二系統出力
  • リンターツールとして準拠チェック + 鮮度・欠落の品質警告
  • GitHub Pages / Cloudflare Pages に並行デプロイ

アーキテクチャ図（対話型）

上記の流れを、2 枚の 対話型ダイアグラム としてまとめました。 どちらもコンポーネントの選択、ルート探索、テーマ切替、印刷・エクスポートに対応しています。

  • 全体像（アーキテクチャ図） — 作者・エディタ・レンダリング・バンドル・リンター・デプロイの構成要素と関係
  • ビルドワークフロー図 — .qmd を書いてから公開・配布までの工程と、品質ゲートで止まる戻り道

全体像（アーキテクチャ図）を開く ビルドワークフロー図を開く

OKF バンドルとは

エージェントにも人間にも読める形で、ドキュメント群をひとまとめにした知識パッケージです（知識バンドル = OKF バンドル、以下「OKF バンドル」）。 okf/ ディレクトリ(index.md / log.md / concepts/*.md)に機械可読な Markdown として自動生成され、 人間向けの HTML と 同じ source(.qmd) から同時に出力されます。

  • concept 単位で構造化 … API / Playbook / Metric / Attested Computation を 1 ファイル 1 概念で記述
  • frontmatter が辞書 … type・対象・作成日などのメタ情報を機械が解釈
  • sha 差分追跡 … バンドル全体の更新差分を機械が検知できる

OKF v0.2 と信頼信号

Open Knowledge Format v0.2 は、Google Cloud が 2026 年 7 月に公開した、AI エージェント間で知識を安全に共有・交換するためのオープン仕様です。v0.1 の「Markdown + YAML frontmatter」という最小構成を継承しつつ、v0.2 ではエージェントが採用可否を判断するための 5 つの trust signals（信頼信号） を frontmatter で示せるようにしました。

ノート出典

本節の内容は Google Cloud Blog: “OKF v0.2 adds trust signals” に基づく整理です。

2 種類のバンドル

OKF では知識のまとまりを「知識バンドル」と「情報バンドル」の 2 つに区別します（OKF SPEC では Knowledge Bundle と呼ばれるもので、このサイトでは知識バンドルと呼びます）。

  • 知識バンドル（Curated Knowledge Bundle） — 人間やエージェントがキュレートした「知識」の集まり。Concept Documents(.md)＋YAML frontmatter＋Markdown body（Schema / Examples / Citations / Prose）＋index.md / log.md で構成され、ここが okf-seedling の出力対象です
  • 情報バンドル（Information / Data Bundle） — キュレート前の「生データ」や外部情報源。Wiki / Confluence、BigQuery などの DB スキーマ、API 仕様書、生データ・ログ、ポリシー・標準規格を含みます

flowchart LR
    subgraph CURATED["知識バンドル<br>(Curated Knowledge Bundle)"]
        C["concepts/*.md<br>frontmatter + body"]
    end
    subgraph SIGNALS["OKF v0.2 Trust Signals<br>（信頼の層）"]
        S["sources / generated / verified<br>stale_after / status<br>+ Attested Computation"]
    end
    subgraph RAW["情報バンドル<br>(Information / Data Bundle)"]
        I["Wiki / DB スキーマ<br>API 仕様書 / ログ / 標準規格"]
    end
    C -- "references（参照）" --> I
    S -. "信頼性の証跡" .-> C

5 つの問いと信頼メタデータ

エージェント（知識の消費者）が知識を採用する前に判断すべき 5 つの問いです。問い 1〜4 は frontmatter フィールド（sources / generated / verified / stale_after / status の 5 つ）で答え、問い 5（計算証明）は Attested Computation 概念型 の frontmatter（runtime / executor / attester）で示します。

# 問い 答える場所
1 何から作られたか？ sources（出典）
2 どれだけ信頼できるか？ generated / verified（生成者・検証者）
3 まだ正しいか？ stale_after（鮮度期限）
4 現在のバージョンか？ status（draft → stable → deprecated）
5 正規の方法で計算されたか？ Attested Computation 概念型（runtime / executor / attester）

相関の本質

  • 知識バンドルは情報バンドルを 参照（references） する
  • OKF v0.2 の trust signals がその参照に 信頼性の証跡 を与える
  • 信頼性は「スコア」ではなく 観測可能な事実 として記録される
  • これにより、エージェントは本文を読む前に frontmatter だけで 採用/棄却の判断 ができる

Create

quarto use template watanabe3tipapa/okf-seedling でバンドルの雛形を生成します。concepts/*.qmd・チュートリアル・検証スクリプトが一度に手に入り、続く quarto render で OKF バンドルまで作れます。1. Create a Bundle の手順を見る

Author

6 種の concept 型（API Overview / API Endpoint / API Schema / Playbook / Metric / Attested Computation）を type レジストリで拡張可能。1 概念 1 ファイルに type と title を書けば執筆が始まり、frontmatter がそのまま機械可読なメタデータになります。2. Concept Types の書き方を見る

Deploy

GitHub Pages と Cloudflare Pages に並行デプロイ。quarto render の出力を公開するだけで、人間用 HTML と okf/ バンドルの両方が配信されます。frontmatter は HTML にも出力され、Playwright による知識蓄積にも対応。3. Deploy の手順を見る

OKF × RAG Synergy

OKF と RAG は競合ではなく、OKF バンドルが RAG の精度を左右する RAG-ready な知識基盤になる補完関係です。実バンドル例でシナジーを分解します。OKF × RAG Synergy の記事を読む

DeepSeek V4.1 Flash はこう考える

「AI はこう考える」シリーズ。 本サイトの制作を支援した DeepSeek V4.1 Flash が、OKF と知識バンドルの価値を率直に論じます。

規格の役割は、育成の動機ではなく、廃棄と監査を可能にすること。

#1 OKF と知識バンドルの価値

frontmatter と 1 概念 1 ファイルは何を可能にするか。モデル更新で削られるもの・削られないもの、規格の役割を「廃棄と監査」から考える。 #1 を読む

#2 AI は「検証済み」を信じるか

REA の Evidence 思想と知識バンドルを対比し、verified の限界、未知の残し方、生の証拠と熟成した知識の分担を考える。 #2 を読む

知識の頭出し（Peek）

カセットテープを再生位置の先頭に戻す「頭出し」のように、知識のいちばん頭をチラ見する体験です。「たしかこんな概念があったはず…」といううろ覚えの記憶に、title・description・鮮度チップ・本文の一行がフックして、「ああ、そうだった」から一歩進んだ 新しい気づき を取りに出します。

OKF バンドルは「1 概念 1 ファイル + frontmatter」なので、概念そのものが頭出しの単位になります。下のカードはこのサイト自身のバンドル(okf/concepts/*.md)から quarto render 時に自動生成しています。クリックで本文の頭が展開され、詳細ページへ飛べます。

ノート任意の LP にも貼れます

このセクションはテンプレート同梱の tools/gen-peek.mjs が生成しており、quarto use template 派生のバンドルなら同じ手順で自分の LP に設置できます。『1. Create a Bundle』の Peek 節 を参照してください。

Concept 型

Type 説明 選び方の目安
API Overview API 全体の概要（認証・バージョン・エラー） API の設計方針や全体像を 1 枚で説明したい。例: 認証方式・バージョン戦略・共通エラーをまとめ、各エンドポイントの起点にしたい
API Endpoint 1 エンドポイントの仕様 個別のエンドポイントを 1 本ずつ定義したい。例: GET /users のリクエスト/レスポンス/エラーを 1 ファイルで書く
API Schema 入出力の型・JSON スキーマ データの形を機械に正確に伝えたい。例: users オブジェクトの JSON スキーマとカラム型を単一の真実として持つ
Playbook 手順書・対処手順 手順や判断を構造化したい。例: データ鮮度アラートを受け取ったときの triage 手順
Metric 指標の定義 指標の定義・単元・鮮度を機械に解釈させたい。例: 売上総利益率（gross margin）の定義と更新周期
Attested Computation 検証可能な計算定義 計算値が正規の方法で計算されたかを検証したい。例: 売上の集計 SQL を executor / attester 付きで記録し、再実行して照合する

Quick Start

最低限の手順でローカルにバンドルを作って検証します。前提条件は Quarto（≥ 1.4）と Node.js（≥ 18）のインストールです（Quarto 公式サイト を参照）。

ブラウザで試すなら、Online Editor で始める

Step 1. テンプレートから雛形を生成します

quarto use template watanabe3tipapa/okf-seedling

Step 2. 人間用 HTML と OKF バンドルを同時にレンダリングします

quarto render

Step 3. 準拠チェック + 品質警告を実行します

node tools/validate-okf.mjs
ノートこのステップには Node.js が必要です

tools/validate-okf.mjs は Node.js（≥ 18） で動作します。未インストールの場合は Node.js 公式サイト から入れてから実行してください（Step 1〜2 は Quarto のみで動作）。