Was ist Googles neues Open-Knowledge-Format?

Veröffentlicht

12. August 2026

Autor

Faizan Nadeem

Die Grundlagen

Was OKF tatsächlich abdeckt

Das Open Knowledge Format ist eine Spezifikation zur Darstellung kuratierten Wissens als Verzeichnis aus einfachen Markdown-Dateien mit YAML-Frontmatter, veröffentlicht vom Datenteam von Google Cloud im Juni 2026. Es formalisiert ein Muster, das sich im Ökosystem bereits organisch herausgebildet hatte – Andrej Karpathys viel geteilte „LLM wiki“-Idee, die AGENTS.md-Konvention, die inzwischen in Zehntausenden Open-Source-Projekten verwendet wird, und Entwickler, die Obsidian-artige Vaults direkt an Coding-Agents anbinden. OKF erfindet kein neues Substrat; es standardisiert dasjenige, das sich bereits durchgesetzt hat: Markdown, Frontmatter und Git.

Ein „Concept“ ist die atomare Einheit – eine Datei, ein Wissensbaustein –, und der Pfad der Datei ist ihre Identität, ohne ein separates ID-System, das synchron gehalten werden müsste. Von den wenigen empfohlenen Frontmatter-Feldern ist genau eines verpflichtend: type. Alles andere – Titel, Beschreibung, ein Ressourcen-Link, Tags, ein Zeitstempel – ist optional. Dieser Minimalismus ist kein Versehen; er ist die gesamte Designphilosophie. Das ist ein Wire-Format, keine Plattform, und die Spezifikation ist bewusst tolerant gegenüber dem, was sie akzeptiert: unbekannte Typen, fehlende optionale Felder, sogar kaputte Links sind alles Dinge, die ein konformer Consumer akzeptieren muss, statt sie zurückzuweisen.

Warum dies ein Problem mit hohem Nutzen ist

Token-Kosten summieren sich mit jedem Agenten, jeder Aufgabe und jedem Teammitglied, das einen ausführt. Dieselben strukturellen Fakten über eine Codebasis neu herzuleiten, ist keine einmalige Kostenposition – es ist eine wiederkehrende Steuer auf jede einzelne Interaktion.
Die Alternativen sind beide für genau diese Art von Wissen fehlerhaft. Ein naiver Dump des gesamten Repositories skaliert nicht über eine kleine Codebasis hinaus, und RAG leitet Beziehungen aus Rohdokumenten zur Anfragezeit immer wieder neu her – für Wissen, das sich in Wahrheit gar nicht so oft ändert.
Veralteter Kontext ist nicht nur langsam – er ist aktiv falsch. Ein Agent, der auf einem überholten mentalen Modell der Abhängigkeiten eines Services arbeitet, verschwendet nicht nur Tokens; er kann Änderungen vornehmen, die etwas kaputt machen, von dessen Verbindung er nichts wusste.

Die vollständige Architektur

Commit Pushed
      │
      ▼
Diff-Scoped Scan  (which services/modules actually changed?)
      │
      ▼
Draft / Update Concept Docs  (two-pass enrichment agent)
      │
      ▼
Re-link Cross-References  (update dependency/responsibility links)
      │
      ▼
Lint  (spec-compliance rules)
      │
      ▼
Publish  (commit the bundle, push to CI, or register to a catalog)

Das Leitprinzip lautet: das stabile Wissen einmal kompilieren, damit Agents es nicht bei jeder Aufgabe erneut herleiten müssen. OKF selbst hat keine Meinung dazu, wie diese Kompilierung erfolgt oder aktuell bleibt – dieser Teil liegt vollständig bei denjenigen, die es einführen, und ist die eigentliche Engineering-Arbeit, auf die sich dieser Beitrag konzentriert.

Die Kernschichten erklärt

1. Die Concept-Datei

Was sie ist: Eine einzelne Markdown-Datei, die eine Wissenseinheit repräsentiert – einen Service, eine API, eine Tabelle, ein Runbook – mit einem kleinen YAML-Frontmatter-Block oben und einem frei formbaren Markdown-Body darunter.

Warum sie wichtig ist: Weil der Dateipfad die Identität ist, gibt es nichts zwischen einem separaten ID-System und dem tatsächlichen Ort des Wissens abzugleichen – das Dateisystem selbst ist der Index.

---
type: Service
title: billing-service
description: Handles subscription billing, invoicing, and payment webhooks.
resource: https://github.com/yourorg/monorepo/tree/main/services/billing
tags: [billing, payments, python]
timestamp: 2026-08-01T10:00:00Z
---
# Responsibilities
Owns the Invoice and PaymentEvent domain models.

# Dependencies
- Calls customer-service to resolve account state.
- Publishes events consumed by notifications-service.

Produktionstipp: Spiegele die Struktur des ursprünglichen Anwendungsfalls bewusst – ersetze eine BigQuery-Konsole-URL im Feld resource durch einen Repository-Pfad und einen Daten-Abschnitt # Schema durch eine codeorientierte Struktur aus # Responsibilities / # Dependencies. Konsistenz in der Body-Struktur über Concept-Dateien hinweg ist für den Agenten-Konsum wichtiger als jedes einzelne Feld.

2. `index.md` und progressive disclosure

Was es ist: Ein reservierter Dateiname, der auf jeder Ebene des Bundles als Verzeichnisübersicht dient – der Einstiegspunkt, den ein Agent liest, bevor er irgendetwas anderes anfasst.

Warum es wichtig ist: Das ist eine echte Kontrolle des Token-Budgets, keine Komfortdatei. Ein orchestrierender Agent liest index.md, entscheidet, welche Concept-Dateien eine bestimmte Teilaufgabe tatsächlich benötigt, und lädt nur diese – niemand zieht für eine Änderung, die einen einzigen Service betrifft, das gesamte Bundle in den Kontext.

Produktionstipp: Halte Index-Einträge bei einem Titel und einer einzeiligen Beschreibung, direkt aus dem Frontmatter jedes Concepts übernommen. Ein mit Details aufgeblähter Index verfehlt den Zweck, überhaupt einen zu haben.

3. `log.md` und Änderungsverlauf

Was es ist: Ein weiterer reservierter Dateiname – eine chronologische, nach Datum gruppierte Aufzeichnung dessen, was sich an dem geändert hat, was das Bundle weiß, getrennt von git log, das nur festhält, was sich im Code geändert hat.

Warum es wichtig ist: „Was hat sich in dieser Datei geändert?“ und „Was hat sich in unserem Verständnis dieses Systems geändert?“ sind unterschiedliche Fragen. Der Code eines Services kann sich ändern, ohne dass sich seine dokumentierten Verantwortlichkeiten ändern, und umgekehrt – ein log.md lässt einen Agenten (oder eine Person) die zweite Frage direkt beantworten, statt sie aus der Commit-Historie ableiten zu müssen.

4. Cross-Links als Abhängigkeitsgraph

Was es ist: Gewöhnliche relative Markdown-Links zwischen Concept-Dateien, wobei die Bedeutung der Beziehung durch den umgebenden Text und nicht durch ein formales Schema transportiert wird.

Warum es wichtig ist: Diese Links machen aus einem flachen Verzeichnis etwas, das eher einem Abhängigkeitsgraphen als einer simplen Ordnerhierarchie ähnelt – billing-service kann auf alles verweisen, was es aufruft, und auf alles, wohin es veröffentlicht, unabhängig davon, wo diese Services tatsächlich im Repository-Baum liegen.

Produktionstipp: Weil Links nur Markdown sind und die Spezifikation verlangt, dass Consumer auch kaputte Links tolerieren, solltest du das nicht als Ersatz für echte statische Analyse deines Call-Graphs behandeln. Es ist eine kuratierte, für Menschen und Agents lesbare Zusammenfassung des Abhängigkeitsgraphen, kein formal verifizierter Graph.

5. Die Enrichment-Agent-Pipeline

Was sie ist: Der Teil, den OKF bewusst nicht spezifiziert – der Prozess, der Concept-Dateien tatsächlich entwirft und pflegt, während sich der Code verändert. Das Referenzmuster besteht aus zwei Durchläufen: einem, der geänderte Services durchläuft und aus ihren Schnittstellen und ihrer Struktur eine Concept-Datei entwirft oder aktualisiert, und einem zweiten, der Verweise zurück auf vorhandene Dokumentation, Runbooks und PRs ergänzt.

Warum sie wichtig ist: Das ist die eigentliche Engineering-Arbeit hinter der Einführung von OKF. Das Format selbst ist fast kostenlos zu prototypisieren – ein Pflichtfeld, kein SDK. Ein Bundle aus tausend Dateien korrekt zu halten, während ein Team Dutzende Commits pro Tag ausliefert, ist das eigentliche Systemproblem, und genau das müsst ihr lösen, nicht die Spezifikation.

Produktionstipp: Begrenze jeden Enrichment-Durchlauf auf den Git-Diff, nicht auf das gesamte Repository. Ein kompletter Re-Scan des gesamten Repositories bei jedem Commit macht das teuer; ein diff-begrenzter Scan nur der geänderten Services macht es billig genug, um bei jedem Push zu laufen.

6. Tooling: Init, Hooks, Search und Lint

Was es ist: Eine Open-Source-CLI (unabhängig von Google, in Go geschrieben), die ein Bundle aufsetzt, einen Git-Hook installiert, damit es sich automatisch aktualisiert, Keyword-Suche über Concepts unterstützt und einen Satz eingebauter Regeln zur Spezifikationskonformität durchsetzt.

Warum es wichtig ist: Du musst die Automatisierungsschicht nicht bei null bauen – die Form von „beim Commit scannen, Geändertes aktualisieren, vor dem Vertrauen linten“ ist bereits durch vorhandenes Tooling erprobt, selbst so früh im Ökosystem.

Produktionstipp: Lasse Lint als harte Schranke laufen, bevor deine CI einem Bundle genug vertraut, um Agents darauf handeln zu lassen. Angesichts der Toleranz der Spezifikation gegenüber fehlenden Feldern und kaputten Links ist Lint das Einzige, was zwischen „technisch konform“ und „tatsächlich nützlich“ steht.

End-to-End-Durchlauf

Verfolge einen Commit durch die vollständige Pipeline:

Ein Entwickler pusht eine Änderung an billing-service und fügt eine neue Abhängigkeit zu einem Fraud-Check-Service hinzu.
Der Git-Hook wird ausgelöst und startet einen diff-begrenzten Scan – nur billing-service und alles, was direkt vom Diff betroffen ist, wird erneut untersucht, nicht das gesamte Repository.
Durchlauf eins des Enrichment-Agenten entwirft das Update, liest die neue Schnittstelle und die neuen Call-Sites des Services und schreibt den Abschnitt # Dependencies von billing-service.md um, sodass der Fraud-Check-Service aufgenommen wird.
Durchlauf zwei ergänzt Quellenverweise, gleicht die Änderung mit vorhandenen Runbooks oder PR-Beschreibungen ab, die erklären, warum die Abhängigkeit hinzugefügt wurde, und verlinkt diese.
Cross-References werden auf beiden Seiten aktualisiert – billing-service.md verlinkt nun auf die Concept-Datei des Fraud-Check-Services, und falls in dieser Datei ein Abschnitt # Dependents existiert, wird er so aktualisiert, dass er zurückverweist.
Lint läuft gegen das aktualisierte Bundle, prüft die Gültigkeit des Frontmatters und fängt alles ab, was der Enrichment-Durchlauf strukturell falsch erzeugt hat.
Das Bundle wird veröffentlicht – zusammen mit der Codeänderung committet oder über die CI an einen ausgelieferten Ort gepusht.
Am nächsten Tag greift ein Orchestrator-Agent eine nicht verwandte Aufgabe auf, die den Fraud-Check-Service betrifft. Er liest index.md, sieht die Concept-Datei, lädt nur diese eine Datei – einschließlich ihres nun aktuellen Rückverweises auf billing-service – und muss nie wieder eine der beiden Codebasen von Grund auf neu scannen, um die Beziehung zu verstehen.

Sonderfälle

Wo OKF endet und RAG beginnt. OKF ist für den stabilen, kuratierten Teil des Wissens einer Codebasis gedacht – Services, Ownership-Grenzen, Abhängigkeitsgraphen, die Runbooks, die sich tatsächlich jemand die Mühe gemacht hat zu schreiben. RAG bleibt weiterhin das richtige Werkzeug für den Long Tail: einmalige Design-Dokumente, Slack-Threads, alte Tickets – alles, was zu unstrukturiert oder zu selten referenziert wird, um eine Kuratierung in eine Concept-Datei zu rechtfertigen. OKF als RAG-Ersatz zu behandeln, ist die falsche Perspektive; es als kompilierten Cache zu behandeln, der RAG das erneute Herleiten stabiler Fakten erspart, ist die richtige.

Monorepos mit mehreren Teams und Typdrift. Weil type producer-definiert ist und es kein externes Register gibt, werden verschiedene Teams, die zum selben Bundle beitragen, ganz natürlich auseinanderdriften – der „API Endpoint“ des einen Teams ist die „Route“ des anderen. Nichts in der Spezifikation verhindert das; nur eure eigenen Lint-Regeln und Konventionen können die Linie halten.

Governed Metrics und zertifizierte Berechnungen. Die Spezifikation enthält einen Concept-Typ für das, was sie eine „attested computation“ nennt – eine sanktionierte, überprüfbare Art, einen Wert zu berechnen, unterschieden von einer bloßen Dokumentation dessen, was der Wert bedeutet. Für Teams mit Metriken, die eine Single Source of Truth dafür brauchen, wie sie berechnet werden, nicht nur wofür sie stehen, ist das eine eigene Concept-Datei wert, statt die Berechnungslogik in eine allgemeine Beschreibung zu falten.

Skalierungs- und Produktionsherausforderungen

Re-Scans des gesamten Repositories skalieren nicht, diff-begrenzte schon. Das gesamte Kostenmodell dieser Pipeline hängt davon ab, Enrichment-Durchläufe auf das zu begrenzen, was sich tatsächlich geändert hat. Ein Team, das bei jedem Commit alles neu scannt, wird die Pipeline als zu teuer empfinden, lange bevor sein Repository groß genug wird, um sie wirklich zu brauchen.

Progressive disclosure muss bewusst in eure Orchestrierungsschicht eingebaut werden, nicht einfach vorausgesetzt. Der Vorteil für das Token-Budget durch index.md materialisiert sich nur, wenn euer orchestrierender Agent tatsächlich so gebaut ist, dass er zuerst den Index liest und Concept-Dateien selektiv lädt – OKF an einen Agenten anzuschrauben, der weiterhin ganze Verzeichnisse in den Kontext kippt, bringt euch die Wartungskosten ohne die Einsparungen.

Drift und Governance werden im großen Maßstab schwieriger, nicht leichter. Ohne Typregister und ohne erzwungene Link-Semantik bleibt ein Bundle, das von einer Handvoll Leuten gepflegt wird, allein durch Konvention kohärent; ein Bundle, das von Dutzenden Beiträgern angefasst wird, braucht bewusste Lint-Regeln und Disziplin im Review, um nicht zu einem inkonsistenten Durcheinander zu verkommen, das technisch spezifikationskonform und praktisch unzuverlässig ist.

Das ist ein sehr frühes Ökosystem. Die Spezifikation wurde im Juni 2026 veröffentlicht, das Tooling außerhalb von Googles eigener Referenzimplementierung ist fragmentiert, und es gibt noch keine langlaufenden Produktions-Fallstudien für große, aktiv veränderte Codebasen. Plane ein, dass sich nicht nur euer Bundle, sondern auch die Spezifikation selbst weiterentwickeln wird.

Codebeispiele

Ein Bundle aufsetzen und den Hook für automatische Aktualisierungen anschließen:

okf init
okf hook install
okf search -q "billing"
okf lint

Ein minimaler Python-Wrapper, um die CLI aus der eigenen CI-Pipeline aufzurufen:

import subprocess

def okf_lint(bundle_path: str = ".okf/knowledge") -> bool:
    result = subprocess.run(
        ["okf", "lint", bundle_path],
        capture_output=True, text=True,
    )
    if result.returncode != 0:
        print(result.stdout)
    return result.returncode == 0

Die Load-and-Search-Primitiven, die euer Orchestrator vor dem Dispatch eines Sub-Agenten aufruft, sowie die Lint-Prüfung, die eure CI aufruft, bevor sie einem Bundle vertraut:

bundle, err := okf.LoadBundle(".okf/knowledge", nil)
results := bundle.Search("billing")
report := lint.LintBundle(concepts, lint.DefaultConfig())

Häufige Fallstricke

Fehler: OKF als RAG-Ersatz behandeln. Zu versuchen, unstrukturiertes, selten referenziertes Wissen in kuratierte Concept-Dateien zu pressen, untergräbt die gesamte Prämisse des Formats. Lösung: Nutze OKF für stabiles, kuratiertes Wissen und lasse RAG für den Long Tail bestehen.

Fehler: Bei jedem Commit das gesamte Repository neu scannen. Das ist der schnellste Weg, die Pipeline zu teuer zu machen, um sie weiter laufen zu lassen. Lösung: Begrenze jeden Enrichment-Durchlauf auf den Git-Diff, nicht auf die gesamte Codebasis.

Fehler: Lint überspringen, weil die Spezifikation absichtlich tolerant ist. Spezifikationskonform ist nicht dasselbe wie vertrauenswürdig – ein Bundle voller kaputter Links und driftender Typen kann technisch immer noch bestehen. Lösung: Lass Lint als harte CI-Schranke laufen, bevor Agents auf das Bundle losgelassen werden.

Fehler: OKF einführen, bevor ihr überhaupt Agents habt, die es konsumieren. Das gesamte Nutzenversprechen hängt davon ab, dass etwas das Bundle auch liest. Lösung: Wenn in eurem Workflow bislang nichts strukturierten Kontext konsumiert, pflegt ihr ein Wiki, das niemand liest – wartet, bis ihr agentische Workflows habt, die es tatsächlich verwenden würden.

Fehler: Den Zitations-Durchlauf überspringen. Ein Enrichment-Agent mit nur einem Durchlauf, der lediglich entwirft, aber vorhandene Dokumentation nicht querverweist, produziert oft plausibel klingende, aber nicht verifizierte Beschreibungen. Lösung: Behalte die Zwei-Durchlauf-Struktur bei – erst entwerfen, dann belegen –, statt dem ersten Durchlauf als final zu vertrauen.

Best Practices für die Produktion

Begrenze Enrichment immer auf den Diff. Das ist der Unterschied zwischen einer Pipeline, die bei jedem Commit läuft, und einer, die nach der ersten teuren Woche abgeschaltet wird.
Entwirf deinen Orchestrator von Anfang an rund um progressive disclosure. Die Token-Einsparungen sind real, aber nur, wenn tatsächlich etwas index.md liest, bevor Concept-Dateien geladen werden.
Linten, bevor du vertraust. Die Toleranz der Spezifikation gegenüber fehlenden Feldern und kaputten Links bedeutet, dass Governance vollständig in deiner Verantwortung liegt, nicht in der des Formats.
Behandle OKF und RAG als komplementäre Werkzeuge, nicht als Konkurrenten. Leite stabiles, kuratiertes Wissen durch OKF und alles andere durch RAG.
Beginne mit eurem am häufigsten geänderten Service, nicht mit dem gesamten Repository. Eine minimale Pipeline – okf init, ein Git-Hook, ein Enrichment-Durchlauf über den Service mit der höchsten Änderungsrate – reicht aus, um echte Token-Einsparungen zu messen, bevor ihr euch auf einen vollständigen Rollout festlegt.

Zum Abschluss

Die Spezifikation selbst ist tatsächlich fast nichts – ein Pflichtfeld, simples Markdown, kein SDK zur Installation. Genau deshalb ist sie gut einführbar, und genau deshalb ist sie nicht der interessante Teil. Das eigentliche System, das es sich zu bauen lohnt, ist die Enrichment-Pipeline, die einen Wissensgraphen ehrlich hält, während sich eure Codebasis unter ihm weiter verändert, und das ist ein Engineering-Problem, das euch keine Spezifikation fertig gelöst überreichen kann. Wenn ihr bereits mehrere Agents gegen euer eigenes Repository laufen lasst, lohnt sich dafür diese Woche ein Prototyp – richtet einen Git-Hook auf euren aktivsten Service und messt die Token-Differenz bei eurer nächsten Multi-Agent-Aufgabe, bevor ihr entscheidet, ob die Wartungskosten es wert sind.

Wenn du das in deiner eigenen Codebasis ausprobieren würdest: Worauf würdest du den ersten Enrichment-Durchlauf begrenzen – auf euren am häufigsten geänderten Service oder auf den mit den am stärksten verflochtenen Abhängigkeiten?