OKF入門: メモをagentがたどれる知識に変える

OKFは、同じ前提説明を繰り返す場面で効く

プロダクト改善や分析判断では、「この指標は何を数えるのか」「どのユーザーを除外するのか」「どのテーブルと結合するのか」を繰り返し説明する。OKFは、そのような再利用される前提をagentがたどれる形にするための形式として読むと分かりやすい。

ここでいうagentは、AIに作業させる実行主体を指す。本文では、人間が毎回プロンプトで補っていた文脈を、Markdownファイル、frontmatter、Markdownリンクへ逃がす発想としてOKFを扱う。

この記事では採用判断まではしない。OKFを、普通のMarkdownやfrontmatter一般と何が違う概念なのか、自分の言葉で説明できる状態を目指す。

普通のメモでは、人間が文脈を補っている

たとえば、monthly_active_usersという指標をagentに説明したいとする。普通のMarkdownメモなら、次のように書ける。

# monthly_active_users

月次アクティブユーザー数。
月内に1回以上ログインしたユーザーを数える。
無料トライアル中のユーザーは含めない。
退会済みユーザーは退会日以降の月から除外する。
分析では users と login_events を user_id で結合する。

人間が読むなら、これでも意味は分かる。しかしagentに渡す知識として見ると、次の判断を人間が毎回補っている。

• これは指標なのか、テーブルなのか、業務ルールなのか。
• どのテーブルやイベントと関係するのか。
• 分析時に必ず参照すべき除外条件はどれか。
• 他のagentやtoolへ渡すとき、どこを入口にすればよいのか。

この補完が属人化すると、agentへの依頼ごとに条件漏れや参照漏れが起きる。OKFは、この繰り返し説明される文脈を、ファイル側に置くための形式として理解できる。

OKFでは、知識をconcept fileとして切り出す

OKFの中心発想は、文書を長くすることではない。繰り返し参照され、他の知識と関係する前提を、concept fileとして切り出すことだ。

---
type: metric
title: Monthly Active Users
description: 月内に1回以上ログインし、無料トライアル中ではないユーザー数
tags: [growth, product_analytics]
---

# Monthly Active Users

月内に1回以上ログインしたユーザーを数える。
無料トライアル中のユーザーは含めない。
退会済みユーザーは退会日以降の月から除外する。

## Related concepts

- [users table](/tables/users.md)
- [login events table](/tables/login_events.md)
- [trial users excluded](/caveats/trial-users-excluded.md)

変化は、MarkdownにYAMLを付けたこと自体ではない。monthly_active_usersを、agentに再利用させたい知識の1単位として扱ったことにある。

仕様で決まることと、この例の運用判断を分ける

上の例には、OKF仕様として重要な部分と、この記事で理解しやすくするために置いた運用例が混ざっている。ここを分けておくと、Markdown + frontmatter一般との違いが見えやすい。

普通のfrontmatterは、文書に任意の属性を付ける仕組みである。OKFはそこから一歩進んで、知識をconcept fileとして扱い、最低限typeを持たせ、bundleとして交換・参照しやすくするための弱い規約を置く。

3分で試すなら、1ファイルからでよい

OKFを理解するために、最初から既存メモを一括変換する必要はない。まず1つの指標定義だけをconcept fileにする。

okf-demo/
└── metrics/
    └── monthly_active_users.md

この1ファイルでも、非予約のMarkdownファイルにparse可能なfrontmatterがあり、typeが非空なら、concept documentとして扱える。ローカルのテキストファイルだけで試せるので、Google Cloudアカウントや専用SDKは不要である。

find okf-demo -name '*.md' -maxdepth 3 -print

期待する確認結果は、まずconcept fileが1つ存在すること。そしてagentに読ませたとき、type: metric、無料トライアル除外、退会後除外、関連テーブルへのリンクを拾えることだ。

index.mdは、複数conceptになったときの任意の入口

OKFではindex.mdという予約ファイル名がある。ただし、これは必須入口ではない。存在しない場合でも、consumerはそれだけを理由にbundleを拒否しない。

conceptが増えたら、次のように入口を置ける。

# Metrics

* [Monthly Active Users](metrics/monthly_active_users.md) - 月内に1回以上ログインし、無料トライアル中ではないユーザー数

index.mdの役割は、知識を正しくすることではなく、束になったconceptへの入口を作ることである。

OKF化すると、文脈をたどる手がかりが増える

ここでいう「agentが使える」は、agentが勝手に賢くなるという意味ではない。入口、種類、関連情報が明示されているため、必要な文脈をたどりやすくなるという意味である。

OKFは、分類や正しさを自動では決めない

OKF v0.1でproducerが最低限そろえるものは少ない。非予約の.mdファイルにはparse可能なYAML frontmatterを置き、typeを非空にする。index.mdとlog.mdは予約ファイル名だが、存在する場合にだけ所定の構造に従う。

一方でconsumer側は寛容に読む。unknown type、unknown field、broken link、missing indexを理由にbundleを拒否しない。つまりOKFは厳密な知識モデルではなく、相互運用のための最小約束である。

この寛容さは導入しやすさでもあるが、運用品質を保証しない。正しい分類、最新の定義、SQLやdbtやBIとの同期、owner、公開範囲は別途決める必要がある。

OKF化に向くのは、繰り返し参照される前提である

採用判断はこの記事ではしない。ただし、どんな知識がconcept候補になるかを知っておくと、OKFの意味が具体化する。

最小導入として考えるなら、まず1つの指標だけをconcept fileにする。type、title、description、関連リンクだけで始め、既存メモを一括変換しない方がよい。

知識をたどりやすくするほど、公開範囲の管理が重要になる

例に出てくるテーブル名や指標名は架空・匿名化済みである。実務では、個人情報、金融情報、顧客固有情報、公開できない実テーブル名やKPI定義を、公開HTMLや外部AIの入力対象にしない。

OKF化する前に、そのconceptが公開可能か、社内限定か、特定ロール限定かを分類する。実務運用では、必要に応じてclassification、owner、source、last_reviewed、allowed_consumersのようなfieldを足す候補になる。

公開前には、secretsなし、個人情報なし、顧客名なし、実テーブル名の公開可否、owner、source、last_reviewed、Markdownリンクの確認、rollback可能性を確認する。

作業指示と参照知識は置き場所が違う

結論: OKFはメモを再利用可能な知識に変える

OKFは、AIに渡したい知識を再利用できる単位に分ける考え方である。concept fileで知識を切り出し、typeで種類を示し、Markdownリンクで関係をつなぐ。

ただし、OKFにすると正しい知識管理が自動で完成するわけではない。agentが関連知識をたどる手がかりは増えるが、分類、鮮度、source of truth、owner、権限、公開範囲は別途設計する必要がある。

参考資料