Uwagi praktyczne: OKF to coś więcej niż Markdown: Jak postrzegam format portabelny
Krok po kroku praktyczne wskazówki: OKF to coś więcej niż Markdown – jak postrzegam format przenośny: umowy, sprawdzanie oraz miejsca na kod do wstawienia dla zespołów wykorzystujących ten wzorzec.
To przewodnik pokazuje, jak przejść od surowców do gotowego systemu w przypadku projektu OKF Is More Than Markdown: How I Think About a Portable Knowledge Layer for AI Agents. Kluczowe są konkretne kroki, jasne sprawdzenia oraz kod, który można bez problemu umieścić w repozytorium, bez konieczności domyślania się intencji. Na etapie przeglądu należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy udokumentować zarówno prawidłowy przebieg procesu, jak i ścieżkę naprawczą. Próby ponownych działań, kontrola przez ludzi oraz obsługa błędów stanowią integralną część produktu, a nie elementy dodawane później.
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).
Agenci są potężni, ale nadal nie wiedzą, jak działa twój produkt
Gdy pracujesz nad fazą, w której agenci są potężni, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co się dzieje w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Wolij małe, testowalne jednostki od rozbudowanych skryptów. Gdy jakiś krok się nie powiedzie, błąd powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Ustaw punkty kontrolne po kosztownych krokach. System powrotu nie powinien ponownie naliczać opłat za tę samą wywołanie LLM, gdy operator próbuje ponownie uruchomić późniejszy węzeł.
Wiki
PDF
Product docs
Shared Drive
API documentation
Source code
JIRA Tickets
Slack threads
Google Drive
People's heads
Ważną częścią OKF nie jest Markdown
Gdy przechodzisz przez etap „Ważna część”, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy poszczególnym elementom, zdefiniuj kryteria sukcesu i odrzuć ciche, częściowe ukończenie zadania. Zrób kontrolę po kosztownych krokach. Narzędzie do kontynuacji nie powinno ponownie naliczać opłat za tę samą wywołanie LLM, gdy operator próbuje ponownie uruchomić późniejszy węzeł.
Pakiety, koncepcje oraz element, który wydaje ci się najciekawszy: index.md
Gdy zajmujesz się koncepcjami Bundles oraz etapem realizacji, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Zapisz czas trwania operacji oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy proces przechodzi z środowiska demonstracyjnego do współdzielonych środowisk. Ustal punkty kontrolne po kosztownych krokach. Narzędzie do kontynuacji pracy nie powinno ponownie naliczać opłat za tę samą wywołanie LLM, gdy operator próbuje ponownie uruchomić późniejszy węzeł. Gdy zajmujesz się koncepcjami Bundles oraz etapem realizacji, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Zdokumentuj zarówno ścieżkę prawidłowego działania, jak i ścieżkę naprawczą. Próby ponownych wywołań, mechanizmy ludzkiej kontroli oraz obsługa wiadomości błędowych stanowią część produktu, a nie elementy dodawane później.
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
Czy to nie jest po prostu RAG?
Faza „Czy to nie jest…” działa najlepiej, gdy traktuje się ją jako mierzalną powierzchnię. Zapisz jeden idealny przykład działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres. Wolno preferować małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy jakiś krok zawiedzie, awaria powinna wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Oddziel zasady dzielenia na fragmenty od zasad wyszukiwania. Zmiana jednych nie powinna zmuszać do przepisywania drugich, gdy zmieniają się metryki jakości.
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": "..."
}
A co z umiejętnościami agenta?
Etap „A co z umiejętnościami agenta?” działa najlepiej, gdy traktuje się go jako mierzalną powierzchnię do analizy. Zapisz jeden idealny przykład działania, jeden przypadek niepowodzenia oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres pracy. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy poszczególnym elementom, zdefiniuj kryteria sukcesu i odrzucaj ciche, częściowe ukończenie zadań. Utrzymuj stan grafu w prostej formie i określonej strukturze typów. Wplecione elementy ukrywają informację o tym, który węzeł zapisał dane w danym polu, co powoduje przerwanie kontynuacji pracy po zakłóceniach.
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/
Najbardziej interesujący przypadek użycia OKF jest w rzeczywistości lokalny
Etap przypadeku użycia OKF funkcjonuje najlepiej, gdy traktowany jest jako mierzalna powierzchnia. Zapisz jeden idealny zapis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres. Zapisuj czasy wykonywania operacji oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy przechodzi się od środowiska demonstracyjnego do współdzielonych środowisk. Utrzymuj stan grafu w prostej formie i z określonym typem danych. Wplecione elementy ukrywają informację o tym, który węzeł zapisał dane do którego pola, i powodują przerwę w kontynuacji działania po zakłóceniach. Etap przypadeku użycia OKF funkcjonuje najlepiej, gdy traktowany jest jako mierzalna powierzchnia. Zapisz jeden idealny zapis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres. Dokumentuj zarówno optymalną ścieżkę działania, jak i ścieżkę naprawczą. Próby ponownych działań, kontrolne punkty ludzkie oraz obsługa wiadomości nieodebranych stanowią część produktu, a nie elementy dodawane później.
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
Wiedza lokalna i centralna nie muszą ze sobą konkurować
Na etapie wiedzy lokalnej i centralnej należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Lepiej używać małych, testowalnych jednostek niż rozbudowanych skryptów. Gdy jakiś krok zawiedzie, powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowany proces. Zastosuj ludzką aprobatę w przypadkach, gdy dochodzi do wydawania pieniędzy lub modyfikacji danych produkcyjnych. Połączenia realizowane w czasie kompilacji nie równają się kompletności biznesowej.
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
wersja v0.2 to moment, w którym OKF stało się znacznie bardziej kompletnym rozwiązaniem
Wersja v0.2 to etap, na którym należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanej punktacji kontrolnej, bez konieczności zgadywania ukrytego stanu. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy poszczególnym elementom, zdefiniuj kryteria sukcesu i odrzuć przypadkowe, częściowe ukończenie zadań. Zapewnij ludzką aprobatę w przypadku operacji, które wiążą się z wydawaniem pieniędzy lub modyfikacją danych produkcyjnych. Połączenia realizowane w czasie kompilacji nie równają się pełnej kompletności rozwiązania biznesowego.
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?
Zatwierdzona obliczalność to inny rodzaj wiedzy.
Ponieważ Atested Computation to określony etap, należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić ten krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy rejestrować czasy wykonywania oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy proces przechodzi z środowiska demonstracyjnego do współdzielonych środowisk. Konieczne jest ludzkie zatwierdzenie dla operacji, które generują wydatki lub zmieniają dane produkcyjne. Podłączenia realizowane w czasie kompilacji nie gwarantują pełnej kompletności rozwiązania biznesowego. Ponieważ Atested Computation to określony etap, należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić ten krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy udokumentować zarówno ścieżkę prawidłowego działania, jak i ścieżkę naprawczą. Próby ponownych działań, kontrolne punkty ludzkie oraz obsługa wiadomości błędnych stanowią część produktu, a nie elementy dodawane później.
Przetłumacz poniższy tekst z języka angielskiego na polski.Here is something we know.
Here is the approved way
to establish that something is true.
Jaki problem faktycznie rozwiązuje OKF?
Podczas przechodzenia przez etap „Jaki problem?”, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Wolno preferować małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy jakiś krok się nie powiedzie, błąd powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Ustalaj punkty kontrolne po kosztownych krokach. Narzędzie do kontynuacji pracy nie powinno ponownie naliczać opłat za tę samą wywołanie LLM, gdy operator próbuje ponownie uruchomić późniejszy element.
Lista kontrolna operacyjna
Etap listy kontrolnej operacyjnej działa najlepiej, gdy traktuje się go jako mierzalną powierzchnię do analizy. Zapisz jeden idealny zapis działania, jeden przypadek niepowodzenia oraz notatkę dotyczącą cofnięcia zmian, zanim rozszerzysz zakres pracy.
Zachowaj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności przeglądania całej struktury.
Zachowaj stan grafu w formie prostych, typizowanych elementów. Wplecione struktury ukrywają informację o tym, który węzeł zapisał dane do którego pola, i utrudniają kontynuację pracy po przerwach.
Gdy budżet na to pozwala, dodaj test sprawdzający kluczową ścieżkę w procesie CI przy użyciu narzędzi testowych, a nie rzeczywistych, płatnych API.
Dokumentuj zarówno prawidłową ścieżkę działania, jak i ścieżkę przywracania do normalnego funkcjonowania. Próby ponownych działań, kontrola przez ludzi oraz obsługa wiadomości błędowych stanowią część produktu, a nie elementy dodawane później.
Zachowaj stan grafu w formie prostych, typizowanych elementów. Wplecione struktury ukrywają informację o tym, który węzeł zapisał dane do którego pola, i utrudniają kontynuację pracy po przerwach.
Zanim wdrożysz cały stack, zamroź wersje, utwórz „złoty transkrypt” dla kluczowej ścieżki oraz potwierdź kroki odwracania zmian. Środowiska współdzielone wymagają ograniczeń szybkości, weryfikacji użytkowników oraz wyraźnego właściciela odpowiedzialnego za rotację haseł. Wolisz nudną niezawodność od sprytnych, jednorazowych demonstracji.
Uwaga dotycząca procesu batch dla 758c51495df5: unikaj przechowywania kluczy dostawcy w repozytorium, ustaw ograniczenie liczby tokenów na sesję oraz przechowuj transkrypty obok plików testowych, aby późniejsze zmiany modeli pozostały porównywalne.
Uwaga dotycząca wzmocnienia bezpieczeństwa na etapie 0 działa najlepiej, gdy jest traktowana jako mierzalna powierzchnia do optymalizacji. Zanim rozszerzysz zakres, zapisz jeden „złoty transkrypt”, jeden przypadek awarii oraz notatkę dotyczącą odwracania zmian. Zapisuj również czasy wykonywania zadań oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy ścieżka przechodzi z demonstracji do środowisk współdzielonych.
Szczegóły wzmocnienia 0/782: zmierz czas wykonywania, klasę błędu oraz zużycie tokenów dla tej notatki, a następnie zdecyduj, czy zachować zmianę na podstawie ustalonego zestawu pytań, a nie jedynie anegdoty.
W pierwszym etapie notatki dotyczącej wzmocnienia zdefiniuj dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie wykonać ten krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Zdokumentuj zarówno prawidłowy przebieg działania, jak i ścieżkę naprawczą. Próby ponowne, kontrolne punkty ludzkie oraz obsługa wiadomości błędnych stanowią część produktu, a nie element późniejszej dopracowywania.
Szczegóły wzmocnienia 1/782: zmierz czas wykonywania, klasę błędu oraz zużycie tokenów dla tej notatki, a następnie zdecyduj, czy zachować zmianę na podstawie ustalonego zestawu pytań, a nie jedynie anegdoty.
Gdy przechodzisz przez drugi etap notatki dotyczącej wzmocnienia bezpieczeństwa, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy poszczególnym elementom, zdefiniuj kryteria sukcesu i odrzuć przypadki częściowego ukończenia bez żadnych informacji.
Szczegół 2/782 dotyczący wzmocnienia bezpieczeństwa: zmierz czas wykonywania, klasę błędu oraz zużycie tokenów dla tej notatki, a następnie zdecyduj, czy zachować zmianę na podstawie ustalonego zestawu pytań, a nie jedynie informacji anegdotycznych.
Etap trzeci notatki o wzmocnieniu bezpieczeństwa działa najlepiej, gdy jest traktowany jako mierzalna powierzchnia do analizy. Zapisz jeden idealny przykład działania, jeden przypadek niepowodzenia oraz notatkę dotyczącą cofnięcia zmian, zanim rozszerzysz zakres prac. Utrzymuj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności przeglądania całej struktury.
Szczegół wzmocnienia 3/782: zmierz czas wykonywania, klasę błędu oraz zużycie tokenów dla tej notatki, a następnie zdecyduj, czy zachować zmianę na podstawie ustalonego zestawu pytań, a nie jedynie anegdoty.
W czwartym etapie notatki dotyczącej wzmocnienia określ dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Wolno preferować małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy dany krok zawiedzie, powód awarii powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowany proces.
Szczegół wzmocnienia 4/782: zmierz czas wykonywania, klasę błędu oraz zużycie tokenów dla tej notatki, a następnie zdecyduj, czy zachować zmianę na podstawie ustalonego zestawu pytań, a nie jedynie anegdoty.
Literatura pokrewna
- Praktyczne notatki: Przetestowałem, czy rozmiar kawałków ma większe znaczenie niż dzielenie na kawałki — Szczegółowy przewodnik po Praktycznych notatkach: Przetestowałem, czy rozmiar kawałków ma większe znaczenie niż dzielenie na kawałki: umowy, sprawdzenia oraz gotowe miejsca na kod dla zespołów wdrażających ten wzorzec.
- Praktyczne notatki: RAG to coś więcej niż odzyskiwanie danych — to poszukiwanie i osąd — Szczegółowy przewodnik po Praktycznych notatkach: RAG to coś więcej niż odzyskiwanie danych — to poszukiwanie i osąd: umowy, sprawdzenia oraz gotowe miejsca na kod dla zespołów wdrażających ten wzorzec.