
Google OKF, 에이전트가 읽는 조직 지식의 교환 포맷
Google OKF: 에이전트가 '믿고 읽을 수 있는' 조직 지식의 조건
요약 2026년 6월 Google Cloud는 Open Knowledge Format(OKF) 을 공개했습니다. Markdown 본문과 YAML frontmatter로 조직 지식을 표준화하는 벤더 중립 오픈 포맷입니다. 7월에 나온 v0.2에는 "에이전트가 쓴 지식을 믿어도 되는가"에 답하기 위한 신뢰 신호가 추가됐습니다. 저희는 사내 레거시 문서인 HawkEye ADR 132건을 OKF v0.2로 변환하고, 세 개의 모델로 전후를 비교했습니다. 토큰은 최대 70% 줄었고, 같은 질문에 대한 답의 흔들림도 줄었습니다. 이 글이 전하려는 핵심은 하나입니다. 에이전트 품질의 병목은 모델보다 컨텍스트이고, 컨텍스트 품질은 '읽기 전에 판단할 수 있는 구조'에서 나옵니다.
Key Insights
OKF는 서비스가 아니라 포맷입니다. SDK도, 계정도, 런타임도 필요 없습니다.
cat으로 읽을 수 있으면 OKF를 읽을 수 있습니다.frontmatter는 '설명'에서 '판단'으로 진화했습니다. v0.1이 "이것은 무엇인가"를 적는 곳이었다면, v0.2는 "이것을 지금 읽어도 되는가"를 결정하는 곳입니다.
신뢰는 점수가 아니라 신호로 기록됩니다. 스펙은 신뢰 점수를 저장하지 않고, 원천 신호만 남긴 뒤 판단을 소비자에게 맡깁니다.
실측에서 가장 큰 효과는 '재현성'이었습니다. 토큰 절감보다 더 중요한 변화는 "같은 질문에 같은 답"에 가까워졌다는 점입니다. 다만 그 정도는 모델마다 달랐습니다.
사람의 서명 0건은 실패가 아니라 출발점입니다. 신뢰 등급 분포는 자동화가 어디까지 왔고, 사람이 어디서부터 개입해야 하는지를 보여주는 지도입니다.
1. 왜 지금, 조직 지식의 '포맷'인가
모델은 충분히 똑똑해졌다. 부족한 것은 맥락이다
파운데이션 모델은 코드를 쓰고 문서를 요약하고 데이터를 분석합니다. 그런데 에이전트가 실제 업무에서 틀리는 이유를 추적해 보면, 대부분은 추론 능력이 아니라 맥락 부족으로 귀결됩니다. Google이 OKF 발표에서 짚은 문제의식도 같습니다. 모델 성능이 좋아질수록 오히려 관련 맥락의 부재가 에이전트 시스템의 한계를 결정한다는 것입니다.
그리고 그 맥락은 대부분 내부 지식입니다. 테이블 스키마, 우리 회사에서 특정 지표가 뜻하는 바, 장애 런북, 시스템 간 조인 경로, 오래된 API의 폐기 공지 같은 것들입니다. 이런 지식은 보통 다음과 같은 곳에 흩어져 있습니다.
자체 API를 가진 메타데이터 카탈로그
위키 / Confluence / 공유 드라이브
코드 주석, docstring, 노트북 셀
몇몇 시니어 엔지니어의 머릿속
그 결과는 익숙합니다. 에이전트를 만드는 모든 팀이 같은 맥락 조립 문제를 처음부터 다시 풀고, 카탈로그 벤더들은 같은 데이터 모델을 반복해서 재발명하며, 지식은 그것을 만든 도구 안에 갇힙니다.
이미 모두가 쓰고 있던 패턴: LLM Wiki
흥미로운 점은 OKF가 새로운 발명이 아니라는 것입니다. Google은 OKF를 Andrej Karpathy가 정리한 'LLM-wiki' 패턴을 이식 가능하고 상호운용되는 형태로 공식화한 스펙이라고 소개했습니다. 사람이 개인 위키를 포기하는 이유는 교차 참조 갱신 같은 잡무인데, 바로 그 잡무가 LLM이 잘하는 일이라는 관찰이 이 패턴의 출발점입니다.
같은 패턴은 이미 여러 이름으로 쓰이고 있었습니다. 코딩 에이전트와 연결된 Obsidian vault, AGENTS.md / CLAUDE.md 계열의 규약 파일, 에이전트가 작업 전에 먼저 읽는 index.md·log.md, 데이터팀의 'metadata as code' 저장소 등입니다. 문제는 이들이 겉모습은 비슷해도 서로 협력하도록 설계되지 않았다는 점입니다. 어떤 필드를 넣어야 하는지, 어떤 파일명이 무엇을 뜻하는지에 대한 합의가 없었습니다.
OKF의 답: 서비스가 아니라 포맷
OKF가 내린 결론은 명확합니다. 또 하나의 지식 서비스가 아니라 포맷이 필요하다는 것입니다. Google이 제시한 포맷의 요건은 다섯 가지입니다. SDK 없이 누구나 만들 수 있고, 별도 연동 없이 누구나 소비할 수 있으며, 시스템과 조직을 옮겨도 살아남고, 코드와 함께 버전 관리되며, 같은 파일을 사람과 에이전트가 번역 없이 읽을 수 있어야 합니다.
한 번 작성하면 모든 AI 도구가 읽는 표준 포맷 하나. N개의 bespoke 통합을 OKF 1개로 줄인다.
2. 에이전트 생태계 안에서 OKF의 위치: 4-Protocol Map
OKF는 MCP의 대체재가 아닙니다. 역할이 서로 다른 4개의 프로토콜이 에이전트 생태계를 함께 구성합니다.
프로토콜 | 주체 | 역할 | 비유 | 다루는 것 |
|---|---|---|---|---|
MCP | Anthropic | 에이전트 ↔ 도구 실시간 연결 | USB 포트 | 행동(Action) |
OKF | 조직 지식 패키징 · 교환 | 도서관 카탈로그 | 지식(Knowledge) | |
AGENTS.md / CLAUDE.md | Community | 에이전트 행동 지침 | 직원 매뉴얼 | 규범(Norm) |
A2A | 에이전트 간 협업 · 발견 | 내선 전화 | 협업(Coordination) |
하네스 설계 관점에서 보면 이 네 가지는 서로 다른 층위를 담당합니다. MCP가 "무엇을 할 수 있는가", AGENTS.md가 "어떻게 행동해야 하는가"를 정한다면, OKF는 "무엇을 알고 있어야 하며, 그 앎을 얼마나 믿어도 되는가" 를 정합니다.
RAG와는 무엇이 다른가
OKF를 처음 접하면 "결국 RAG용 문서 정리 아닌가"라는 질문이 나옵니다. 둘은 접근 방식이 다릅니다. GitBook은 OKF가 탐색 가능한 지식 그래프라면, RAG는 유사도 검색이고, 메타데이터 카탈로그는 데이터 인벤토리라고 구분합니다. MarkTechPost도 RAG와 달리 OKF는 에이전트가 직접 읽고 갱신하는, 큐레이션되고 버전 관리되는 개념을 저장한다고 정리했습니다.
관점 | RAG | OKF |
|---|---|---|
검색 단위 | 청크(문서 조각) | 개념(Concept) 파일 하나 |
관계 | 임베딩 공간의 유사도 | 명시적 링크 · 타입 있는 관계 |
현행성 판단 | 불가 — 폐기된 문서도 유사하면 검색됨 |
|
신뢰 판단 | 불가 |
|
갱신 주체 | 파이프라인 재색인 | 에이전트·사람이 파일을 직접 수정 |
인사이트: 뒤에 나올 함정 질문 실험에서 "폐기된 ADR-109를 현행으로 인용"하는 오답이 나옵니다. 이것은 검색 품질의 문제가 아닙니다. 폐기된 문서는 현행 문서와 내용이 비슷할수록 더 잘 검색됩니다. 이 문제는 유사도가 아니라 수명주기(lifecycle) 메타데이터로만 풀 수 있습니다. 둘은 경쟁 관계가 아니라, RAG로 후보를 찾고 OKF 신호로 거르는 식으로 조합할 수 있습니다.
3. OKF의 설계 철학 세 가지
Google은 OKF의 설계 원칙을 세 가지로 정리했습니다.
① 최소한의 의견(Minimally opinionated) — 모든 개념에 요구되는 것은 type 필드 하나뿐이며, 어떤 타입이 있는지, 다른 필드와 본문 구성은 작성자에게 맡깁니다. 스펙은 콘텐츠 모델이 아니라 상호운용 표면만 정의합니다.
② 생산자/소비자 독립 — 사람이 쓴 번들을 에이전트가 읽고, 파이프라인이 생성한 번들을 시각화 도구로 탐색하고, 한 LLM이 만든 번들을 다른 LLM이 조회할 수 있습니다. 포맷이 계약이고, 양쪽 도구는 독립적으로 교체할 수 있습니다.
③ 플랫폼이 아니라 포맷 — 특정 클라우드, 데이터베이스, 모델 제공사, 에이전트 프레임워크에 묶이지 않으며, 읽고 쓰는 데 독점 계정이나 SDK를 요구하지 않을 것이라고 명시했습니다.
인사이트: 세 번째 원칙이 가장 중요합니다. Google이 만든 포맷이지만 Google 제품이 없어도 완전히 동작합니다. 실제로 저희 실험도 Google 도구를 하나도 쓰지 않았고, Claude와 GPT 계열 모델만으로 진행했습니다. 포맷의 가치는 소유자가 아니라 그 포맷을 말하는 참여자의 수에서 나온다는 것이 OKF의 기본 전제입니다.
4. OKF 구조: Knowledge Bundle → Concept → Graph
Knowledge Bundle = 디렉토리
okf-bundle/
├── index.md # 번들 소개 (점진적 탐색의 진입점)
├── log.md # 변경 이력
├── tables/
│ ├── alarms.md # 경보 테이블
│ └── incidents.md
├── detection-rules/ # 룰 5개
│ └── brute-force-login.md
├── metrics/
│ └── false-positive-rate.md
└── runbooks/
└── ransomware-response.md파일 경로가 곧 개념의 식별자이며, index.md는 에이전트가 계층을 탐색할 때 점진적으로 정보를 펼치는 용도로, log.md는 변경의 시간순 이력을 남기는 용도로 선택적으로 둘 수 있습니다.
Concept = 하나의 .md 파일
---
type: Detection Rule
title: Brute Force Login 탐지
description: 10분 내 5회 실패 시 탐지
tags: [auth, brute-force, critical]
generated: { by: agent/v2, at: 2026-08-01T09:00:00Z }
status: stable
stale_after: 2027-01-01
---
# Brute Force Login
threshold 기반 탐지...
관련: [알람 테이블](../tables/alarms.md)개념끼리는 일반 마크다운 링크로 연결되고, 이 링크들이 디렉토리를 파일 시스템의 부모/자식 관계보다 풍부한 관계 그래프로 바꿉니다.
YAML Frontmatter 필드
필드 | 계열 | 역할 | 예시 |
|---|---|---|---|
| 핵심 | 지식 유형 (유일한 필수) |
|
| 핵심 | 사람이 읽는 제목 |
|
| 핵심 | 한 줄 요약 |
|
| 핵심 | 실제 리소스 URI | DB URI, API endpoint, 대시보드 URL |
| 핵심 | 필터·검색용 |
|
| 출처 (v0.2) | 근거 자료와 신뢰성 신호 |
|
| 신뢰 (v0.2) | 생성 주체 + 시각 |
|
| 신뢰 (v0.2) | 검증 이벤트 목록 |
|
| 수명주기 (v0.2) |
|
|
| 수명주기 (v0.2) | 유효 기한 (절대 날짜) |
|
토큰 절약의 원리: 에이전트는 frontmatter만 읽고 관련성을 판단한 뒤, 선택한 경우에만 본문을 읽습니다. Google도 대부분의 상호작용은 본문까지 가지 않으며, frontmatter는 관련성과 신뢰성 판단에 필요한 신호만 끌어올려 산문에 토큰을 쓰지 않고도 싸고 자주 판단할 수 있게 하는 역할이라고 설명합니다.
5. v0.2: "에이전트가 쓴 지식을 믿어도 되는가"
문제의 전환: 사람이 쓴 위키에서 에이전트가 쓴 번들로
v0.2의 문제의식은 짧게 요약됩니다. 가장 가치 있는 번들은 사람이 한 번 쓰고 끝나는 문서가 아닙니다. 에이전트가 계속 쓰고, 다른 에이전트가 소비하는 문서입니다. Google은 이렇게 설명합니다. 사람이 쓴 위키 페이지에는 '누군가 썼고, 틀리면 책임을 물을 수 있다'는 암묵적 보증이 있지만, 에이전트가 하룻밤에 개념 1만 개를 생성하면 그 보증은 사라집니다.
그래서 소비자(대개 또 다른 에이전트)는 명시적 신호로 각 개념을 판단해야 하고, 다음 다섯 질문에 답할 수 있어야 합니다.
# | 질문 | 계열 | v0.2 필드 |
|---|---|---|---|
1 | 무엇으로부터 만들어졌나? | Provenance(출처) |
|
2 | 얼마나 믿어도 되나? | Trust(신뢰) |
|
3 | 아직도 사실인가? | Freshness(신선도) |
|
4 | 현행 버전인가? | Lifecycle(수명주기) |
|
5 | 이 숫자는 정해진 방식으로 계산됐나? | Attestation(증명) |
|
중요한 점은 v0.2가 규칙이 아니라 어휘를 추가했다는 것입니다. 여전히 type만 필수이고, 새 필드는 모두 선택이며, 아무것도 채택하지 않은 번들도 v0.1 때와 똑같이 유효합니다. 다만 이제는 '없다는 것'이 의미를 갖습니다. 검증되지 않은 개념은 거부되지는 않지만 검증된 개념과 구별됩니다.
신뢰 등급은 '저장'하지 않고 '도출'한다
신뢰는 두 필드로 표현합니다. 둘을 분리한 이유는 쓴 사람과 확인한 사람이 같을 필요가 없기 때문입니다. 소비자는 verified에서 신뢰 등급을 도출합니다.
verified키가 없으면 ⇒unverifiednon-human actor만 verify했으면 ⇒
machine-confirmed
human:<id>actor가 verify했으면 ⇒human-reviewed
Google은 이 등급이 접근 제어가 아니라 권고 신호라고 명시하면서도, "임원 대시보드에는 사람이 검토한 지표만 노출" 같은 정책을 frontmatter 필터 하나로 구현할 수 있다고 설명합니다.
출처(sources)도 같은 철학입니다. OKF는 신뢰성 점수가 아니라 신호를 기록합니다. 점수는 주관적이고, 소비자 간에 이식되지 않으며, 쓰는 순간부터 낡기 때문입니다. 대신 작성자, 사용 횟수, 최종 수정일 같은 객관적 신호를 남기고, 판단은 소비자가 합니다. 커뮤니티 해설도 같은 운영 원칙을 강조합니다. 판단 결과를 공유 데이터로 저장하면 환경마다 신뢰 점수가 달라지는 혼란이 생기므로, 원천 신호를 저장하고 소비자별로 도출하라는 것입니다.
stale_after가 상대 TTL이 아니라 절대 날짜인 이유
Google은 의도적으로 상대 TTL 대신 절대 날짜를 택했습니다. 그래야 신선도 판단이 '언제 읽었는가'와 무관한 단순한 날짜 비교가 되고, LLM이 아닌 소비자가 원하는 결정성을 확보할 수 있기 때문입니다.
verified와 stale_after는 서로 독립적입니다. 둘을 혼동하면 검증은 받았지만 이미 만료된 옛 정의가 계속 쓰이는 문제가 생기므로, 근거 확인 여부와 만료 여부는 따로 평가해야 합니다.
⚠️ 구현 시 주의: 스펙은 아직 움직이고 있습니다. 한 오픈소스 구현체는 최신 SPEC 문구에 맞춰
stale_after를 오프셋이 포함된 RFC 3339 시각으로만 인정하고, 날짜만 있는 값은 무시하도록 처리했다고 밝혔습니다. 소비자를 구현할 때는 반드시 최신 SPEC.md를 기준으로 삼으십시오.
Attested Computation: "이 숫자, 정말 정해진 방식으로 계산했나?"
v0.2에서 가장 과감한 추가는 Attested Computation이라는 새 개념 타입입니다. 출처(Provenance)가 "주장이 어디서 왔는가"에 답한다면, 증명(Attestation)은 더 어려운 질문에 답합니다. 에이전트가 금액을 보고하는 순간, 그 숫자가 정해진 방식으로 산출됐는지, 아니면 에이전트가 SQL을 즉흥적으로 작성했는지를 묻는 것입니다.
동작 방식은 이렇습니다.
개념 파일에 승인된 계산식과 파라미터 선언이 들어갑니다. 에이전트는 선언된 파라미터만 채울 수 있고, 계산식을 작성하거나 고칠 수 없습니다.
소비자는
executor로 계산을 실행하고 영수증(receipt) 을 받습니다. 영수증에는 실행 ID, 실제 실행된 쿼리, 결과가 담깁니다.LLM을 쓰지 않는 결정적
attester가 영수증을 검사해, 실행된 쿼리가 승인된 계산식과 일치하는지, 표시된 값이 영수증과 맞는지 판정합니다.판정이 거짓이면 소비자는 그 값을 표시하지 않습니다.
verified는 정의가 여전히 정책과 맞는지를 문서 단위로 느리게 확인해 번들에 저장하고, 증명은 한 번의 실행이 값을 올바르게 만들었는지를 호출마다 런타임에 확인하며 번들에 저장하지 않습니다. 그리고 OKF는 계산식과 검증 방법을 기록할 뿐 스스로 아무것도 실행하지 않습니다.
인사이트 (하네스 엔지니어링 관점): Attested Computation은 "LLM의 판단이 개입하면 안 되는 구간을 포맷 수준에서 선언하는 장치" 입니다. 저희가 하네스를 설계할 때 반복해서 부딪히는 원칙, 즉 "확률적 컴포넌트의 출력은 결정적 컴포넌트가 검증한다"가 지식 포맷 안에 들어온 것입니다. 관제 도메인으로 옮기면 SLA 위반율, 오탐률, 장애 건수처럼 보고서에 들어가는 숫자를 에이전트가 임의 쿼리로 산출하지 못하게 막는 용도로 바로 쓸 수 있습니다.
v0.1 → v0.2 호환성
v0.2는 추가형이고 하위 호환되는 마이너 버전이며, 의도적인 변경은 두 가지입니다. timestamp가 generated.at으로, 본문의 # Citations 목록이 sources로 대체됐고, 두 경우 모두 v0.2 소비자는 v0.1 형식으로 대체 해석할 수 있습니다.
6. 실전 적용: HawkEye ADR 132건을 OKF로
산문 속 관계를 타입 있는 관계로 승격
원본 문서의 산문에는 이런 서술이 섞여 있습니다.
...insertDiscoveredEdges must carry per-rung confidence instead of hard-coded 1.0. +ADR-109 dependency, +OQ5 (agent-side local LLDP as a bonus path)....
사람은 이 문장에서 "ADR-111에 ADR-109 의존이 추가됐다"는 관계를 읽어냅니다. 하지만 기계는 아무 관계도 추출하지 못합니다. OKF 변환은 이런 서술을 타입 있는 관계(relation)로 승격시킵니다.
flowchart LR
ADR111["ADR-111<br/>amendment"] -- references --> ADR109["ADR-109<br/>deprecated"]
ADR113["ADR-113<br/>references"] -- references --> ADR109
ADR058["ADR-058<br/>appendix-a"] -. tracked in .-> RES["RESERVATIONS.md"](노드 4개와 RESERVATIONS.md 레지스트리로 구성된 실제 관계 그래프의 축소판입니다. 노드는 ADR-109(deprecated), ADR-111(amendment), ADR-113(references), ADR-058(appendix-a)입니다.)
참고: 저희 변환본의
relations,lifecycle_state는 OKF 코어 스펙이 아니라 생산자 정의 확장 필드입니다. OKF는 모르는 키를 거부하지 않고 보존하도록 설계되어 있어서 이런 도메인 확장이 가능합니다. 참고로 타입 있는 관계 엣지(typed relationship edges)는 커뮤니티가 제안한 확장 항목 중 하나로, 향후 표준화될 가능성이 있습니다.
파일 하나에 무엇이 붙는가
Before — 원본 (6 lines)
# ADR-109: Observer Policy Unification
## Status
> ⚠ SUPERSEDED for the observer_process
> slice — 2026-07-27 (owner dawon).
── 기계가 아는 것: 파일명, mtime. 끝.After — OKF (+13 lines frontmatter)
---
type: ADR
lifecycle_state: superseded-partial
status: deprecated
relations:
- {predicate: references,
target: /adr/ADR-017....md}
sources:
- {id: origin, resource: ...}
---본문은 한 글자도 바뀌지 않습니다. 산문에 있던 사실이 frontmatter로 올라오고, 파일명과 본문에 흩어진 참조가 타입 있는 관계로 승격될 뿐입니다. 변환 비용이 낮고 원본을 훼손하지 않는다는 점이 레거시 문서에 도입할 때 가장 큰 장점입니다.
신뢰 등급 분포: 132건의 현재 상태
unverified | machine-confirmed | human-reviewed |
|---|---|---|
92 | 40 | 0 |
사람 서명 0건은 부끄러운 숫자가 아닙니다. 지금 이 순간의 정직한 현재 상태입니다. 자동 백필이 어디까지 확인했고, 어디부터 사람의 서명이 필요한지를 이 세 숫자가 그대로 보여줍니다.
인사이트: 이 분포는 곧 리뷰 작업의 우선순위 큐가 됩니다. 사람의 검토 시간은 한정되어 있으므로, machine-confirmed 40건 중 참조가 많이 걸린 노드부터 서명하면 그래프 전체의 신뢰도가 가장 빠르게 올라갑니다. 신뢰 등급은 "믿을 수 있는가"라는 판정인 동시에 "어디부터 사람이 봐야 하는가"라는 작업 지시서입니다.
7. 실측: 함정 질문과 세 모델 비교
함정 질문 설계
OKF 변환 전 원본만으로 에이전트에게 다음 질문을 던지면 아래와 같은 오답 패턴이 나타납니다. 각 질문은 OKF v0.2의 특정 신호가 해결하도록 설계했습니다.
질문 (함정) | 오답이 되는 조건 | 해결하는 OKF 신호 |
|---|---|---|
크리덴셜 저장 방식이 확정됐나? |
| 수명주기 ( |
observer 정책의 최종 위치는? | 폐기된 ADR-109를 현행으로 인용함 | 수명주기 ( |
지금 유효한 결정은 몇 건? | 매번 다른 수를 답함 (재현 불가) | 수명주기 전체의 결정적 집계 |
ADR-113이 참조하는 ADR-112는? | 번호가 두 문서에 중복된 걸 못 알아챔 | 경로 기반 식별자 + 관계 |
접속기록 결정, 의존 문서는? | 미확정 상태를 놓치거나 참조 수가 틀림 | 관계 + 수명주기 |
실험 설계
대상:
hawkeye-renewal/docs/adr132개 ADR조건: Before = 원본 산문 / After = OKF v0.2 변환본
질문 5개(크리덴셜·옵저버정책·유효건수·번호중복·접속감사) × 반복 실행
모델: Claude Sonnet 5 · Claude Opus 5 · GPT-5.6-Sol (OpenAI Codex CLI)
하네스:
poc/experiment/run_exp.py,run_multimodel.py
결과
모델 | 토큰 (전→후) | 비용 (전→후) | 소요시간 (전→후) | 재현성 — "지금 유효한 결정은 몇 건?" |
|---|---|---|---|---|
Claude Sonnet 5 | 916K → 273K (−70%) | $0.730 → $0.232 (−68%) | 100s → 63s (−37%) | 29·38·25 → 40·40·40 (완전 수렴) |
Claude Opus 5 | 437K → 288K (−34%) | $0.815 → $0.634 (−22%) | 131s → 99s (−25%) | 39·40·29 → 38·40·38 (편차 축소, 완전 수렴은 아님) |
GPT-5.6-Sol | 495K → 315K (−36%) | (Codex CLI 미노출) | 147s → 130s (−11%) | 36·36·36·37·37·37 → 30·37·39·40·40·40 (n=6, 대체로 수렴·이상치 1건) |
결과 해석: 숫자 너머에서 읽어야 할 것
① 절감 폭은 '원래 얼마나 헤맸는가'에 비례합니다. Sonnet 5의 Before 토큰(916K)은 Opus 5(437K)의 두 배가 넘습니다. 원본 산문 환경에서 Sonnet 5가 더 많은 파일을 열어 보며 탐색했고, OKF가 그 탐색 비용을 가장 크게 줄였다고 해석할 수 있습니다. After 기준으로는 세 모델이 273K~315K로 비슷한 범위에 모였습니다. 구조화된 지식이 모델 간 격차를 좁히는 평탄화 효과를 보인 셈입니다. 단, 이는 가설이며 표본 규모를 늘려 확인할 필요가 있습니다.
② 가장 중요한 지표는 비용이 아니라 재현성입니다. 운영 환경에서 "유효한 결정은 몇 건인가"에 29, 38, 25로 답하는 에이전트는 쓸 수 없습니다. 비용이 아무리 싸도 그렇습니다. Sonnet 5는 OKF 적용 후 3회 모두 40건으로 수렴했습니다. 반면 Opus 5와 GPT-5.6-Sol은 편차가 줄었을 뿐 완전히 수렴하지는 않았습니다.
③ OKF는 재현성을 '보장'하지 않고, 재현성의 '근거'를 만듭니다.
완전 수렴하지 못한 원인은 두 가지로 볼 수 있습니다. 하나는 모델이 frontmatter 신호를 어떻게 해석하는지(예: superseded-partial을 유효로 셀지)가 여전히 모델 판단에 맡겨져 있다는 점입니다. 다른 하나는 집계를 LLM이 직접 수행했다는 점입니다. 여기서 다음 단계가 분명해집니다. "유효 건수" 같은 집계는 LLM이 세지 말고, frontmatter를 파싱하는 결정적 코드가 계산하게 해야 합니다. Attested Computation이 숫자 보고에 대해 제시하는 바로 그 해법입니다.
8. 하네스 엔지니어에게 주는 시사점
OKF를 "문서 포맷"으로만 보면 절반만 보는 것입니다. 에이전트 실행 환경(하네스)을 설계하는 입장에서 OKF는 다음 세 가지를 가능하게 합니다.
1. 컨텍스트 게이팅을 결정적으로 만든다.
지금까지는 "이 문서를 컨텍스트에 넣을지"를 임베딩 유사도나 LLM의 판단에 맡겨 왔습니다. OKF frontmatter가 있으면 하네스가 LLM을 호출하기 전에 status != deprecated, stale_after > today, trust_tier >= machine-confirmed 같은 필터를 코드로 적용할 수 있습니다. 모델이 잘못된 문서를 읽을 기회 자체를 없애는 것입니다. 실패를 모델이 막게 하지 말고, 환경이 막게 하라는 원칙의 직접적인 구현입니다.
2. 에이전트가 만든 지식에 책임 경로를 붙인다.
멀티 에이전트 오케스트레이션에서 한 에이전트의 산출물은 다음 에이전트의 입력이 됩니다. generated.by와 verified[]가 있으면 파이프라인의 어느 단계가 어떤 지식을 만들었고 누가 확인했는지를 추적할 수 있습니다. 오류가 전파됐을 때 원인 노드를 되짚을 수 있는 최소한의 감사 경로가 생기는 것입니다.
3. 사람의 개입 지점을 설계할 수 있게 한다.
신뢰 등급 분포는 "사람이 어디를 봐야 하는가"를 알려줍니다. 모든 문서를 사람이 검토하는 것도, 아무것도 검토하지 않는 것도 답이 아닙니다. human-reviewed가 필요한 소비 시나리오(임원 보고, 고객 제출 문서)만 정의하고, 그 경로에 필요한 문서만 서명 대상으로 삼으면 됩니다.
9. 도입 체크리스트
레거시 문서에 OKF를 도입하려는 팀을 위한 단계별 제안입니다.
단계 | 할 일 | 산출물 |
|---|---|---|
0. 범위 선정 | 에이전트가 가장 자주 틀리는 문서군 하나 선택 (ADR, 런북, 지표 정의 등) | 대상 디렉토리 1개 |
1. 최소 변환 |
| v0.1 적합 번들 |
2. 수명주기 | 산문 속 "폐기됨", "대체됨", "보류" 표현을 | 현행/폐기 구분 |
3. 신뢰 백필 | 자동 생성분에 | 신뢰 등급 분포표 |
4. 함정 질문 세트 | 우리 도메인의 오답 패턴 5~10개를 질문으로 고정 | 회귀 테스트 세트 |
5. 전후 측정 | 토큰·시간·재현성을 반복 실행으로 비교 | 도입 효과 근거 |
6. 사람 서명 | 핵심 소비 경로의 문서부터 |
|
주의할 점
스펙은 아직 초기 단계입니다. Google 스스로 v0.1을 완성된 표준이 아닌 출발점이라고 불렀습니다. 필드 형식이 바뀔 수 있으니, 검증 로직은 스펙 버전을 명시해 고정하십시오.
선택 필드를 필수로 취급하지 마십시오. 커뮤니티 해설은 v0.2의 선택 필드를 필수로 다루다가 유효한 v0.1 번들을 거부하는 실수를 대표적인 혼동으로 꼽습니다. 엄격함은 소비자 쪽 정책으로 두는 것이 맞습니다.
확장 필드는 문서화하십시오.
relations,lifecycle_state같은 자체 확장은 번들의index.md에 의미를 정의해 두어야 다른 소비자도 해석할 수 있습니다.
10. 생태계 현황
공개 후 3개월 남짓 지났지만, 외부 생태계는 빠르게 형성되고 있습니다.
Google 레퍼런스 구현: BigQuery 데이터셋을 순회하며 개념 문서를 만드는 enrichment agent, 번들을 인터랙티브 그래프로 보여주는 정적 HTML 시각화 도구, 샘플 번들이 함께 공개됐습니다. Google Cloud의 Knowledge Catalog도 OKF를 수집해 에이전트에 제공할 수 있도록 업데이트됐습니다.
커뮤니티 구현체: Rust로 작성된
okf-core는 OKF v0.2의 파서, 모델, 검증기, 출처·신뢰·증명 계열, 링크 그래프 도구를 순수 Rust로 구현했습니다. 에이전트 스킬 형태의okf-skills는 v0.1 번들을 v0.2로 제자리 마이그레이션하는 기능을 제공합니다.커뮤니티 확장 제안: 타입 있는 관계 엣지, 에이전트 라우팅 힌트 필드, 선택적 삭제 적합성 프로파일, .okfignore 규약 등이 제안된 상태입니다.
정리
OKF는 MCP·A2A·AGENTS.md와 경쟁하지 않습니다. 조직 지식 교환에 특화된 포맷이며, 그 가치는 소유자가 아니라 참여자 수에서 나옵니다.
핵심은 Markdown 본문 + YAML frontmatter입니다. 사람은 그대로 읽고, 기계는 frontmatter만으로 관련성을 판단합니다.
v0.2는 frontmatter를 "설명하는 곳"에서 "판단하는 곳"으로 바꿨습니다. 출처·신뢰·신선도·수명주기·증명의 다섯 질문에 읽기 전에 답할 수 있습니다.
실제 ADR 132건에 적용한 결과, 세 모델(Sonnet 5 / Opus 5 / GPT-5.6-Sol) 모두에서 토큰과 시간이 줄고 재현성이 개선되는 경향을 확인했습니다. 다만 그 정도는 모델마다 달랐습니다.
다음 단계는 분명합니다. 판단은 구조가, 집계는 결정적 코드가, 서명은 사람이 맡는 하네스를 설계하는 것입니다.


