OKF: 에이전트를 위한 구글의 마크다운 스펙

2026년 6월 12일, 구글 클라우드는 AI 에이전트가 큐레이션된 지식을 읽고 교환하는 방식에 대한 스펙을 발표했습니다. 그래프 데이터베이스나 스키마 레지스트리, SDK, 그리고 그것을 돌릴 서비스를 기대했을지도 모릅니다.

하지만 오픈 지식 포맷(Open Knowledge Format, OKF)의 실체는 이렇습니다: YAML frontmatter가 있는 마크다운 파일들의 디렉터리.

그게 포맷의 전부입니다. 그리고 그 절제야말로 흥미로운 지점입니다.

스펙은 생각보다 작다

OKF에 대해 쓴 글 대부분은 발표 내용을 요약하는 데 그칩니다. 스펙 원문을 직접 읽어볼 가치가 있습니다 --- 다루는 범위가 놀라울 만큼 작기 때문입니다.

OKF v0.1이 모든 개념 문서에 요구하는 필드는 딱 하나뿐입니다:

---
type: BigQuery Table
---

끝입니다. type은 문서가 어떤 종류의 개념을 설명하는지 나타내는 짧은 문자열로, 라우팅과 필터링에 쓰입니다. 값은 중앙에서 등록하지 않습니다 --- 유효한 타입 목록을 승인하는 위원회 같은 건 없습니다. 생산자는 알아보기 쉬운 이름을 골라 그냥 쓰면 됩니다.

권장되는 필드가 다섯 개 더 있지만, 어느 것도 필수는 아닙니다:

필드	용도
title	표시 이름. 없으면 소비자가 파일명에서 유추할 수 있습니다.
description	한 문장 요약.
resource	기반 자산을 고유하게 식별하는 URI.
tags	교차 분류를 위한 YAML 리스트.
timestamp	마지막 수정 시각의 ISO 8601 날짜시간.

생산자는 원하는 커스텀 키를 자유롭게 추가할 수 있습니다. 소비자는 알 수 없는 필드를 거부하지 말고 그대로 보존해야 합니다.

완전하고 규격에 맞는 개념 문서는 이런 모습입니다:

---
type: BigQuery Table
title: Orders
description: One row per completed customer order.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders]
timestamp: 2026-05-28T00:00:00Z
---

# Schema

| Column | Type | Description |
|--------|------|-------------|
| order_id | STRING | Unique identifier |

Obsidian에서 frontmatter가 있는 노트를 써본 적이 있다면, 이미 유효한 OKF 개념 문서에 아주 가까운 것을 써본 셈입니다.

그래프 데이터베이스 없는 지식 그래프

OKF를 도입하든 안 하든, 훔쳐올 가치가 있는 설계 결정이 하나 있습니다.

개념 간의 관계는 표준 마크다운 링크로 표현됩니다. 데이터베이스의 엣지가 아닙니다. frontmatter의 relationships: 블록도 아닙니다. 그냥 링크입니다:

Each order references a [customer](/tables/customers.md).

안정성을 위해 번들 기준 절대 경로(/로 시작)가 권장되지만, ./other.md 같은 일반 상대 경로도 작동합니다.

그리고 이걸 실제로 작동하게 만드는 부분: 관계의 종류는 링크가 아니라 주변 문장이 전달합니다. “각 주문은 고객을 참조한다”는 문장 자체가 곧 엣지 레이블입니다. 유지할 온톨로지도, 합의할 술어 어휘도 필요 없습니다. 자연어가 이미 그 역할을 하고 있고, 소비자는 언어 모델이기 때문입니다.

지난 10년간 지식 그래프 툴링은 기계가 해석할 수 있도록 관계 유형을 형식화하는 데 공을 들여왔습니다. OKF의 베팅은 이게 더는 필요 없다는 것입니다 --- 이제 기계가 영어를 직접 읽으니까요.

예약된 두 개의 파일명

번들 안에서 특별한 의미를 갖는 파일명은 딱 두 개뿐입니다:

• index.md --- 점진적 공개(progressive disclosure)를 가능하게 하는 디렉터리 목록입니다. frontmatter가 없습니다. 에이전트는 모든 개념을 컨텍스트에 로드하는 대신, 먼저 인덱스를 읽고 필요한 링크만 따라갑니다.
• log.md --- ISO 8601 날짜 헤딩을 사용하는 시간순 업데이트 히스토리이며, 최신 항목이 맨 위에 옵니다.

그 외의 모든 .md 파일은 개념 문서입니다. 결국 번들은 평범하게 탐색 가능한 폴더처럼 보이게 됩니다:

sales/
├── index.md
├── datasets/orders_db.md
├── tables/orders.md
└── metrics/weekly_active_users.md

조용히 중요한 것은 index.md입니다. 잘 쓰인 CLAUDE.md 뒤에 있는 것과 같은 본능입니다: 라이브러리 전체를 컨텍스트 윈도우에 쏟아붓지 말고, 에이전트에게 목차를 건네준 뒤 필요한 것을 가져오게 하라는 것이죠.

OKF가 아닌 것

RAG가 아닙니다. RAG는 원시 청크를 검색해 관련된 것이 떠오르길 바라며, 쿼리 시점에 지식을 다시 도출합니다. OKF 번들은 에이전트가 직접 읽고 갱신하는, 큐레이션되고 상호 링크된 개념을 저장합니다. 큐레이션은 매 쿼리마다 근사되는 대신 한 번, 의도적으로 이루어집니다.

AGENTS.md나 CLAUDE.md도 아닙니다. 그것들은 지시 파일입니다 --- 에이전트에게 리포지토리에서 어떻게 행동할지 알려줍니다. OKF는 주제 지식을 설명합니다: 이 테이블이 뭘 의미하는지, 이 지표가 어떻게 정의되는지, 왜 이 데이터셋에 3월 구간이 비어 있는지. 하는 일이 다르고, 서로 보완적입니다.

MCP도 아닙니다. MCP는 에이전트를 라이브 시스템에 연결하는 런타임 프로토콜입니다. OKF는 디스크에 정지해 있는 파일 포맷입니다. 둘 다 함께 쓰는 게 자연스러울 겁니다: 웨어하우스에 접근하는 건 MCP, 그 안에 뭐가 있는지 설명하는 건 OKF.

준수 규칙은 의도적으로 관대하다

번들이 OKF v0.1을 준수하려면, 예약되지 않은 모든 .md 파일에 파싱 가능한 YAML frontmatter가 있어야 하고, 모든 frontmatter 블록에 비어 있지 않은 type이 있어야 하며, 예약된 파일이 존재할 경우 그 구조를 따라야 합니다.

더 말해주는 건 스펙이 소비자에게 금지하는 것들입니다. 소비자는 선택 필드 누락, 알 수 없는 type 값, 알 수 없는 키, 깨진 상호 링크, 또는 index.md 부재를 이유로 번들을 거부해서는 안 됩니다.

이것은 번들이 절반쯤 완성되고, 부분적으로 기계 생성되며, 끊임없이 변한다고 예상하는 사람들이 설계한 포맷입니다 --- 그리고 실제 지식 베이스가 정확히 그런 모습입니다. 엄격한 포맷은 자신의 엄격함 때문에 죽습니다. 이 포맷은 지저분한 폴더와 부딪혀도 살아남도록 만들어졌습니다.

구글은 이와 함께 레퍼런스 툴링도 내놓았습니다: BigQuery 보강 에이전트, 정적 HTML 시각화 도구, 그리고 샘플 번들 세 개.

분명히 짚어둘 단서 하나: OKF는 v0.1이며 명시적으로 초안입니다. 스펙은 버전이 관리되고 하위 호환 성장을 위해 설계되었지만, 필드명과 관례는 여전히 바뀔 수 있습니다. 오늘 당장 지식 베이스를 이것을 중심으로 다시 짜지는 마세요. 다만 표준이 어느 방향을 가리키는지는 눈여겨봐 두시길.

구글 클라우드를 넘어서는 이유

BigQuery 예시를 걷어내면, OKF는 훨씬 더 큰 파급 범위를 가진 베팅입니다: 기계가 읽을 수 있는 지식의 내구적인 포맷은 여러분이 소유한 폴더 안의 평범한 마크다운 파일이라는 베팅입니다.

API가 달린 독점 카탈로그가 아닙니다. 읽을 수 없는 벡터 스토어의 임베딩도 아닙니다. 표를 망가뜨리는 내보내기 버튼이 달린 위키도 아닙니다. 파일입니다. 디스크 위에. diff가 가능하고, grep이 가능하고, 벤더 간에 이동 가능하며, 사람도 시장의 모든 모델도 읽을 수 있습니다.

이것은 Claude Code, Cursor, Copilot, Windsurf가 각자 독립적으로 마크다운을 지시 파일 포맷으로 선택하며 도달한 것과 같은 결론입니다. 구글 클라우드가 이걸 스펙으로 적어낸 건 발명이 아니라 확인입니다.

Minibase가 맞아 들어가는 지점

Minibase Vault를 쓰고 있다면, 이미 구조적으로 OKF 번들에 가까운 것을 유지하고 있는 셈입니다: 여러분의 디스크 위에 있는, frontmatter가 있는 마크다운 파일 폴더이고, Claude와 ChatGPT가 읽는 폴더입니다.

이걸 공식적으로 준수하게 만드는 건 작은 편집 하나면 됩니다 --- frontmatter에 type을 추가하고, 나머지는 링크가 하게 두세요:

---
type: Article
title: How the Open Knowledge Format can improve data sharing
resource: https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/
tags: [okf, agents, markdown]
timestamp: 2026-07-19T00:00:00Z
---

이것이 이번 발표의 실질적인 형태입니다. 에이전트 지식 베이스에서 어려운 부분은 파일 포맷이었던 적이 없습니다 --- 어려운 건 좋은 원본 자료를 그 안에 채워 넣는 일이었습니다. 스펙은 폴더를 어떻게 만들지 알려줄 뿐, 그것을 채워주지는 않습니다.

Minibase는 바로 그걸 채우는 부분입니다: 클릭 한 번으로 어떤 웹페이지든 --- 문서, GitHub README, 스펙, 스레드, 리서치 논문 --- 여러분의 폴더 안에 놓인 깔끔한 마크다운으로 바뀌어, 다음에 실행할 에이전트가 바로 쓸 수 있게 됩니다.

포맷은 이제 표준입니다. 그 안에 무엇을 채우느냐는 여전히 여러분의 경쟁력입니다.

---

Minibase는 어떤 웹페이지든 여러분의 에이전트가 읽을 수 있는 깔끔한 마크다운으로 바꿔줍니다 --- 확장 프로그램 설치하기하고 에이전트를 더 똑똑하게 만드는 번들 구축을 시작하세요.