Twój agent AI nie potrzebuje więcej kontekstu. Potrzebuje mózgu, któremu może ufać.

Załóżmy, że o godzinie 02:14 zadzwoni pager. Otwierasz podręcznik postępowania i wygląda on doskonale – z numerowanymi krokami, schematem oraz wyraźnymi oznakami tego, że ktoś o to zadbał. Postępujesz zgodnie z krokiem 4, ale nic się nie dzieje. Na dole strony widzisz datę ostatniej edycji: czternaście miesięcy temu.

Każde zdanie w nim było poprawne w dniu napisania. Ale nie było żadnego sygnału wskazującego na to, że minął jego termin ważności.

To jest prawdziwy błąd. Nie chodzi o brak dokumentacji ani o jej złą jakość. Chodzi o dokumentację, która wygląda równie wiarygodnie w najgorszym momencie, jak i w pierwszym. Przez czterdzieści lat oprogramowanie było dostarczane z zasadą, że dokumentacja to proza, a czytelnik sam ją ocenia. Później repozytoria trafiły w ręce osób, które nie potrafią nic ocenić i które czytają każde słowo z pełnym przekonaniem.

Co się zmieniło

Agent sztucznej inteligencji nie ma własnej pamięci. Jest bezstanowy, a przy każdej turze cała rozmowa jest wysyłana na nowo od początku. Dokumentacja Anthropic stwierdza wprost: należy za każdym razem wysyłać pełną historię rozmowy.

Dlatego dokumentacja architektury składającej się z 4000 tokenów, którą agent zawsze ładuje, nie jest czytana tylko raz. W sesji trwającej czterdzieści tur jest czytana czterdzieści razy. A jej ładowanie może pogorszyć funkcjonowanie agenta.

Badania Chromy nad degradacją kontekstu przeprowadziły na 18 nowoczesnych modelach, w tym GPT, Claude, Gemini i Qwen, i wykazały, że dokładność spada wraz ze wzrostem długości danych wejściowych – w niektórych przypadkach z 95% do 60%. Kluczowym elementem, który powinien skłonić do zmiany nawyków, jest fakt, że nie chodzi tu o efekt bliski granicy możliwości modelu. Degradacja występowała na każdym poziomie długości, który sprawdzono. Jeśli te wyniki są prawdziwe, nawet okno o długości miliona tokenów zaczyna mieć problemy już przy pięćdziesięciu tysiącach tokenów, ponieważ wrogiem jest szum, a nie ograniczenia mocy obliczeniowej.

Anthropic określa to jako budżet uwagi: kontekst jest zasobem skończonym o malejących zwrotach krańcowych, a celem jest jak najmniejszy zbiór tokenów o wysokiej wartości informacyjnej. To pozostawia dwie złe opcje.

• Ładowanie wszystkiego. Agent zna system, ale wykazuje znacząco gorsze wyniki w każdym zadaniu, a każda edycja dokumentu unieważnia całą pamięć promptów i wymusza ponowne ich obliczenie.
• Brak ładowania niczego. Agent pozostaje sprawny, ale nic nie wie, więc improwizuje. Tworzy własne kroki implementacyjne lub uruchamia polecenia, które zostały wycofane już w marcu.

Zespoły wybierają jedną z opcji, doświadczają konsekwencji, a potem przechodzą na drugą. Mniej więcej w takiej sytuacji znajduje się obecnie branża.

Istnieje już diagnoza w jednym zdaniu

W kwietniu 2026 roku Andrej Karpathy opublikował krótki zarys, który nazwał plikiem z ideą. Nie była to ani produkt, ani biblioteka. Przedstawił w nim jeden podejście: model przetwarza surowe dane na uporządkowaną, strukturyzowaną witrynę typu Markdown, a od tego momentu pytania kierowane są do tej witryny zamiast do oryginałów.

Ważny fragment tego tekstu nie ma nic wspólnego z sztuczną inteligencją: ludzie porzucają witryny, ponieważ obciążenie związane z ich utrzymaniem rośnie szybciej niż ich wartość.

Każdy, kto widział, jak umiera przestrzeń Confluence, to rozpozna. Ludzie przestawali ją używać nie dlatego, że pisanie w niej było trudne, ale dlatego, że konserwacja była skomplikowana, a polega ona głównie na pracach biurowych: odświeżanie linków, aktualizowanie streszczeń, oznaczanie, że ta strona teraz jest sprzeczna z tamtą, poprawianie indeksu. To właśnie te zadania przestały być kosztowne, ponieważ LLM nie nudzi się, nie zapomina o odnośnikach i może przetworzyć piętnaście plików za jednym razem. Jego podział pracy jest prosty: ty to czytasz, a LLM to pisze.

Idea szybko się rozprzestrzeniła. Dwa miesiące później Google Cloud opublikowało specyfikację, która, według samego ogłoszenia, formalizuje wzorzec wiki oparty na LLM w formacie przenośnym i interoperacyjnym. Diagnoza pozostaje taka sama jak u Karpathy’ego, i to właśnie dlatego wszystko to działa teraz, a nie w 2019 roku.

OKF w pół minuty

OKF, czyli Open Knowledge Format, został opublikowany przez zespół Data Cloud w Google Cloud w czerwcu 2026 roku w wersji roboczej (v0.2) i stanowi wyraźną formalizację tego formatu. Technicznie jest to katalog plików Markdown z metadanymi w formacie YAML – to wszystko.

Specyfikacja opisuje go w następujący sposób: każdy, kto potrafi użyć polecenia cat do otwarcia pliku, może czytać pliki w formacie OKF, a każdy, kto potrafi wykonać polecenie git clone wobec repozytorium, może je rozpowszechniać.

Jedynym obowiązkowym polem jest type. Plik zawierający wyłącznie wartość type już spełnia wymagania formatu. Nie są potrzebne rejestr schematów, bazy danych, procesy wstrzykiwania danych, zabezpieczenia typu vendor lock ani żadne SDK.

okf/
  index.md                  ← table of contents
  billing/
    index.md
    invoice-retries.md      ← one file, one answerable question
  flows/
    customer-offboarding.md

Jeśli twoja reakcja brzmi „no to folder z Markdowniem”, to jest to dokładne stwierdzenie. Format nie jest najważniejszą częścią, a uzasadnionym zarzutem jest to, że folder nie wymaga specyfikacji. W komunikacie Google znajduje się odpowiedź: wiki Karpathy’ego, wiki zespołu oraz eksport katalogu dostawcy mogą wyglądać podobnie – zawierać Markdown, frontmatter i łącza międzysekcyjne – ale żaden z nich nie został zaprojektowany tak, by współpracować ze sobą. W tym właśnie polega potrzeba specyfikacji. Wszyscy niezależnie doszli do tego samego formatu, co zazwyczaj oznacza, że jest on prawidłowy, a następnie każda implementacja wymyśliła własne nazwy pól. Format przekształca kilka prywatnych konwencji w coś, co agent może odczytać wszędzie.

Główna idea: dokumentacja staje się stanem

Oto przykładowy dokument:

---
type: Playbook
title: Invoice retry policy
status: stable                      # draft | stable | deprecated
stale_after: 2026-11-01             # stale when today >= this date
generated: { by: "human:dana", at: 2026-08-10 }
verified:  [{ by: "human:sam",  at: 2026-08-11 }]
sources:
  - resource: services/billing/retry.go
    last_modified: 2026-07-15
not:
  - term: "restart the worker to clear the queue"
    why: "in-flight jobs are lost, they are not re-queued"
    instead: "drain first, then restart"
---

Pięć z pokazanych pól pochodzi z specyfikacji. Szóste jest najważniejsze i pojawia się ponownie poniżej.

Szafka na akta po prostu przechowuje dokumenty. Mózg również wie, co przechowuje, jak duże ma pewność oraz które błędy coś mu nauczyły. Poniższe elementy odpowiadają temu:

Teraz przeczytaj ten frontmatter tak, jak to zrobiłby komputer. stale_after to data wygaśnięcia. To nie jest znak „ostatnia aktualizacja”, który trzeba interpretować. To data bezwzględna, dzięki której sprawdzanie stanu aktualności staje się prostym porównaniem: today >= stale_after. Ten test może wykonać cokolwiek: agent czytający plik, zadanie zaplanowane, system CI.

Zastanów się nad tym. Problem zaniku dokumentacji jest problemem kulturowym od chwili wynalezienia wiki. Ciągłe przypomnienia, specjalne dni poświęcone dokumentacji, kwartalne audyty, a także strona „Standardy dokumentacji”, która sama już jest przestarzała. Wszystko to opiera się na presji społecznej, a nic z tego nie może być egzekwowane. Dzięki stale_after zanik dokumentacji staje się nieudanym testem, należącym do tej samej kategorii co awarii kompilacji. Albo test się udaje, albo nie – nikt nie musi się czuć źle.

Inne pola działają w ten sam sposób. sources wymienia ścieżki kodowe, które opisuje dokument, dzięki czemu skrypt może w końcu odpowiedzieć na pytanie, na które wiki nigdy nie były w stanie: ta prośba o integrację zmieniła plik, który według trzech dokumentów ma go opisywać, więc czy ktoś je zaktualizował? verified rejestruje osoby, które potwierdziły dokładność dokumentu, oddzielnie od tych, które go napisали, ponieważ, jak brzmi specyfikacja, osoba, która stworzyła dany koncept, nie musi być tą, która go potwierdziła. Projekt przygotowany przez agenta oraz zatwierdzenie przez doświadczonego inżyniera to dwa odrębne zdarzenia, na które większość narzędzi do dokumentacji nigdy nie zwraca uwagi. Poziomy zaufania są wyprowadzane na podstawie przedrostka określającego wykonawcę i nie są przechowywane, ponieważ przechowywana ocena jest subiektywna, nieprzenoszona pomiędzy różnymi użytkownikami i z czasem ulega przestarzeniu.

status: deprecated umożliwia zachowanie starej definicji zamiast jej usunięcia. Gdy dwa panele kontrolne różnią się co do wartości „przychodu”, przyczyną często nie są błędne dane, lecz dwie różne definicje – jedna została cicho zastąpiona, a żadna z nich nie została oznaczona. Zachowaj obie, oznacz jedną, a dane z poprzedniego kwartału nadal będą dostępne.

To właśnie jest ta zmiana: nie chodzi o ładniejszy format tekstu, lecz o tekst w połączeniu z możliwością przeszukiwania stanu. Dokumenty można analizować, testować i sprawdzać ich poprawność.

Arytmetyka tokenów

Te wartości zostały zmierzone w porównaniu z opublikowanym przykładem od Google, więc można je sprawdzić:

Przetworzenie jednego faktu od początku do końca kosztuje około 950 tokenów i jest naliczane tylko w przypadku zapytań, które tego wymagają. Część działająca zawsze to poziom 0: sześćdziesiąt tokenów, jedno zdanie.

Porównaj to z typowym podejściem: przewodnik o długości 1600 tokenów jest dodawany do każdego zapytania, chociaż być może tylko jedno na dziesięć go potrzebuje. Wiedza pozostaje ta sama, średni koszt wynosi około jednej dziesiątej, a dokument może rosnąć bez ograniczeń, ponieważ dodatkowa długość nie wpływa na niepowiązane rozmowy w repozytorium. Specyfikacja oparta na index.md realizuje ten cel, nadając mu nazwę – stopniowe ujawnianie informacji: najpierw sprawdza się, co już istnieje, a potem otwiera się dokumenty.

Czym OKF nie jest

OKF nie pełni funkcji zabezpieczenia. Plik Markdown nie może powstrzymać agenta przed uruchomieniem czegoś destruktywnego. Rzeczywiste egzekwowanie musi odbywać się poprzez kod, takie jak listy zakazów i haki przed wykonywaniem, które blokują dane działanie bez względu na wybór modelu. Bez względu na to, co jeszcze pamiętasz, nie zakładaj, że zapisanie zagrożenia oznacza, że jesteś chroniony.

To, co naprawdę daje OKF, to agent, który wie. Specyfikacja definiuje ponadto typ Attested Computation, w którym agent może przekazywać parametry, ale nigdy nie może pisać ani modyfikować samej procedury obliczeniowej – to najbliższe, co można osiągnąć, chcąc zabronić przeredagowywania sprawdzania bezpieczeństwa. Bądź tego świadom, ale na razie nie buduj na tym: specyfikacja mówi, że ta interfejsowa struktura zostanie wyraźnie przełożona na późniejszą wersję.

Pamiętaj również, że to jest wersja robocza. Przejście z v0.1 na v0.2 już zmieniło nazwy dwóch konstrukcji, więc przyjmij tylko osiem pól, których potrzebujesz. Każda późniejsza zmiana nazwy będzie polegać na wyszukiwaniu i zastępowaniu.

Zacznij od małego, dodawaj mechanizmy kontroli wtedy, gdy jest to konieczne

To nie jest projekt – to jeden plik.

1. Napisz jeden dokument o tym, co ostatnio kogoś kosztowało popołudnie, zawierający pola type, title, description oraz stale_after.
2. Napisz plik index.md, który go wymieni, z kolumną „kiedy to przeczytać”, i dodaj okf_version: „0.2”. Korzeniowy indeks to jedyny miejsce, do którego należy to pole, a zgodnie ze specyfikacją jest to jedyne frontmatter, które indeks może zawierać.
3. Dodaj wskaźnik do swojego pliku zawsze dostępnego. Kosztuje on około sześćdziesięciu tokenów i zawiera ścieżkę oraz wyzwalacz, ale nigdy streszczenie, ponieważ streszczenie zarówno zwiększa koszt utrzymania pliku zawsze dostępnego, jak i nadal zmusza agenta do otwarcia pliku.

To wystarczy, aby rozpocząć pracę. Ponieważ today >= stale_after to po prostu porównanie, agent może je ocenić zaraz po otwarciu pliku. To, co zrobić z przestarzałym dokumentem, zależy od ciebie – specyfikacja celowo pozostawia to otwarte.

Dodaj automatyzację w momencie, gdy druga osoba może unieważnić twój dokument bez jego czytania. To jest prawdziwy próg, a dotyczy on raczej wielkości zespołu niż poprawności. Przy pięciu dokumentach sam to zauważysz, a wystarczy sprawdzanie terminu ważności po stronie agenta. W zespole osoba, która niszczy twój dokument, to z definicji ktoś, kto nigdy go nie otworzył, więc dobre intencje nie mogą do niego dotrzeć – musi to zrobić jakiś element w procesie pull request. Tańsza wersja to zadań zaplanowane, które zgłaszają wygasłe dokumenty. Silniejsza wersja to brama w procesie pull request, która blokuje go przy wygasłym dokumencie i wyświetla ostrzeżenie, jeśli kod opisany w dokumencie został zmodyfikowany. Zacznij od tańszej opcji.

Wersja skrócona

To, czego potrzebuje agent, to nie większe okno kontekstowe. Potrzebuje wiedzy, gdzie szukać, a każdy otwierany plik musi być szczery co do swojego wieku. Sześćdziesiąt tokenów na początku, reszta na żądanie, oraz dokument, który może zakłócić proces budowania, gdy przestanie być prawdziwy – co wcześniej nie było możliwe.

Dalsza lektura: specyfikacja OKF v0.2 oraz przykładowe pakiety, post Google Cloud na temat tego formatu, artykuły Anthropic o inżynierii kontekstu, umiejętnościach agentów i buforowaniu promptów, a także badanie Chromy nad degradacją kontekstu.

Powiązana lektura

• Praktyczne notatki: Twój agent programistyczny nie potrzebuje więcej kontekstu. Potrzebuje mapy. — Krok po kroku instrukcja korzystania z Praktycznych notatek: Twój agent programistyczny nie potrzebuje więcej kontekstu. Potrzebuje mapy.: umowy, sprawdzenia oraz miejsca na kod do wstawienia dla zespołów wdrażających ten wzorzec.
• Praktyczne notatki: Twój agent programistyczny nie potrzebuje lepszego promptu — Krok po kroku instrukcja korzystania z Praktycznych notatek: Twój agent programistyczny nie potrzebuje lepszego promptu: umowy, sprawdzenia oraz miejsca na kod do wstawienia dla zespołów wdrażających ten wzorzec.

Praktyczne notatki: Izraelski technologiczny radar 2026-27: Inżynieria w epoce agentów — Szczegółowy przewodnik po Praktycznych notatkach: Izraelski technologiczny radar 2026-27: Inżynieria w epoce agentów: umowy, sprawdzenia oraz miejsca na kod do wstawienia dla zespołów wdrażających ten model.