OKF入門: 繰り返し説明する前提を知識ファイルにする

この記事で扱うこと、扱わないこと

この記事は、OKFを導入すべきかを判定する記事ではない。1つの指標定義をOKF風の知識ファイルに分けると、何が参照しやすくなり、何を別途運用で決める必要があるのかを確認する記事である。

読後に目指す状態は、次の4つを自分の言葉で説明できることだ。

• どのメモがOKF化の候補になりそうか。
• 通常のMarkdownで十分なメモと、知識ファイルに分けたいメモの違いは何か。
• 作業指示として置くべき内容と、参照知識として置くべき内容は何が違うか。
• 外部AI、RAG、検索indexへ渡す前に何を確認すべきか。

本文はOKF v0.1 Draftを、2026-06-30時点で確認した理解に基づく。仕様が変わる可能性はあるため、実装や公開前には公式仕様を確認する。

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

たとえば、月次アクティブユーザー数をAI agentに説明したいとする。普通のMarkdownなら、次のように書ける。

# monthly_active_users

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

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

• これは指標なのか、テーブルなのか、業務ルールなのか。
• どのテーブルやイベントと関係するのか。
• 分析時に必ず参照すべき除外条件はどれか。
• 複数のメモを渡すとき、どこを入口にすればよいのか。
• いつ、なぜ、その知識が変わったのか。

OKFは、この「毎回人間が補っている文脈」を、ファイル側に置くための形式として読むと分かりやすい。

OKF化で何が変わるか

ここで重要なのは、AI agentが自動で賢くなるわけではないという点だ。OKFは、参照漏れを減らすための手がかりを増やす。実際にどこまで使えるかは、読み手側のツールやagentが、ファイル探索、リンク解決、権限判定をどう実装しているかに依存する。

成功の目安は、前提説明が短くなること、除外条件の参照漏れが減ること、古い定義を見つけやすくなること、知識変更をレビューしやすくなることである。

OKFの用語を、日本語の実務語に置き換える

OKFの仕様語は英語で出てくる。日本語話者が読むときは、先に意味を押さえてから仕様語に戻る方が読みやすい。

以降では、仕様語を残しつつ、必要に応じて「知識ファイル」「知識のまとまり」「作り手側」「読み手側」と言い換える。

知識ファイルとして、1つの指標定義を切り出す

OKFの中心は、長い文書を作ることではない。繰り返し参照する前提を、1つの知識ファイルとして切り出すことだ。

以下は架空例である。実務では、実テーブル名、顧客名、内部KPI、個人情報、APIキー、SQL、ログ断片をそのまま入れない。

---
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 frontmatterを付けたこと自体ではない。月次アクティブユーザー数を、AI agentが参照しやすい知識の1単位として扱ったことにある。

Markdownリンクは、関連情報をたどる手がかりである。ただしリンク自体に「必須join」「参考情報」「注意喚起」のような関係種別はない。関係の意味は、周辺の本文で説明する必要がある。

OKFで必須のこと、この例で足したこと

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

OKFは、厳密なスキーマで知識を縛る形式ではない。最低限のfrontmatterと通常のMarkdownリンクを前提に、異なるツールやAI agentが同じ知識のまとまりを参照しやすくするための軽い約束である。

1ファイルで試す

OKFを理解するために、既存メモを一括変換する必要はない。まず、架空の指標定義を1つだけ作る。

mkdir -p okf-demo/metrics

cat > okf-demo/metrics/monthly_active_users.md <<'EOF'
---
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)
EOF

find okf-demo -type f -name '*.md' -print

期待結果は次の通りである。macOSでも動きやすいように、ここでは-maxdepthを使わない。

okf-demo/metrics/monthly_active_users.md

この時点では、リンク先のtables/users.mdなどは未作成でよい。最小実験の成功条件は、1つのMarkdownファイルからtype: metric、指標の説明、無料トライアル除外、退会後除外、関連リンクの手がかりを読み取れることである。

uv run --with pyyaml python - <<'PY'
import re
from pathlib import Path
import yaml

path = Path("okf-demo/metrics/monthly_active_users.md")
text = path.read_text(encoding="utf-8")
_, frontmatter, body = text.split("---", 2)
meta = yaml.safe_load(frontmatter)

print("type:", meta.get("type"))
print("title:", meta.get("title"))
print("links:", re.findall(r"\[[^\]]+\]\(([^)]+)\)", body))

assert meta.get("type") == "metric"
assert "無料トライアル中のユーザーは含めない" in body
PY

AI agentに読ませる場合は、「この知識ファイルを読んで、MAUの除外条件と参照先を列挙して」と依頼する。除外条件と3つのリンクを拾えれば、まずは概念理解として十分である。

index.mdとlog.mdは、知識のまとまりを支える予約ファイル

OKFには、通常の知識ファイルとは別に、特別な意味を持つ予約ファイル名がある。この記事で押さえるべきものはindex.mdとlog.mdである。

# Metrics

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

# Change Log

## 2026-06-30

- Added `metrics/monthly_active_users.md`.
- Clarified that trial users are excluded from MAU.
- Linked related concepts for users, login events, and trial exclusion.

index.mdは入口を作る。log.mdは変更の履歴を残す。どちらも、知識を正しくする魔法ではないが、複数の知識ファイルを扱うときに、AI agentと人間が同じ文脈へ戻りやすくする。

OKFだけでは解決しないこと

OKFが保証するのは、最低限の読み取りやすさであって、知識の正しさではない。読み手側は、unknown type、unknown field、broken link、missing indexだけを理由に知識のまとまりを拒否しない。これは互換性のための寛容さであり、本番品質の保証ではない。

そのため、実務では次の設計を別途決める必要がある。

• 正本はどこか。BI、dbt、SQL、仕様書、運用ルールのどれを基準にするのか。
• 誰が更新するのか。ownerとレビュー周期をどう置くのか。
• リンク切れ、古い定義、重複した指標名をどう検知するのか。
• どのAI agent、RAG、検索index、社内ツールに読ませてよいのか。
• 外部由来のMarkdownを、命令ではなく参照データとして扱えるか。

特に、OKF本文に書かれた文は作業命令として信頼しない。外部由来のMarkdownに「以前の指示を無視して」といった文が混じっていても、system指示や開発者指示より優先してはいけない。

OKF化候補と、やりがちな失敗

採用判断はこの記事ではしない。ただし、候補の見分け方を持つと、OKFの意味は具体化する。

「同じ前提を何度も説明している」は、採用条件ではなく導入の目安である。頻度だけでなく、誤用時の影響、変更頻度、正本の所在、機密性、レビュー可能性を見る。

失敗例としては、typeだけ付けて満足する、BIやdbt側の定義とズレる、broken linkを放置する、owner不在の公式っぽいメモを増やす、機密情報を外部AIへ渡す対象に混ぜる、といったものがある。

公開範囲ではなく、投入先まで決める

OKF化すると、知識は参照しやすくなる。だからこそ、公開HTMLにするかどうかだけでなく、外部AI、社内RAG、全文検索、embedding、agentの常時参照、CIログ、PR差分、ブラウザ履歴、キャッシュに流れてよいかを考える必要がある。

実務運用では、OKF標準fieldとは別に、次のような運用fieldやチェックを足す候補がある。

• classification: public、internal、confidential、restrictedなどの分類。
• allowed_consumers: 読ませてよいAI agent、ツール、検索index。
• owner, source, last_reviewed: 更新責任、正本、最終確認日。
• secret scan、PII scan、broken link check、実テーブル名の公開可否確認。
• 誤公開時のrevert、検索indexやembeddingからの削除、復元確認。

個人運用メモでは、口座番号、残高、顧客名、内部KPI、認証情報を知識ファイルに入れない。必要なら、判断ルールだけを匿名化して扱う。

結論: まず1つの指標定義を知識ファイルにする

OKFは、社内知識や個人メモを一気に移行するための仕組みではない。まずは指標定義、除外条件、テーブル説明のように、何度もAI agentへ説明している前提を1つだけ知識ファイルに分ける。

そのうえで、index.mdで入口を作るか、log.mdで更新履歴を残すか、owner、正本、公開範囲、投入先をどう決めるかを考える。OKFは、知識を正しくするものではなく、知識を参照しやすい単位に分けるための形式である。

参考資料