OKF Bundle (번들링)

• OKF Bundle은 OKF concept 문서들을 담은 하나의 디렉터리 트리 — “a directory of markdown documents with YAML frontmatter that catalog tools, downstream agents, and humans can all read”
• concept 문서·index.md(목차)·log.md(이력)·references/(부수 문서)로 구성된 파일 기반 패키지
• git repo·tarball·zip으로 통째로 주고받는 이식 가능한 지식 묶음 — OKF (Open Knowledge Format)의 배포 단위
• 스키마 레지스트리·중앙 권위·필수 툴링이 없는 최소 규약(minimally opinionated) 정적 포맷

쉽게 이해하기

번들은 “주제별 메모 카드(=concept 문서)를 한 폴더에 정리해, 통째로 zip이나 git으로 건넬 수 있게 묶어둔 것”이다. 카드 한 장 = 개념 하나(테이블·지표·런북…)이고, 카드끼리는 본문 안의 링크로 연결된다. 폴더 맨 앞엔 목차 카드(index.md), 한쪽엔 수정 일지(log.md)가 있다. 이 폴더를 그대로 압축해 보내면 받는 쪽 — 사람이든 에이전트든 — 이 별도 도구 없이 펼쳐 읽는다.

그냥 markdown을 한곳에 모으면 안 되나? — OKF가 더하는 것

사실 OKF는 거창한 무언가가 아니다. 흩어진 markdown 더미에 상호운용에 꼭 필요한 최소 규칙(맨 위 type, 목차 index.md, 링크 규약)만 못 박은 것이다 — “no schema registry, no central authority, and no required tooling.” 그런데 이 작은 규약이 “그냥 .md 모으기”와 결정적 차이를 만든다.

AS-IS — 규약 없는 markdown 더미

flowchart LR
    F1[notes1.md] --> A[받는 사람/에이전트]
    F2[schema.txt] --> A
    F3[wiki page] --> A
    A -. 목차·타입·링크 규약 없음 .-> X((어디서부터 읽지?))

TO-BE — OKF Bundle

flowchart LR
    subgraph B["OKF Bundle (1개 디렉터리)"]
        IDX[index.md<br/>목차]
        C1["orders.md<br/>type: BigQuery Table"]
        C2[customers.md]
        LOG[log.md<br/>변경 이력]
        C1 -->|/tables/customers.md| C2
    end
    B -->|git / tarball / zip| H[사람: cat·GitHub]
    B -->|ingest| AG[에이전트: SDK 없이 파싱]

그냥 모아둔 더미 대비 OKF가 보장하는 것(공식 README가 정리한 이점):

• 도구 없이 읽힘 — “No SDK or query language stands between a reader and the content.” 사람은 cat·GitHub로, 에이전트는 별도 SDK 없이 파싱한다. LLM에게 좋은 포맷이 곧 사람에게도 좋은 같은 한 벌이라, “에이전트용 메타데이터”와 “사람용 위키”를 따로 둘 필요가 없다.
• 버전관리가 그냥 됨 — “Pull requests, line-by-line diffs, blame, and review workflows just work.”
• 이식성 — “No proprietary API stands between you and your metadata.” git/tarball로 어디로든 옮겨도 살아남는다.
• 구조 + 비구조 동시 — frontmatter(구조화 메타데이터)와 본문(prose·표·예시)을 의도적으로 함께 담는다.
• 기존 도구 호환 — Notion·Obsidian·MkDocs·Hugo·Jekyll이 이미 markdown + YAML frontmatter를 말한다.
• 관계 표현 — “Graph-shaped, not just tree-shaped” — 폴더 계층(트리)을 넘어 링크로 개념 간 관계를 표현한다.

번들 구조와 각 파일의 목적 (공식 스펙)

스펙이 제시하는 디렉터리 레이아웃은 다음과 같다.

path/to/bundle/
├── index.md          # 선택. progressive disclosure용 디렉터리 목차
├── log.md            # 선택. 변경 이력(최신순)
├── <concept>.md      # 루트에 놓인 concept 한 개
└── <subdirectory>/   # 하위 디렉터리로 concept들을 그룹화
    ├── index.md
    ├── <concept>.md
    └── <subdirectory>/
        └── …

각 구성요소가 왜 있는지, 무엇을 맡는지:

• concept 문서 (<concept>.md) — “A single unit of knowledge within a bundle. Represented as one markdown document.” 지식의 원자 단위 하나 = 파일 하나다. frontmatter의 type(필수)으로 종류를 라벨링하고, 본문에 스키마·예시·prose를 담는다.
• index.md (예약) — 어느 디렉터리에나 올 수 있는 목차. 그 폴더에 무엇이 있는지 문서를 열어보기 전에 훑게 해준다(progressive disclosure). README 표현으로는 번들 전체를 한꺼번에 context에 올리지 않고 “one level at a time” 으로 내려가며 탐색한다. 보통 자동 생성되며, 없으면 consumer가 즉석에서 합성할 수 있다.
• log.md (예약) — 계층의 어느 수준에나 올 수 있는 변경 이력. 그 scope의 변화를 최신순·ISO 8601(YYYY-MM-DD)로 기록한다. **Update**·**Creation**·**Deprecation** 같은 굵은 머리말은 관습이지 필수가 아니다.
• references/ — enrichment 과정에서 발견됐지만 기존 concept에 딱 들어맞지 않는 독립 문서를 모아두는 곳.
• 하위 디렉터리 — 도메인에 맞게 자유롭게 구성한다 — “The directory structure is independent of the domain — producers organize concepts however makes sense.”

frontmatter는 type 하나만 필수다(routing·filtering·presentation 용도이며 중앙 등록 체계가 없다). 권장 필드는 우선순위 순으로 title·description·resource·tags·timestamp.

왜 한 파일이 아니라 여러 파일·디렉터리인가

“전부 한 .md에 적으면 안 되나?”에 대한 답은, 이 구조가 단일 파일로는 못 주는 네 가지를 주기 때문이다.

• 원자적 diff — OKF는 “Diffable in version control”. concept마다 파일이 나뉘어 있어 PR에서 무엇이 바뀌었는지가 줄 단위로 드러난다. 거대한 단일 파일은 작은 수정도 diff·blame이 지저분해진다.
• progressive disclosure — 에이전트는 context window가 한정적이고 사람도 전부 읽고 싶지 않다. index.md로 목차만 보고 필요한 concept 파일만 펼친다. 한 파일이면 매번 전체를 통째로 로드해야 한다.
• 그래프 ≠ 트리 — concept가 파일로 쪼개져 서로를 링크하면 방향성 엣지의 그래프가 된다. 한 파일 안의 앵커 링크만으로는 이 관계망을 깔끔히 표현하거나 탐색하기 어렵다.
• 라우팅·검색 단위 — type이 붙은 concept 단위라, consumer가 종류별로 필터링하거나 에이전트가 관련 카드 한 장만 골라 가져올 수 있다.

지식을 잇는 법: 링크와 references/

concept끼리는 평범한 markdown 링크로 잇는다. 링크에는 절대 경로(/tables/customers.md — 권장, 문서를 옮겨도 안정적)와 상대 경로가 있다. “A link from concept A to concept B asserts a relationship” 이되, 관계의 종류(parent/child·joins-with·depends-on…)는 링크 자체가 아니라 주변 prose가 말해준다. 또 “Consumers MUST tolerate broken links” — 대상이 아직 없는 링크는 깨진 게 아니라 아직 쓰지 않은 지식일 수 있다.

그래서 이미 A가 있고 연관된 B가 들어올 때 A에 합쳐지는지가 궁금할 수 있는데 — 포맷 자체에는 자동 병합·중복제거 규칙이 없다(각 concept은 개별/discrete). 합칠지 말지는 producer의 판단이고, 레퍼런스 enrichment agent는 페이지마다 다음 중 하나를 고른다.

flowchart TB
    NEW[새 정보 B] --> Q{기존 concept A와<br/>얼마나 연관?}
    Q -->|강하게 연관| ENRICH["enrich<br/>A 문서에 B를 보강 (합침)"]
    Q -->|독립 가치 있음| MINT["mint<br/>references/&lt;slug&gt; 새 문서 → A와 링크"]
    Q -->|불필요| SKIP[skip]

즉 B는 (a) A 문서에 보강되어 합쳐지거나, (b) references/<slug>로 독립 문서가 되어 A와 링크로 이어진다. 어느 쪽이든 관계는 결국 링크 그래프로 남는다. 자동으로 합쳐지는 게 아니라, 생산 주체가 정하고 형식은 그것을 허용할 뿐이다.

원문을 그대로 넣나, 재가공하나

포맷은 재가공을 강제하지 않는다. producer와 consumer가 독립이라 “어떻게 만들었는지”를 따지지 않는다 — 사람이 손으로 써도, 에이전트가 생성해도 같은 번들이다. 다만 스펙은 “Producers SHOULD favor structural markdown — headings, lists, tables, fenced code blocks — over freeform prose, since structure aids both human reading and agent retrieval” 라고 권한다.

그래서 enrichment agent 같은 생산 에이전트는 원문을 그대로 복붙하기보다 frontmatter(구조화 메타데이터) + 본문(스키마 표·예시)으로 재구조화한다. “안녕하세요 → 안녕” 같은 임의의 표면 텍스트 축약이 목적이 아니라, 검색·이해에 유리한 구조로 원의미를 정리하는 것이다.

규격이지 프로토콜이 아니다 (MCP와의 차이)

OKF를 “MCP 같은 하나의 규격”으로 이해했다면 방향은 맞다 — 둘 다 벤더 중립 개방 표준으로, 모두가 각자 변환기를 만들던 N×M 통합 문제를 줄이는 “lingua franca”다. 차이는 층위에 있다.

	MCP	OKF
정체	프로토콜 (runtime)	정적 데이터 포맷
하는 일	에이전트가 도구·데이터와 실시간 대화	지식을 파일로 적어둠
비유	HTTP / API	Markdown · JSON 같은 파일 포맷
실행	요청/응답·세션 있음	실행·쿼리·런타임 없음

MCP는 “실시간으로 대화하는 방법”, OKF는 “지식을 파일로 적어두는 방법”이다. 둘은 경쟁이 아니라 보완 관계다 — 에이전트는 “Parseable by agents without bespoke SDKs” 인 OKF 번들을 (예: Knowledge Catalog가 ingest해) 컨텍스트로 받아 쓴다.

참고 문서

• OKF SPEC.md §3 Bundle Structure (GitHub)
• OKF repo & enrichment agent README (GitHub)
• How the Open Knowledge Format can improve data sharing (Google Cloud Blog)