0
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

できたばかりのOKFを自社システムに入れてみた。実装した日に境界が見えた

0
Posted at

TL;DR: Google Cloudが2026年6月に公開したばかりのOKF(Open Knowledge Format)を、実際に自社システムに入れてみた。Markdown + YAML frontmatterだけで作るエージェント向け知識層の仕様で、既存ファイルにYAMLを足すだけの低コストな試みだった。ところが実装した当日のうちに、OKFの価値よりも先にOKFの境界(適用範囲)が見えた。OKFは一次情報源ではなく、安定した知識をエージェント向けに映す「鏡」であり索引層だ、という話。


OKFとは何か

Google Cloudが2026年6月に公開したOpen Knowledge Format(OKF v0.1)は、「散在した知識を整理する」ための仕様だ。まだ始まったばかりの仕様で、この記事を書いている時点でも公開から1ヶ月経っていない。

技術的にはシンプルで、MarkdownとYAML frontmatterだけで構成される。唯一の必須フィールドは type のみ。

---
type: workflow
title: 市場調査モニタリング
owner: human-pm
updated_at: 2026-07-04
source:
  - ops_reports/systems/medium_scout/
---

# 市場調査モニタリング

## Purpose

毎日の記事候補収集・レビューワークフロー。

## Required Steps

- ブラウザ付きMediumメタデータ収集を実行する
- ブラウザカバレッジを確認する
- GitHub Issueを作成または更新する
- HumanがIssueに判断を記録する

設計の3原則(一次ソース):

  1. 制限が最小限 — 必須フィールドは type だけ
  2. プロデューサーとコンシューマーの独立性 — 書く側と読む側が分離
  3. プラットフォームではなく、形式 — クラウド・DB・モデルに非依存

サンプルのYAMLに含まれる owner や source はOKF標準の必須フィールドではなく、自社で追加した拡張フィールドだ。「MarkdownにYAMLを足しただけなら、自前フォーマットで十分では」という疑問はもっともだが、Googleの仕様に乗る利点は将来的なツール共通化(linter、パーサー、他のエージェントとの相互運用)にある。今はその恩恵をまだ受けていないが、仕様に沿っておけば後から入ってくる。

OKFは検索の仕組みではない。「安定した定義・ルール・ワークフローをエージェントがナビゲートできる形に整理する」ための仕様だ。

自社システムに散在する運用知識

自社システムでは、ClaudeCode・Codexの2つのAIワーカーが記事の調査・執筆・管理を行っている。すでに以下のドキュメントがエージェント向け知識として機能している。

ファイル 役割
CLAUDE.md ClaudeCode行動ルール・制約
AGENTS.md 複数ワーカー役割分担・協調ルール
.claude/skills/ タスク別プレイブック
ops_reports/rules/ 品質ゲート群
ops_reports/worker_board/ 現在タスク状態

自社システムの知識層 — OKF化前後

ただし構造はバラバラで、エージェントが参照先を毎回推測している。

実装設計 — 最小PoC

いきなり全てを変換せず、まず9ファイルから始める設計を立てた。

okf/
├── index.md                         # バンドルナビゲーション
├── workflows/
│   ├── medium_scout.md              # 市場調査モニタリング
│   ├── article_issue_creation.md    # 記事Issue作成手順
│   └── publication_stats.md        # KPI集計ワークフロー
├── rules/
│   ├── scout_quality_gate.md        # 市場調査品質ゲート
│   ├── public_comment_gate.md       # 公開コメントルール
│   └── source_verification.md      # ソース検証ルール
└── agents/
    ├── codex.md                     # Codex運用ポリシー
    └── claudecode.md               # ClaudeCode運用ポリシー

変換元ファイルの調査で、それぞれの対応が明確になった。

OKFファイル 変換元(確認済み) 性質
workflows/medium_scout.md(市場調査プログラムの仕様) docs/MEDIUM_SCOUT_V0_1_SPEC.md + V0_2_REQUIREMENTS.md 業務の仕様書・要件定義書
workflows/publication_stats.md tools/publication_stats/README.md + nightly runner設計書 ツールのREADME・運用設計書
workflows/article_issue_creation.md AGENTS.md + .claude/skills/ 内の該当スキル チーム内の役割分担・手順書
rules/scout_quality_gate.md ops_reports/rules/article_quality_gate.md §Idea/Shape/Substance Gate 評価基準・判断ルール
rules/public_comment_gate.md ops_reports/rules/article_quality_gate.md §Public Comment Gate 評価基準・判断ルール
rules/source_verification.md CLAUDE.md §10(Knowledge Boundary Assertion Rule) 行動制約ルール
agents/codex.md AGENTS.md §8(Codex GitHub Invocation Rule) 役割定義・権限ルール
agents/claudecode.md AGENTS.md + CLAUDE.md ClaudeCode担当部分 役割定義・権限ルール

新しいコンテンツを一から書く必要はない。既存ファイルにYAML frontmatterを付加して、ファイル間の相対リンクを整理するだけだ。

OKF PoC ファイルマッピング

設計レビュー結果: Codexにレビューを依頼し、PASS_WITH_NOTES を取得。ブロッキング問題なし。実装方針: additive(既存ファイルを破壊しない)/ concise(冗長な転記不要)/ source-linked(変換元へのリンクを保持)。

変換しないもの

OKFに向かない、あるいは今すぐ変換しなくていいもの:

  • GitHub Issues — 動的かつ変化が多い。そのままでいい
  • 市場調査記録(Medium/Substack上の関連記事の収集・評価ログ) — 横断検索の対象
  • 日次ops_reports(AIワーカーが書く作業日報) — 時系列記録。整理不要

OKFは「安定していて、エージェントが何度も参照する知識」に向いている。更新頻度が高いもの・一度きりの記録には向かない。

実装コストは低い。リスクも低い(okf/ ディレクトリを削除すれば元に戻る)。ただし、ここで言う「コストが低い」は初期導入コストの話だ。OKFを要約レイヤーとして置く以上、元ファイルとの同期コストは別に残る。導入自体の失敗より、導入後に静かに古びることの方が、実際に見るべきリスクかもしれない。

実装した日に、OKFの境界が見えた

実装後すぐに、OKFの価値よりも先に、OKFの境界が見えた。それは「OKFに入れるべき知識」と「まだOKFに入れてはいけない知識」を分ける実例だった。

OKFバンドルを実装したPRで、@codex review を同じコミットに対して43分間で4回送ってしまう事故が起きた。

原因はOKFの設計ではない。Codexのレビュー結果は issue comment ではなく PR Reviews API (pulls/N/reviews) に届くのに、監視ロジックが issue comment だけをポーリングして「10分応答なし」と誤判定し、再依頼を繰り返していた。

この事故はOKFの対象外だった。「変換しないもの」に書いた通り、OKFは安定したルールの置き場であり、動的な運用トラブルそのものは拾えない。実際、修正は先に CLAUDE.md §6 と ops_reports/rules/aiworker_state_file_coordination.md にルール(PR単位のロックファイル codex_review_locks.json)として書き、そのあとで okf/agents/codex.md に要約を反映した。OKFはルールが生まれる場所ではなく、安定してから置く場所だ。

この「後から反映する」作業自体が実装コストの実感になった。ルールを1箇所変更するたびに、OKF側の対応ファイルも手動で追随させる必要がある。今回は半日で3回この同期をした。整合性をチェックするCIやlintはまだない——放置すれば静かに陳腐化する設計だ。


OKF v0.1はまだ始まったばかりの仕様だ(GitHub)。「どこまでをOKFで整理し、どこからをSkillやCLAUDE.mdに任せるか」という境界線は、実装した初日に早くも見えてきた。OKFは一次情報源ではない。ルールが生まれる現場でもない。OKFは知識が生まれる場所ではなく、すでに安定した知識を映す鏡だ。鏡が実物とズレないよう磨き続けるのは、結局は人間かエージェントの仕事として残る。

できたばかりのOKFを自社システムに入れてみた — まとめ


出典: Google Cloud ブログ — Open Knowledge Format のご紹介 · OKF GitHub

0
2
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?