Open Knowledge Format OKF [Wiki]

Tato stránka je pouze pro čtení. Můžete si pouze prohlédnout zdrojový kód, ale ne ho měnit. Zeptejte se správce, pokud si myslíte, že něco není v pořádku.
====== Open Knowledge Format OKF ======

//Vytvořeno: **1.7.2026** | Aktualizováno: **~~LASTMOD~~**//

[[https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf|Open Knowledge Format (OKF)]] je návrh otevřeného formátu pro ukládání znalostí jako Markdown souborů s YAML metadaty. Hodí se jako přenosná znalostní báze pro lidi i AI agenty, protože obsah je čitelný bez speciálního SDK, dá se verzovat v Gitu a lze ho načítat jako kontext pro LLM.

===== Co OKF řeší =====

V softwarovém projektu bývají důležité znalosti rozptýlené mezi README, wiki, issues, komentáře v kódu, databázové migrace, OpenAPI specifikace a historii chatů. Člověk si kontext často dohledá, ale AI agent potřebuje kratší, strukturované a dobře odkazované dokumenty.

OKF se na to dívá jako na balíček znalostí. Každý dokument popisuje jeden koncept: doménovou entitu, API endpoint, databázovou tabulku, architektonické rozhodnutí, runbook, metriku nebo externí referenci.

Důležité vlastnosti:

  * znalosti jsou obyčejné soubory v adresáři,
  * každý koncept je Markdown dokument,
  * metadata jsou v YAML frontmatteru,
  * odkazy mezi dokumenty tvoří graf vztahů,
  * bundle lze verzovat v Gitu,
  * konzumentem může být člověk, statický web, vyhledávací index, RAG pipeline nebo AI agent.

===== BigQuery není podstata =====

Repozitář obsahuje referenčního agenta, který umí generovat OKF bundle z BigQuery datasetu a doplňovat ho z webové dokumentace. To je ale jen ukázkový producer. Podstatou projektu je samotný formát popsaný ve [[https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md|specifikaci OKF]].

Pro běžný vývoj aplikace lze OKF použít ručně nebo vlastním skriptem bez BigQuery a bez Google Cloudu. BigQuery příklady ukazují hlavně to, že jeden koncept může být technické aktivum se schématem, popisem, příklady a odkazy na související koncepty.

===== Základní struktura =====

OKF bundle je adresářová struktura s Markdown soubory:

<code>
okf/
├── index.md
├── architecture/
│   ├── index.md
│   ├── overview.md
│   └── auth.md
├── domain/
│   ├── index.md
│   ├── user.md
│   └── order.md
├── api/
│   ├── index.md
│   └── create-order.md
├── database/
│   └── orders-table.md
├── decisions/
│   └── why-use-postgresql.md
└── runbooks/
    └── local-development.md
</code>

Soubor s konceptem má YAML frontmatter a Markdown tělo:

<code markdown>
---
type: Domain Entity
title: Order
description: Objednávka zákazníka v e-shopu.
tags: [domain, ecommerce, payments]
---

# Význam

Order reprezentuje nákupní proces od vytvoření košíku po zaplacení.

# Stavy

- `draft` — objednávka ještě není potvrzená
- `pending_payment` — čeká se na platbu
- `paid` — platba přijata
- `cancelled` — objednávka zrušena

# Vazby

- Uživatel je popsán v [User](/domain/user.md).
- Data jsou uložena v [orders table](/database/orders-table.md).
- Vytváření objednávky řeší [Create Order API](/api/create-order.md).
</code>

Podle specifikace je povinné hlavně pole ''type''. Ostatní pole jako ''title'', ''description'', ''resource'', ''tags'' a ''timestamp'' jsou doporučená, ale ne povinná.

===== Použití při vývoji aplikace =====

==== Projektová paměť ====

OKF může fungovat jako projektová paměť uložená přímo v repozitáři. Před větší změnou si vývojář nebo AI agent načte související dokumenty a získá kontext, který není zřejmý jen ze zdrojového kódu.

Například při úpravě objednávek se načtou:

  * ''domain/order.md'' — význam doménového objektu a jeho stavy,
  * ''api/create-order.md'' — jak se objednávka vytváří přes API,
  * ''database/orders-table.md'' — kde jsou data uložená,
  * ''decisions/payment-provider-abstraction.md'' — proč je platební logika navržená konkrétním způsobem,
  * ''runbooks/debug-payment-failure.md'' — jak řešit běžné problémy.

==== Dokumentace domény ====

Doménové pojmy se dají dokumentovat jako samostatné koncepty. To pomáhá hlavně tam, kde názvy tříd nebo tabulek nestačí k pochopení business významu.

Příklady konceptů:

  * ''domain/customer.md'',
  * ''domain/subscription.md'',
  * ''domain/invoice.md'',
  * ''domain/payment.md''.

Každý koncept může odkazovat na API, databázové tabulky, rozhodnutí a runbooky. Tím vznikne graf vztahů, ne jen strom dokumentace.

==== Architektonická rozhodnutí ====

OKF se hodí i pro záznam rozhodnutí. AI agent pak při refaktoringu ví, proč daný návrh existuje, a nebude ho omylem rušit jako „zbytečnou složitost“.

<code markdown>
---
type: Architecture Decision
title: Ukládání provider payloadů do JSONB
description: Důvod, proč ukládáme původní odpovědi platebních bran.
tags: [database, payments, architecture]
---

# Rozhodnutí

Payloady z platebních bran ukládáme do JSONB sloupce.

# Důvod

Každý provider vrací jinou strukturu a potřebujeme zachovat původní odpověď pro debugging.

# Důsledky

- Stabilní pole mají normální databázové sloupce.
- Provider-specific data zůstávají v JSONB.
- Business logika nemá záviset na náhodných vnořených JSON polích.
</code>

===== Použití jako znalostní báze pro AI agenty =====

OKF je pro AI agenty zajímavé hlavně tím, že kombinuje volný text, metadata a odkazy.

Možné použití:

  * agent si před prací načte ''index.md'' a podle něj vybere relevantní koncepty,
  * RAG pipeline indexuje jednotlivé Markdown dokumenty jako samostatné jednotky,
  * metadata ''type'' a ''tags'' slouží k filtrování výsledků,
  * odkazy mezi dokumenty pomáhají dohledat související kontext,
  * dokumenty lze udržovat v Gitu společně s aplikací.

Praktický postup pro coding agenta může být jednoduchý:

  - Najdi v OKF bundle dokumenty související se změnou.
  - Načti doménové koncepty, API, databázové poznámky a rozhodnutí.
  - Teprve potom upravuj kód.
  - Pokud změna mění doménu nebo architekturu, aktualizuj odpovídající OKF dokument.

Tím se z OKF stává kontrolovaná paměť projektu, ne jen dokumentace „někde bokem“.

===== Minimální experiment =====

Pro první ověření není potřeba psát žádný generátor. Stačí vytvořit malý adresář ''okf/'' v repozitáři a ručně přidat několik dokumentů:

<code>
okf/
├── index.md
├── product/what-this-app-does.md
├── architecture/overview.md
├── domain/user.md
├── domain/order.md
├── api/main-api.md
├── database/schema-overview.md
├── decisions/authentication.md
└── runbooks/local-development.md
</code>

Pak lze vyzkoušet jednoduché pravidlo pro práci s AI agentem:

> Před větší změnou v kódu nejdřív načti relevantní dokumenty z ''okf/'' a při změně domény nebo architektury je aktualizuj.

Pokud se tento postup osvědčí, další krok může být automatické generování části dokumentů z OpenAPI, databázového schématu, testů nebo existující wiki.

===== Kdy OKF dává smysl =====

OKF dává smysl hlavně když:

  * projekt má víc doménového nebo architektonického kontextu, než je vidět přímo z kódu,
  * na projektu pracují AI coding agenti,
  * je potřeba verzovat znalosti spolu s kódem,
  * chceš mít znalostní bázi použitelnou pro RAG,
  * dokumentace má být přenositelná a nezávislá na konkrétním nástroji.

Naopak pro malý projekt s jednoduchým README může být OKF zbytečná vrstva navíc.

===== Vztah k DokuWiki =====

OKF nemusí nahrazovat DokuWiki. Spíš může plnit jinou roli:

  * DokuWiki je dobrá pro čitelné články, návody a veřejnější poznámky.
  * OKF je dobré pro strojově čitelnou projektovou znalostní bázi v Gitu.

Praktický model může být kombinace obojího: OKF jako pracovní znalostní vrstva pro agenty a DokuWiki jako redakčně upravená dokumentace nebo osobní znalostní archiv.

===== Shrnutí =====

OKF je jednoduchý formát pro reprezentaci znalostí jako Markdown dokumentů s YAML metadaty. Pro vývoj softwaru je zajímavý hlavně jako strukturovaná projektová paměť pro lidi a AI agenty. Největší hodnota není v BigQuery integraci, ale v tom, že znalosti o doméně, API, databázi, rozhodnutích a runboocích lze mít v malých propojených dokumentech verzovaných v Gitu.

===== Zdroje =====

  * [[https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf|GoogleCloudPlatform/knowledge-catalog – OKF]]
  * [[https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md|Open Knowledge Format – specifikace]]