Google OKF를 작성하여 검증했다: 에이전트용 지식의 필수 항목은 단 하나뿐

에이전트용 지식 관리라고 하면 벡터 DB (Vector DB)를 구축하고 싶어진다. RAG를 구성하고, 임베딩 (Embedding)을 만들고, 검색을 얹고. 하지만 Google이 최근 발표한 Open Knowledge Format (OKF)는 그 전 단계에서 멈춘다. 내용은 "Markdown 폴더를 git으로 배포하는 것뿐". 필수 필드는 type 하나였다.

사양을 처음 읽었을 때, 너무 텅 비어 있어서 허탈했다. 그래서 직접 손을 움직여 확인해 보았다. bundle을 작성하고, 준수 여부 체커 (Checker)를 작성하고, 소비하는 쪽의 코드도 돌려보았다. 결론부터 말하겠다. 사양을 준수하는 것은 5분이면 끝난다. 어려운 것은 그게 아니었다.

OKF v0.1은 2026년 6월 12일에 Google Cloud가 공개한, 에이전트용 지식 기술 포맷이다. SPEC과 샘플 bundle이 GitHub에 놓여 있다 (GoogleCloudPlatform/knowledge-catalog).

요점은 이것뿐이다.

• bundle = Markdown 파일이 들어 있는 디렉토리 트리
• 1개 개념 = 1개 Markdown 파일 (YAML frontmatter + 본문)
• frontmatter의 필수 항목은 type 뿐. title, description, resource, tags, timestamp는 전부 선택 사항.
• index.md와 log.md는 예약된 이름이며, 개념 파일에는 사용하지 않는다 - 소비 측은 관대하게 읽는다.
• 미지의 type, 미지의 키, 링크 끊김, index 누락으로 인해 "거부해서는 안 된다".
• 스키마 레지스트리 (Schema Registry)도 중앙 관리도 SDK도 없다. cat으로 읽을 수 있고 git clone으로 배포할 수 있다. 그것이 OKF의 전부다.

이 부분이 직관에 반한다. 보통 포맷은 항목을 엄격하게 정의할수록 훌륭하다고 생각한다. OKF는 그 부분을 버렸다. 엄격한 스키마는 진부해지기 쉽고, 벤더마다 방언이 늘어나 락인 (Lock-in)이 발생한다. 그래서 producer의 자유를 최대화하고, 정합성 담보는 소비 측의 관대함에 맡기고 있다. XML의 엄격한 검증 (Validation)에 모두가 지쳤던, 그 반성의 연장선에 있는 설계라고 생각한다.

이론보다 실물. 매출 관련의 작은 bundle을 작성해 보았다.

okf_demo/
├── index.md # 예약된 이름 · frontmatter 없음
├── log.md # 예약된 이름 · 업데이트 이력
...

개념 파일은 이런 느낌이다. tables/orders.md:

---
type: BigQuery Table
title: Orders
...

링크인 /tables/customers는 bundle 루트 상대 경로다. 이를 통해 개념 간의 관계를 맺을 수 있다. 개념 ID는 "파일 경로에서 .md를 제외한 것"이므로, 이 링크는 tables/customers.md를 가리킨다.

준수 조건은 3가지만 있다. 예약된 이름 이외의 모든 .md가 parse 할 수 있는 frontmatter를 가진다. 그 안에 비어 있지 않은 type이 있다. 예약 파일은 정해진 구조를 따른다. PyYAML로 솔직하게 작성할 수 있다.

import re, yaml
from pathlib import Path
RESERVED = {"index.md", "log.md"}
...

방금 만든 bundle에 적용하면 통과한다.

## OKF conformance
PASS

시험 삼아 type을 쓰는 것을 잊은 파일과, frontmatter가 없는 생 메모를 섞으면 제대로 걸러낸다.

## OKF conformance
NG note: frontmatter가 없거나 깨짐
NG orphan: 필수 필드 type이 비어 있음

준수 체크는 이것으로 완성되었다. 30줄도 쓰지 않았다. 사양이 작으니까 당연한 결과다.

문제는 여기서부터다. 준수하고 있는 bundle이 그대로 에이전트가 사용할 수 있는 지식인가 하면, 별개의 문제였다. 사양이 텅 비어 있다는 것은, 품질 체크가 통째로 자신의 숙제가 된다는 의미이기도 하다.

같은 bundle에 "운용 린터 (Linter)"를 적용했더니, conformance는 PASS인데 이것만 나왔다.

운영 린터 (operational lint) (사양은 통과하지만 운영에서 곤란한 점)

⚠ type 표기 불일치: ['BigQuery Table', 'bigquery table']은 동일하게 간주되지 않음 (routing이 갈림)
⚠ glossary/churn: description이 없음 (목록에서 어떤 개념인지 읽을 수 없음)
...

전부 사양상으로는 세이프(safe). 하지만 현장에서는 유효하다.

가장 무서운 것은 맨 앞의 type 표기 불일치다. orders.md는 BigQuery Table로, customers.md는 bigquery table로 작성했다. 사양에는 "type은 소비 측에서 routing에 사용한다"라고 되어 있다. 그렇다면 소비 측에서 생 문자열(raw string) 그대로 필터링하면 어떻게 될까.

# "BigQuery Table"로 필터링하면 customers가 조용히 사라짐
tables = [cid for cid, m in meta_by_id.items()
if m.get("type") == "BigQuery Table"] # -> ['tables/orders'] 만 남음

customers가 누락된다. 에러는 발생하지 않는다. 소비 측에서 casefold를 해야 비로소 양쪽 모두를 잡을 수 있다.

=== type=bigquery table 개념 ===
- tables/customers: 고객 마스터. 1고객 1행. resource=bq://acme.sales.customers
- tables/orders: 완료된 고객 주문이 한 행씩 들어가는 테이블. resource=bq://acme.sales.orders

사양의 "알 수 없는 type을 관대하게 처리하라"는 말은, 뒤집어 말하면 "type의 정규화(normalization)는 소비 측의 책임"이라는 뜻이다. 프로듀서(producer)는 얼마든지 표기를 흔들 수 있기 때문이다.

링크 깨짐도 같은 구조였다. revenue.md에서 /tables/order로 링크를 걸었지만, 정확하게는 orders이다. 사양에는 "링크 깨짐은 malformed가 아니다, 소비 측은 견뎌라"라고 명시되어 있다. 깨져 있어도 준수(conformance)는 통과한다. 그래서 준수 체크(conformance checker)와는 별개로, 링크 건전성을 확인하는 운영 린터(operational linter)를 가지고 있는 것이 현실적이었다.

참고로 index.md를 실수로 개념 파일로 작성하면 사고가 난다. 예약어이므로 frontmatter를 넣어서는 안 된다. 처음에 이 문제로 인해 index가 개념으로서 이중으로 나타나 고생했다.

OKF는 지식을 agent-ready 상태로 만들기 위한 최소공배수라고 생각한다. MCP 서버를 구축하기 전, RAG를 구성하기 전에, 사내의 테이블 정의나 용어집을 먼저 bundle로 만들어 둔다. 그러면 어떤 에이전트나 도구에도 동일한 소재를 흘려보낼 수 있다. git에 올라가기 때문에 차이(diff)가 보이고, 리뷰와 롤백(rollback)도 가능하다. 문서를 코드와 동일한 운영 체계로 떨어뜨릴 수 있다는 점이 은근히 크다.

오늘 직접 다뤄보며 확신한 것은, 사양의 얇음은 "편리함"이 아니라 "책임의 이양"이라는 점이다. 준수는 5분이면 끝나지만, type의 정규화, 링크의 건전성, 최신성(freshness)은 전부 이쪽의 몫이 된다. 따라서 OKF가 보급된다 하더라도, 성장하는 것은 포맷 본체가 아니라 이 운영 린터나 빌더(builder) 레이어가 될 것이다. 미리 준수 체크와 운영 린터를 CI에 넣어두면, bundle이 늘어나도 부패하지 않는다. 우선 자신의 팀 테이블 정의 20개 정도를 bundle화하는 것부터 시작하는 것이 딱 적당한 입구라고 생각한다.

참고: OKF SPEC / 샘플 bundle (GitHub) ・ How the Open Knowledge Format can improve data sharing (Google Cloud Blog)