Open Knowledge Format OKF

Toto je starší verze dokumentu!

Vytvořeno: 1.7.2026 | Aktualizováno: 01.07.2026 07:59

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.

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 chatu. Č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.

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 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.

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á.

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.

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.

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.

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“.

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.

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.

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.

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.