Field Log · Entry

Open Knowledge Format(OKF)란? AI 에이전트 지식을 Markdown으로 공유하는 법

흩어진 문서가 Markdown과 YAML 기반 Open Knowledge Format 묶음으로 정리되어 사람과 AI 에이전트에 전달되는 구조

먼저 30초 요약

Open Knowledge Format(OKF)은 새로운 지식관리 서비스가 아니라 지식을 파일로 주고받기 위한 공개 형식입니다.

지식 하나를 YAML frontmatter가 붙은 Markdown 파일 하나로 표현하고, 폴더와 링크로 전체 구조를 만듭니다.

사람, AI 에이전트, 검색기, 시각화 도구가 같은 파일을 읽을 수 있어 특정 벤더의 API에 덜 묶입니다.

원문이 소개한 v0.1 이후 현재 v0.2는 출처, 생성자, 검증자, 상태, 유효기한 같은 신뢰 신호를 추가했습니다.

단, OKF가 검색·권한·정확성을 자동으로 해결하지는 않습니다. 형식 위에 검수와 운영 절차를 따로 세워야 합니다.

Open Knowledge Format(OKF)은 조직 곳곳에 흩어진 맥락을 Markdown 파일과 YAML 메타데이터로 묶어 옮길 수 있게 만드는 규칙입니다. 쉽게 말해, AI 에이전트용 지식을 어느 서비스의 데이터베이스에만 가두지 않고 폴더째 건네기 위한 공통 포장 방식입니다.

Google Cloud의 소개 글은 OKF v0.1을 설명합니다. 핵심 아이디어는 단순하지만 원문에는 데이터 카탈로그, 에이전트, LLM Wiki 이야기가 한꺼번에 나와 처음 읽으면 범위가 크게 느껴집니다. 이 글에서는 “왜 필요한가, 파일은 어떻게 생겼는가, 무엇까지 해결하는가” 순서로 풀어보겠습니다.

한 가지 업데이트도 먼저 짚겠습니다. 원문은 2026년 6월 공개된 v0.1 기준이고, 이 글을 쓰는 2026년 8월 3일 현재 공식 명세는 v0.2입니다. 기본 구조는 그대로이며, v0.2에서 신뢰와 최신성을 판단할 선택 필드가 늘었습니다.

왜 AI 에이전트에게 또 다른 지식 형식이 필요할까?

어떤 회사에서 “주간 활성 사용자 수를 계산해 줘”라고 AI 에이전트에게 요청했다고 가정해 보겠습니다. 정답에 필요한 정보는 보통 한곳에 있지 않습니다.

이벤트 테이블의 스키마는 데이터 카탈로그에 있습니다.
활성 사용자의 업무 정의는 Notion이나 사내 Wiki에 있습니다.
테스트 계정을 제외하는 조건은 SQL 또는 코드에 숨어 있습니다.
오래된 지표를 쓰지 말라는 공지는 메신저에 남아 있습니다.
두 테이블을 어떻게 조인하는지는 담당자의 머릿속에만 있을 수도 있습니다.

모델이 아무리 좋아도 이 맥락을 받지 못하면 조직만의 정의를 알 수 없습니다. 반대로 모든 문서를 무작정 넣으면 오래된 정의와 현재 정의가 섞이고, 어느 근거를 사용했는지 추적하기 어려워집니다. 원문이 지적하는 핵심 문제도 모델 성능보다 조직 지식의 파편화와 이식성 부족입니다.

데이터 카탈로그, 위키, 코드, 런북에 흩어진 맥락을 Open Knowledge Format 묶음으로 정리해 사람과 AI 에이전트가 함께 소비하는 흐름

그림 1. OKF는 새로운 답변 엔진이 아니라, 여러 생산자와 소비자 사이에서 지식 파일의 모양을 맞추는 중간 형식이다.

각 제품이 서로 다른 API와 스키마로 지식을 내보내면 새 에이전트를 붙일 때마다 변환기를 다시 만들어야 합니다. OKF는 이 지점에서 “또 하나의 서비스”가 아니라 서비스 사이를 이동할 수 있는 형식을 제안합니다.

OKF를 한 문장으로 설명하면

개념 하나를 Markdown 파일 하나로 만들고, 검색에 필요한 최소 메타데이터는 YAML frontmatter에 넣으며, 폴더와 일반 Markdown 링크로 지식의 구조와 관계를 표현하는 형식입니다.

CSV가 표 데이터를 여러 도구 사이에서 옮기는 데 쓰이고 OpenAPI가 HTTP API의 계약을 표현하듯, OKF는 사람과 에이전트가 함께 읽을 지식의 교환 표면을 맞추려는 시도라고 보면 쉽습니다. 중요한 점은 OKF가 서버도, 데이터베이스도, SDK도 아니라는 것입니다.

구분	OKF가 정하는 것	OKF가 정하지 않는 것
저장 단위	개념 하나당 Markdown 파일 하나	어느 클라우드나 데이터베이스에 둘지
구조	폴더, 파일 경로, `index.md`, `log.md`	모든 조직이 따라야 할 고정 분류 체계
메타데이터	YAML frontmatter의 공통 필드	전용 SDK나 중앙 스키마 레지스트리
관계	일반 Markdown 링크	별도 지식 그래프 엔진
신뢰 신호	출처·생성·검증·상태·유효기한을 적는 방법	사실 여부의 자동 판정과 접근 권한
소비 방식	사람이 읽고 기계가 파싱할 수 있는 파일	검색, RAG, UI, 에이전트 런타임의 구현

즉 OKF의 야심은 기능을 모두 제공하는 데 있지 않습니다. 여러 도구가 최소한 같은 파일을 놓고 대화하게 만드는 것이 목표입니다.

폴더 하나와 파일 하나만 보면 구조가 보인다

OKF 묶음(bundle)은 평범한 디렉터리입니다. 예를 들어 영업 데이터 지식을 정리한다면 다음처럼 만들 수 있습니다.

sales/
├── index.md
├── log.md
├── tables/
│   ├── index.md
│   ├── orders.md
│   ├── events.md
│   └── customers.md
├── metrics/
│   ├── index.md
│   └── weekly-active-users.md
├── references/
│   └── event-contract.md
└── playbooks/
    └── freshness-alert.md

파일 경로에서 .md를 뺀 값이 그 개념의 식별자가 됩니다.
index.md는 해당 폴더에 무엇이 있는지 먼저 보여 주는 선택 파일입니다.
log.md는 변경 이력을 날짜순으로 남기는 선택 파일입니다.
나머지 .md 파일은 테이블, 지표, API, 런북 같은 개념을 표현합니다.

Open Knowledge Format의 한 개념 파일이 경로 식별자, YAML frontmatter, Markdown 본문과 링크로 구성되는 방식

그림 2. frontmatter는 빠른 필터링과 신뢰 판단에, 본문은 설명과 예시에, 링크는 개념 사이의 관계에 쓰인다.

metrics/weekly-active-users.md는 다음처럼 작성할 수 있습니다.

---
type: Metric
title: Weekly Active Users
description: 최근 7일 안에 핵심 행동을 한 중복 제거 사용자 수
tags: [product, engagement]
generated:
  by: human:data-platform
  at: 2026-08-03T09:00:00+09:00
verified:
  - by: human:analytics-owner
    at: 2026-08-03T10:00:00+09:00
status: stable
stale_after: 2026-12-31
sources:
  - id: event-contract
    resource: /references/event-contract.md
    title: Product event contract
---

# Definition

최근 7일 안에 `core_action` 이벤트를 한 고유 사용자를 센다.
테스트 계정과 내부 운영 계정은 제외한다.[^event-contract]

# Related concepts

- [Event table](/tables/events.md)
- [Freshness alert playbook](/playbooks/freshness-alert.md)

[^event-contract]: Product event contract

여기서 항상 필수인 frontmatter 필드는 type 하나뿐입니다. title, description, resource, tags는 권장 필드이고 나머지는 필요할 때 선택합니다. 생산자가 자체 필드를 더 넣어도 소비자는 모르는 필드 때문에 문서 전체를 거부하지 않아야 합니다. 이 느슨함이 서로 다른 도메인을 한 형식에 담을 수 있게 합니다.

본문은 일반 Markdown입니다. 표, 목록, 코드 예제, 설명을 그대로 쓸 수 있습니다. 다른 개념을 일반 링크로 연결하면 폴더의 부모·자식 관계를 넘어 “이 지표는 이 테이블과 런북에 의존한다” 같은 그래프가 생깁니다.

단순한 파일 형식이 왜 유용할까?

1. 사람과 에이전트가 같은 원본을 읽는다

사람용 Wiki와 에이전트용 JSON을 따로 유지하면 둘 중 하나는 곧 낡습니다. OKF는 사람이 편집기에서 읽는 본문과 에이전트가 파싱하는 메타데이터를 한 파일에 둡니다. 변환 계층이 줄고, 잘못된 내용을 사람이 발견해 바로 고치기도 쉽습니다.

2. Git의 검토 방식을 그대로 쓸 수 있다

파일이므로 diff, commit, branch, pull request, blame을 사용할 수 있습니다. “지표 정의가 언제 바뀌었나”, “누가 검토했나”, “문제가 생기기 전 버전은 무엇인가”를 코드와 비슷한 방식으로 다룰 수 있습니다. Git이 필수는 아니지만 공식 명세도 배포 방식으로 Git 저장소를 권장합니다.

3. 생산자와 소비자를 분리한다

사람이 손으로 쓴 묶음을 AI 에이전트가 읽을 수 있고, 데이터 카탈로그가 내보낸 묶음을 정적 뷰어가 보여 줄 수도 있습니다. 한 에이전트가 만든 파일을 다른 모델이 소비해도 됩니다. 계약은 OKF이고 양쪽 도구는 교체할 수 있습니다.

4. 필요한 만큼만 읽는 구조를 만들기 쉽다

에이전트가 묶음 전체를 매번 읽을 필요는 없습니다. 먼저 index.md와 frontmatter를 보고 관련 파일을 좁힌 뒤 본문을 열 수 있습니다. 이런 점진적 공개는 긴 컨텍스트를 무작정 채우는 것보다 비용과 혼선을 줄이는 데 유리합니다. 실제 검색 계층은 LLM Wiki가 문서를 찾는 과정에서 다룬 것처럼 FTS, 임베딩, 재정렬을 별도로 붙일 수 있습니다.

원문의 v0.1과 현재 v0.2는 무엇이 다를까?

원문을 읽을 때 가장 헷갈릴 수 있는 부분은 버전입니다. Google Cloud의 첫 소개와 v0.2 발표를 시간순으로 놓으면 변화가 단순해집니다.

시점	버전	핵심
2026년 6월	v0.1	Markdown, YAML frontmatter, 폴더, 링크라는 최소 교환 형식 제시
2026년 7월	v0.2	출처, 생성·검증 주체, 신뢰 단계, 상태, 유효기한, 검증 가능한 계산 표현 추가

v0.2가 던지는 질문은 다섯 가지입니다.

이 내용은 무엇을 근거로 만들었는가?
누가 만들었고 누가 확인했는가?
아직도 최신 정보인가?
초안, 안정 버전, 폐기 상태 중 어디에 있는가?
이 숫자는 약속된 계산 방법으로 만들어졌는가?

이를 위해 sources, generated, verified, status, stale_after 같은 선택 필드와 Attested Computation 개념이 추가됐습니다. 모든 필드를 강제한 것은 아닙니다. type만 항상 필수라는 원칙은 유지되고, 신뢰 정보가 없으면 “검증되지 않음”으로 구분해 소비자가 판단합니다.

이 변화는 중요한 현실을 반영합니다. 에이전트가 밤새 수천 개의 문서를 만들 수 있게 되면 “파일이 존재한다”는 사실은 신뢰의 근거가 되지 못합니다. 무엇에서 왔고, 누가 확인했고, 언제 다시 확인해야 하는지가 파일 자체에서 보여야 합니다.

OKF는 RAG를 대체하지 않는다

OKF와 RAG를 같은 제품군으로 보면 혼란이 생깁니다. 둘은 서로 다른 질문에 답합니다.

항목	답하는 질문	대표 산출물
OKF	지식을 어떤 모양으로 저장하고 교환할까?	Markdown + YAML 파일 묶음
검색 인덱스	질문과 관련된 파일·구간을 어떻게 빨리 찾을까?	FTS·벡터·그래프 인덱스
RAG	찾은 근거를 모델 답변에 어떻게 넣을까?	근거 묶음과 출처가 붙은 답변
Wiki UI	사람이 어떻게 둘러보고 편집할까?	트리·검색·그래프·편집 화면

실제 흐름은 다음처럼 이어질 수 있습니다.

OKF bundle
    ↓ parse / index
검색기(FTS, embedding, graph)
    ↓ relevant concepts
RAG 또는 AI agent
    ↓
근거가 연결된 답변·작업

OKF는 검색기의 입력을 표준화할 수 있지만 어떤 임베딩 모델을 쓸지, top-k를 몇 개로 할지, 답변을 어떻게 검증할지는 정하지 않습니다. 반대로 RAG가 훌륭해도 원천 지식의 경로, 버전, 상태가 제각각이면 인덱스를 다시 만드는 비용이 큽니다. 두 층은 경쟁 관계가 아니라 보완 관계입니다. 더 넓은 경계는 LLM Wiki와 RAG의 차이에서 이어서 볼 수 있습니다.

직접 LLM Wiki를 운영하며 확인한 것: 형식은 시작일 뿐이다

제가 여러 프로젝트의 문서를 LLM Wiki로 바꾸는 하네스를 만들 때 가장 먼저 정한 원칙은 작업 에이전트가 정본 문서를 바로 덮어쓰지 못하게 하는 것이었습니다. 에이전트는 원천 경로가 붙은 제안만 만들고, 검토와 승인을 거친 결과만 정본으로 승격하게 했습니다.

그다음에는 “결과가 그럴듯한가”만 보지 않고, 읽은 원천 중 어느 문서가 지식 노드의 근거로 연결됐고 무엇이 빠졌는지 보여 주는 커버리지 리포트를 추가했습니다. 이 구현 경험은 검증·승인·증분 갱신으로 LLM Wiki를 운영하는 방법에 자세히 정리했습니다.

이 하네스가 OKF 호환 구현인 것은 아닙니다. 다만 직접 부딪혀 보니 OKF v0.2가 sources, verified, status, stale_after를 추가한 이유는 분명했습니다. Markdown으로 저장했다는 사실만으로는 출처 누락, 오래된 지식, 자동 생성 오류를 막을 수 없습니다. 이식 가능한 형식과 신뢰 가능한 승격 절차가 함께 있어야 합니다.

도입 전에 알아야 할 한계 네 가지

1. 형식이 사실을 보증하지 않는다

틀린 내용을 완벽한 YAML로 감싸도 틀린 지식입니다. verified 필드는 검증 사실을 기록할 뿐 실제 검증을 대신하지 않습니다. 누가 무엇과 대조했는지에 대한 조직의 규칙이 필요합니다.

2. 검색과 실행 환경은 별도다

OKF에는 벡터 데이터베이스, 검색 API, 에이전트 런타임이 포함되지 않습니다. 작은 묶음은 rg 같은 텍스트 검색으로도 충분하지만, 규모가 커지면 별도의 인덱싱과 평가가 필요합니다.

3. 신뢰 단계는 접근 권한이 아니다

공식 명세의 신뢰 단계는 소비자가 참고하는 신호이지 ACL이 아닙니다. 개인정보, 비밀키, 고객 데이터가 든 문서를 Git에 넣어도 된다는 뜻이 아닙니다. 저장소 권한, 암호화, 비밀정보 검사와 원천 시스템의 접근정책은 별도로 설계해야 합니다.

4. 최소 규격이므로 팀 규칙이 여전히 필요하다

type 값은 중앙에서 등록하지 않습니다. 확장에는 유리하지만 같은 조직 안에서도 Metric, Business Metric, KPI가 뒤섞일 수 있습니다. 파일명, 타입 어휘, 검수자, 갱신 주기 같은 로컬 규칙을 작은 계약으로 정해 두는 편이 좋습니다.

30분 안에 작은 OKF 묶음으로 시작하는 법

처음부터 전사 Wiki를 바꾸려 하지 마세요. 질문 하나에 필요한 작은 도메인으로 시험하는 편이 좋습니다.

1. 자주 틀리는 질문 하나를 고른다

예를 들어 “주간 활성 사용자는 어떻게 계산하나?”를 고릅니다. 이 답에 필요한 지표 정의, 테이블, 이벤트 계약, 장애 대응 문서만 범위에 넣습니다.

2. 개념별 파일을 만든다

product-analytics/
├── index.md
├── metrics/weekly-active-users.md
├── tables/events.md
├── references/event-contract.md
└── playbooks/freshness-alert.md

3. 최소 메타데이터부터 쓴다

처음에는 type, title, description, tags면 충분합니다. 자동 생성이 들어가면 sources, generated, verified, status, stale_after를 추가합니다. 실제 자산이 따로 있으면 resource로 연결합니다.

4. Git과 검증 게이트를 붙인다

다음 항목은 LLM이 아니라 결정적 스크립트로 검사할 수 있습니다.

모든 개념에 type이 있는가?
내부 링크의 대상 파일이 존재하는가?
sources[].id와 본문 각주가 맞는가?
stale_after가 지난 문서가 있는가?
secret 패턴이나 공개하면 안 되는 경로가 포함됐는가?

5. 소비자 하나만 연결한다

처음부터 전용 플랫폼을 만들 필요는 없습니다. GitHub에서 읽거나, 정적 HTML 뷰어를 만들거나, 검색 인덱서가 이 폴더를 읽게 하면 됩니다. 공식 저장소에는 BigQuery용 생성 에이전트, 샘플 묶음, 자체 포함형 HTML 시각화가 참고 구현으로 들어 있습니다.

일주일 정도 써 본 뒤 “다른 도구로 옮기기 쉬웠는가”, “오래된 문서를 구분할 수 있었는가”, “질문에 필요한 근거가 빠지지 않았는가”를 평가하세요. 파일 개수보다 이 세 질문이 성공 여부를 더 잘 보여 줍니다.

자주 묻는 질문

Q1. OKF는 Google Cloud에서만 쓸 수 있나요?

아닙니다. 저장소는 GoogleCloudPlatform 조직에 있지만 형식 자체는 특정 클라우드, 모델, 에이전트 프레임워크나 계정을 요구하지 않습니다. 평범한 파일을 읽고 쓸 수 있으면 생산자와 소비자를 만들 수 있습니다.

Q2. Markdown 폴더라면 모두 OKF인가요?

아닙니다. 개념 문서는 YAML frontmatter를 가져야 하고 최소한 type 필드가 있어야 합니다. index.md, log.md, 링크와 경로에도 명세가 정한 의미가 있습니다. 다만 진입 장벽은 매우 낮습니다.

Q3. 기존 Obsidian이나 Notion 문서를 그대로 쓸 수 있나요?

Markdown과 YAML frontmatter를 이미 쓰는 Obsidian vault는 변환하기 비교적 쉽습니다. Notion처럼 자체 데이터 모델을 쓰는 서비스는 export 결과를 OKF 경로와 frontmatter 규칙에 맞추는 생산자가 필요합니다. “읽을 수 있다”와 “명세에 맞는다”는 구분해야 합니다.

Q4. 새 프로젝트는 v0.1과 v0.2 중 무엇으로 시작해야 하나요?

작성 시점의 최신 명세인 v0.2를 기준으로 시작하는 편이 자연스럽습니다. 다만 v0.2의 새 신뢰 필드는 선택 사항이고 type만 필수라는 최소 원칙은 유지됩니다. 작은 묶음으로 시작한 뒤 자동화가 늘어날 때 신뢰 필드를 보강하면 됩니다.

마무리

OKF의 핵심은 놀랄 만큼 소박합니다.

지식은 Markdown에 쓴다.
검색과 판단에 필요한 정보는 YAML frontmatter에 둔다.
폴더와 링크로 구조를 만들고 파일째 옮긴다.

바로 그 단순함이 장점입니다. 사람용 문서와 에이전트용 데이터 사이에 새 전용 플랫폼을 하나 더 세우지 않아도 됩니다. 동시에 단순함을 과신해서도 안 됩니다. 출처, 검증, 최신성, 접근 권한과 검색 품질은 형식 바깥의 운영 문제로 남습니다.

따라서 가장 현실적인 시작은 “우리 조직의 모든 지식을 OKF로 바꾸자”가 아닙니다. 한 질문에 필요한 다섯 파일을 만들고, 다른 사람과 다른 에이전트가 변환 없이 읽을 수 있는지 확인하는 것입니다. 그 작은 교환이 잘 된다면 OKF가 해결하려는 문제를 이미 절반은 이해한 셈입니다.