Praktische Hinweise: OKF ist mehr als Markdown – Wie ich über eine portable Formatierung denke
Schritt-für-Schritt-Anleitung zu den Praktischen Hinweisen: OKF ist mehr als Markdown – Wie ich an ein Portabel denke: Verträge, Überprüfungen sowie Code-Blöcke für Teams, die dieses Muster einsetzen.
Dieser Leitfaden zeigt den Weg von Rohstoffen bis zu einem funktionsfähigen System für das Projekt „OKF Is More Than Markdown: How I Think About a Portable Knowledge Layer for AI Agents“. Der Schwerpunkt liegt auf ausführbaren Schritten, expliziten Überprüfungen sowie Code, den man ohne Rückschluss auf die Absicht direkt in ein Repository einfügen kann. In der Übersichtsphase sollten Eingaben, Verantwortliche für die einzelnen Schritte sowie Abbruchkriterien definiert werden, bevor Code geändert wird. Die Betreiber sollten in der Lage sein, den Schritt von einem bekannten Checkpoint aus erneut auszuführen, ohne auf versteckte Zustände schließen zu müssen. Dokumentieren Sie sowohl den erfolgreichen Ablauf als auch den Notfallweg gemeinsam. Wiederholungsversuche, menschliche Überprüfungen sowie die Handhabung fehlerhafter Nachrichten gehören zum Produkt selbst und nicht zu späteren Optimierungen.
knowledge/
├── index.md
├── orders/
│ ├── index.md
│ └── order-lifecycle.md
├── payments/
│ ├── index.md
│ └── payment-failures.md
└── policies/
└── refund-eligibility.md
---
type: Business Rule
title: Refund Eligibility
description: Rules for determining whether an order is eligible for a refund.
tags: [orders, refunds]
---
# Refund Eligibility
An order is eligible for a refund when...
See also [Order Lifecycle](../orders/order-lifecycle.md).
Agenten sind mächtig, wissen aber immer noch nicht, wie Ihr Produkt funktioniert
Wenn Sie mit Agenten arbeiten – die zwar mächtig sind, aber in bestimmten Phasen eingesetzt werden – sollten Sie zunächst den Vertrag aufschreiben: erforderliche Eingaben, Erfolgsindikatoren sowie das Vorgehen bei teilweisen Fehlern. Diese Checkliste sorgt dafür, dass spätere Codeänderungen transparent bleiben. Ziehen Sie kleine, testbare Einheiten vor großen Skripten. Wenn ein Schritt fehlschlägt, sollte der Fehler auf eine einzige Verantwortung verweisen und nicht auf ein verworrenes Ablaufschema. Legen Sie nach teuren Schritten Checkpoints an. Das Resume sollte bei einem Neversuch eines Operators für einen späteren Knoten nicht denselben LLM-Aufruf erneut berechnen.
Wiki
PDF
Product docs
Shared Drive
API documentation
Source code
JIRA Tickets
Slack threads
Google Drive
People's heads
Der wichtige Teil von OKF ist nicht Markdown
Beim Arbeiten an der wichtigen Phase sollten Sie zunächst den Vertrag aufschreiben: erforderliche Eingaben, Erfolgsindikatoren sowie das Vorgehen bei teilweisen Fehlern. Diese Checkliste sorgt dafür, dass spätere Codeänderungen transparent bleiben. Betrachten Sie diese Phase als Vertrag zwischen Eingaben und validierten Ausgaben. Benennen Sie die Ergebnisdokumente, definieren Sie Erfolgskontrollen und lehnen Sie stille, teilweise abgeschlossene Abläufe ab. Erstellen Sie Kontrollpunkte nach aufwändigen Schritten. Das Resume sollte keine doppelten Gebühren für denselben LLM-Aufruf erheben, wenn ein Operator einen späteren Knoten erneut ausführt.
Bundles, Konzepte und der Teil, der Ihnen am interessantesten erscheint: index.md
Beim Arbeiten mit den Bundles-Konzepten und den jeweiligen Phasen sollte man zunächst den Vertrag aufschreiben: erforderliche Eingaben, Erfolgssignal sowie das Vorgehen bei teilweisen Fehlern. Diese Checkliste sorgt dafür, dass spätere Codeänderungen transparent bleiben. Notieren Sie außerdem die Laufzeiten sowie die Kosten für Tokens oder Abfragen neben den funktionalen Ergebnissen. Eine frühzeitige Sichtbarkeit der Kosten verhindert überraschende Rechnungen, wenn der Prozess von einer Demo-Umgebung in gemeinsam genutzte Umgebungen übergeht. Legen Sie nach aufwändigen Schritten einen Kontrollpunkt an. Das Wiederaufnehmen des Prozesses sollte keine erneuten Gebühren für denselben LLM-Aufruf verursachen, wenn ein Operator einen späteren Knoten erneut ausführt. Beim Arbeiten mit den Bundles-Konzepten und den jeweiligen Phasen sollte man zunächst den Vertrag aufschreiben: erforderliche Eingaben, Erfolgssignal sowie das Vorgehen bei teilweisen Fehlern. Diese Checkliste sorgt dafür, dass spätere Codeänderungen transparent bleiben. Dokumentieren Sie sowohl den erfolgreichen Ablauf als auch den Notfallweg gemeinsam. Wiederholte Versuche, menschliche Überprüfungen sowie die Handhabung von Fehlern gehören zum Produkt selbst und nicht zu späteren Optimierungen.
store-knowledge/
├── index.md
├── orders/
│ ├── index.md
│ ├── order-lifecycle.md
│ └── cancellation.md
├── payments/
│ ├── index.md
│ └── payment-status.md
└── policies/
├── index.md
└── refund-eligibility.md
Thousands of documents
↓
Load everything into context
index.md
Orders
Payments
Promotions
Refund Policies
Customer Support
policies/index.md
Refund Eligibility
Partial Refunds
Manual Review
policies/refund-eligibility.md
[Order Lifecycle](../orders/order-lifecycle.md)
Bundle
↓
index.md
↓
policies/
↓
index.md
↓
refund-eligibility.md
↓
order-lifecycle.md
Ist das nicht einfach RAG?
Der Ansatz „Ist das nicht einfach“ funktioniert am besten, wenn er als messbare Ebene betrachtet wird. Erfassen Sie ein Beispiel für einen erfolgreichen Ablauf, einen Fehlerfall sowie eine Notiz zur Rücksetzung, bevor Sie den Umfang erweitern. Ziehen Sie kleine, testbare Einheiten vor großen, komplexen Skripten. Wenn ein Schritt fehlschlägt, sollte der Fehler auf eine einzige Verantwortung verweisen und nicht auf einen verworrenen Ablauf. Trennen Sie die Strategie zur Aufteilung in Blöcke von der Strategie zur Informationsabrufung. Ein Änderungsbedarf bei einer dieser Strategien sollte nicht dazu führen, dass die andere neu geschrieben werden muss, wenn sich die Qualitätsmetriken ändern.
Question
↓
Retrieve relevant knowledge
↓
Put knowledge into context
↓
Generate an answer
User Question
↓
Vector / Hybrid Search
↓
Find an OKF concept
↓
Read the concept
↓
Follow indexes or links if needed
↓
Build the final context
{
"title": "...",
"source": "...",
"type": "...",
"updated_at": "...",
"owner": "..."
}
Was ist mit Agent-Fähigkeiten?
Die Phase „Was ist mit Agentenfähigkeiten?“ funktioniert am besten, wenn sie als messbarer Rahmen betrachtet wird. Erfassen Sie einen erfolgreichen Fallbeispiel, einen Fehlerfall sowie die Notizen zur Rücksetzung, bevor Sie den Umfang erweitern. Betrachten Sie diese Phase als Vertrag zwischen Eingaben und validierten Ausgaben. Benennen Sie die Ergebnisdokumente, definieren Sie Erfolgskontrollen und lehnen Sie stille, unvollständige Abschlüsse ab. Halten Sie den Zustand der Graphen einfach und typisiert. Verschachtelte Datenblöcke verbergen, welcher Knoten welches Feld geschrieben hat, und führen zu Unterbrechungen beim Fortsetzen der Verarbeitung.
1. Identify the customer issue
2. Inspect the order status
3. Check the applicable refund policy
4. Determine whether escalation is required
5. Draft a response
customer-support-skill/
├── SKILL.md
└── references/
└── commerce-knowledge/
├── index.md
├── orders/
├── payments/
└── policies/
Der OKF-Anwendungsfall, der Ihnen am interessantesten erscheint, ist eigentlich lokal.
Die OKF-Anwendungsfallphase funktioniert am besten, wenn sie als messbarer Bereich betrachtet wird. Erfassen Sie vor der Erweiterung des Umfangs ein „goldenes“ Transkript, einen Fehlerfall sowie eine Notiz zur Rücksetzung. Erfassen Sie außerdem die Laufzeiten sowie die Kosten für Tokens oder Abfragen neben den funktionalen Ergebnissen. Eine frühzeitige Sichtbarkeit der Kosten verhindert überraschende Rechnungen, wenn der Prozess von einer Demo in gemeinsame Umgebungen übergeht. Halten Sie den Zustand der Grafik einfach und typisiert – verschachtelte Datenblöcke verbergen, welcher Knoten welches Feld geschrieben hat, und führen zu Unterbrechungen beim Fortsetzen des Ablaufs. Die OKF-Anwendungsfallphase funktioniert am besten, wenn sie als messbarer Bereich betrachtet wird. Erfassen Sie vor der Erweiterung des Umfangs ein „goldenes“ Transkript, einen Fehlerfall sowie eine Notiz zur Rücksetzung. Dokumentieren Sie den erfolgreichen Ablauf sowie den Wiederherstellungsprozess gemeinsam. Wiederholversuche, menschliche Kontrollen sowie die Handhabung von Fehlern gehören zum Produkt selbst und nicht zu späteren Optimierungen.
storefront/
├── src/
├── tests/
├── AGENTS.md
└── knowledge/
├── index.md
├── checkout/
├── orders/
├── payments/
├── refunds/
└── promotions/
read code
→ understand code
→ modify code
Coding Task
↓
Read code
+
Read refund policy
+
Read payment constraints
+
Read order lifecycle
↓
Understand actual product behavior
↓
Modify code
Modify code
↓
Product behavior changed
↓
Update knowledge
Lokalwissen und zentrales Wissen müssen nicht miteinander konkurrieren
Zur Phase des lokalen und zentralen Wissens sollten Eingaben, der Verantwortliche für den Schritt sowie die Abbruchkriterien vor dem Codeändern definiert werden. Die Operator sollten in der Lage sein, den Schritt von einem bekannten Checkpoint aus erneut auszuführen, ohne auf versteckte Zustände schließen zu müssen. Bevorzugen Sie kleine, testbare Einheiten vor umfangreichen Skripten. Wenn ein Schritt fehlschlägt, sollte der Fehler auf eine einzige Verantwortung verweisen und nicht auf ein verworrenes Ablaufschema. Setzen Sie menschliche Freigabe bei Vorgängen ein, die Geld ausgeben oder Produktionsdaten ändern. Kompilierzeitbezogene Verbindungen bedeuten noch nicht vollständige Geschäftsabläufe.
Company terminology
Shared authentication rules
Common API contracts
Billing definitions
Customer policies
Security guidelines
Agent
/ \
/ \
↓ ↓
Local OKF Central OKF
project shared
knowledge knowledge
OKF
= Knowledge Artifact
MCP
= Serving / Tool ProtocolSearch Index
= Retrieval Implementation
v0.2 war der Punkt, an dem OKF viel vollständiger wirkte
In der Version v0.2 wird in dieser Phase zunächst festgelegt, welche Eingaben verwendet werden, wer für den jeweiligen Schritt verantwortlich ist und welche Abbruchkriterien gelten, bevor der Code geändert wird. Die Operator sollten in der Lage sein, den Schritt von einem bekannten Checkpoint aus erneut auszuführen, ohne auf versteckten Zuständen schließen zu müssen. Betrachten Sie diese Phase als Vertrag zwischen den Eingaben und den validierten Ausgaben. Benennen Sie die Artefakte, definieren Sie Erfolgskontrollen und lehnen Sie stille, unvollständige Abschlüsse ab. Setzen Sie menschliche Freigabe für Schritte ein, bei denen Geld ausgegeben wird oder Produktionsdaten verändert werden. Eine Kompilierzeit-Verkabelung bedeutet nicht automatisch vollständige Geschäftsabwicklung.
sources:
...
generated:
by: ...
at: ...verified:
...status: stablestale_after: 2026-12-31
Where did this come from?
Who generated it?Has anyone verified it?Is it still current?Is this a draft or a stable concept?
Geprüfte Berechnungen sind eine andere Art von Wissen.
Da die Attested Computation eine Phase darstellt, sollten vor dem Ändern des Codes die Eingaben, der Verantwortliche für den Schritt sowie die Abbruchkriterien definiert werden. Die Operator sollten in der Lage sein, den Schritt von einem bekannten Checkpoint aus erneut auszuführen, ohne auf versteckte Zustände schließen zu müssen. Erhalten Sie Zeiten sowie Kosten für Token oder Abfragen zusammen mit den funktionalen Ergebnissen fest. Eine frühzeitige Sichtbarkeit der Kosten verhindert überraschende Rechnungen, wenn sich der Ablauf von einer Demo-Umgebung in eine gemeinsam genutzte Umgebung verschiebt. Setzen Sie menschliche Freigabe für Schritte ein, die Geld kosten oder Produktionsdaten ändern. Eine Verkabelung zur Kompilierzeit bedeutet noch nicht vollständige Geschäftsabdeckung. Da die Attested Computation eine Phase darstellt, sollten vor dem Ändern des Codes die Eingaben, der Verantwortliche für den Schritt sowie die Abbruchkriterien definiert werden. Die Operator sollten in der Lage sein, den Schritt von einem bekannten Checkpoint aus erneut auszuführen, ohne auf versteckte Zustände schließen zu müssen. Dokumentieren Sie sowohl den erfolgreichen Ablauf als auch den Wiederherstellungsprozess gemeinsam. Wiederholversuche, menschliche Kontrollen sowie die Handhabung von Fehlern gehören zum Produkt und nicht zu späteren Optimierungen.
>Here is something we know.
Here is the approved way
to establish that something is true.
Welches Problem löst OKF eigentlich?
Während der Phase „Welches Problem?“ sollten Sie zunächst den Vertrag aufschreiben: erforderliche Eingaben, Erfolgsignal sowie das Vorgehen bei teilweisen Fehlern. Diese Checkliste sorgt dafür, dass spätere Codeänderungen transparent bleiben. Ziehen Sie kleine, testbare Einheiten vor großen Skripten vor. Wenn ein Schritt fehlschlägt, sollte der Fehler auf eine einzige Verantwortung verweisen und nicht auf ein verworrenes Ablaufverfahren. Führen Sie nach teuren Schritten Kontrollpunkte durch. Das Wiederaufnehmen des Vorgangs sollte keine erneute Abrechnung für denselben LLM-Aufruf verursachen, wenn ein Operator einen späteren Knoten erneut ausführt.
Operative Checkliste
Die Phase der operativen Checkliste funktioniert am besten, wenn sie als messbarer Referenzpunkt betrachtet wird. Erfassen Sie vor der Erweiterung des Umfangs ein „goldenes“ Transkript, einen Fehlfall sowie eine Notiz zur Rücksetzung.
Halten Sie die Konfiguration außerhalb des Anwendungscode. Umgebungsdateien, Geheimdatenspeicher und Feature-Flags sollten an einem Ort gespeichert werden, den Betreiber überprüfen können, ohne den gesamten Graphen durchlesen zu müssen.
Halten Sie den Zustand des Graphen flach und typisiert. Verschachtelte Blob-Strukturen verbergen, welcher Knoten welches Feld geschrieben hat, und führen dazu, dass die Fortsetzung nach Unterbrechungen nicht möglich ist.
Fügen Sie immer dann, wenn das Budget es zulässt, einen Smoke-Test hinzu, der den kritischen Pfad in CI mit Fixtures und nicht mit live genutzten, bezahlten APIs testet.
Dokumentieren Sie sowohl den erfolgreichen Ablauf als auch den Wiederherstellungsprozess gemeinsam. Wiederholversuche, menschliche Überprüfungen sowie die Handhabung von Fehlnachrichten gehören zum Produkt selbst und nicht zu späteren Optimierungen.
Halten Sie den Zustand des Graphen flach und typisiert. Verschachtelte Blob-Strukturen verbergen, welcher Knoten welches Feld geschrieben hat, und führen dazu, dass die Fortsetzung nach Unterbrechungen nicht möglich ist.
Vor der Einführung des Stacks sollten Versionen eingefroren werden, ein „goldener“ Transkript für den kritischen Pfad erstellt und die Rollback-Schritte bestätigt werden. Gemeinsam genutzte Umgebungen erfordern Rate Limits, Überprüfungen der Nutzerzuordnung sowie einen klaren Verantwortlichen für die Rotation von Geheimnissen. Man sollte langweilige Zuverlässigkeit vor cleveren, einmaligen Demonstrationen bevorzugen.
Batch-Hinweis für 758c51495df5: Halten Sie die Provider-Schlüssel außerhalb des Repositories, legen Sie eine Obergrenze für Tokens pro Sitzung fest und speichern Sie die Transkripte neben den Evaluierungs-Dateien, damit spätere Modellwechsel vergleichbar bleiben.
Die Härtegrad-Hinweis-Stufe 0 funktioniert am besten, wenn sie als messbarer Referenzpunkt betrachtet wird. Erstellen Sie vor der Erweiterung des Umfangs ein „goldenes“ Transkript, einen Fehlerfall sowie den Rollback-Hinweis. Erfassen Sie außerdem Zeiten sowie Kosten für Tokens oder Abfragen neben den funktionalen Ergebnissen. Eine frühzeitige Sichtbarkeit der Kosten verhindert überraschende Rechnungen, wenn der Einsatzbereich von Demonstrationen zu gemeinsam genutzten Umgebungen wechselt.
Verstärkungsmaßnahme Detail 0/782: Messen Sie die Ausführungsdauer, die Fehlerklasse sowie den Tokenverbrauch für diese Notiz und entscheiden Sie anschließend auf der Grundlage eines festgelegten Fragebogens statt aufgrund von Einzelfällen, ob die Änderung beibehalten werden soll.
Für die erste Stufe der Verstärkungsmaßnahme definieren Sie vor dem Codeändern die Eingabedaten, den Verantwortlichen für den Schritt sowie die Abschlusskriterien. Die Operator sollten in der Lage sein, den Schritt von einem bekannten Checkpoint aus erneut auszuführen, ohne auf versteckte Zustände schließen zu müssen. Dokumentieren Sie sowohl den erfolgreichen Ablauf als auch den Notfallweg gemeinsam. Wiederholungsversuche, menschliche Überprüfungen sowie die Handhabung von Fehlern gehören zum Produkt selbst und nicht zu späteren Optimierungen.
Verstärkungsmaßnahme Detail 1/782: Messen Sie die Ausführungsdauer, die Fehlerklasse sowie den Tokenverbrauch für diese Notiz und entscheiden Sie anschließend auf der Grundlage eines festgelegten Fragebogens statt aufgrund von Einzelfällen, ob die Änderung beibehalten werden soll.
Beim Bearbeiten der zweiten Stufe der Verstärkungsmaßnahmen sollten Sie zunächst einen Vertrag aufschreiben: erforderliche Eingaben, Erfolgsindikatoren sowie das Vorgehen bei teilweisen Fehlern. Diese Checkliste sorgt dafür, dass spätere Codeänderungen transparent bleiben. Betrachten Sie diese Stufe als Vertrag zwischen Eingaben und validierten Ausgaben. Benennen Sie die relevanten Artefakte, definieren Sie Erfolgsprüfungen und lehnen Sie stille, teilweise abgeschlossene Abläufe ab.
Detail 2/782 zur Verstärkung: Messen Sie die Ausführungszeit, die Fehlerklasse sowie den Tokenverbrauch für diese Maßnahme und entscheiden Sie anschließend auf der Grundlage eines festgelegten Fragekatalogs – und nicht nur aufgrund von Einzelfällen –, ob die Änderung beibehalten werden soll.
Die dritte Stufe der Verstärkungsmaßnahmen funktioniert am besten, wenn sie als messbarer Bereich betrachtet wird. Erfassen Sie vor der Erweiterung des Umfangs ein „goldenes Transkript“, einen Fehlerfall sowie eine Notiz zur Rücksetzung. Bewahren Sie Konfigurationen außerhalb des Anwendungscode auf. Umgebungsdateien, Geheimdatenspeicher sowie Feature-Flags sollten an einem Ort gesammelt sein, den Betreiber ohne das Durchlesen des gesamten Systems prüfen können.
Verstärkungsmaßnahme Detail 3/782: Messen Sie die Ausführungsdauer, die Fehlerklasse sowie den Tokenverbrauch für diese Notiz und entscheiden Sie anschließend auf der Grundlage eines festgelegten Fragebogens statt aufgrund von Einzelfällen, ob die Änderung beibehalten werden soll.
Zur vierten Stufe der Verstärkungsmaßnahme sollten die Eingabedaten, der Verantwortliche für den Schritt sowie die Abschlusskriterien vor der Codeänderung definiert werden. Die Operator sollten in der Lage sein, den Schritt von einem bekannten Checkpoint aus erneut auszuführen, ohne auf versteckte Zustände schließen zu müssen. Bevorzugen Sie kleine, testbare Einheiten vor umfangreichen Skripten. Wenn ein Schritt fehlschlägt, sollte der Fehler auf eine einzelne Verantwortung verweisen und nicht auf ein verworrenes Ablaufverfahren.
Verstärkungsmaßnahme Detail 4/782: Messen Sie die Ausführungsdauer, die Fehlerklasse sowie den Tokenverbrauch für diese Notiz und entscheiden Sie anschließend auf der Grundlage eines festgelegten Fragebogens statt aufgrund von Einzelfällen, ob die Änderung beibehalten werden soll.