====== 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: 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 Soubor s konceptem má YAML frontmatter a Markdown tělo: --- 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). 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“. --- 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. ===== 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ů: 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 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]]