Практычныя нататкі: OKF — гэта больш, чым Markdown

У гэтым карыце парадокс занова ствараецца ад сыр'ёчных матэрыялаў да рабочай сістэмы для праекту «OKF Is More Than Markdown: How I Think About a Portable Knowledge Layer for AI Agents». Акцэнт ставіцца на практычныя крокі, чыстае перакананне ў правільнасці дзействаў і код, які можна проста падключыць у рэпазітарый, не прабуючы здогадвацца пра мету. У стадыі агледку неабходна з'явіць вхідныя даны, адпаведальнага за крок і крытэрыя завершэння прычынным чынам перад зменай коду. Аператары должны магчымае перадзванаць крок з вядомай точкі контролю, не прабуючы здагадвацца пра схованы стан. Неабходна аддактуваць документацыю як пра успішны ход задачы, так і пра шляхі ўстранення проблем. Перапрыбуткі, людзкія перакрыцчы і обработка некорэктных паведамленняў ёсць часткай продукту, а не чымсь, што дадаецца пазней.

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

Агенты ўплывныя, але яны так і не ведаюць, як працюе ваш продукт

Калі працуеце з агентамі, спачатку запісайце угоду: неабяжлівыя даны, сігнал успеху і тое, што выходзіць у разе частковага невыпання. Такі спіс пераконтроўкаў дапамагае заліцвачыць змяны ў кодзе чыста. Валічыце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выйшоў, невыпанне павінна вказваць на адную адпаведальнасць, а не на заплутаны ланцюг задач. Робіце пераконтроўку пасля дорогіх крокаў. Сістэма вярнення не павінна знову ставіць плату за той самы вызов LLM, калі аператар перапрыяўляе працу да наступнага вузла.

Wiki
PDF
Product docs
Shared Drive
API documentation
Source code
JIRA Tickets
Slack threads
Google Drive
People's heads

Важным элементам OKF не ёсць Markdown

Калі працуеце над стадзіяй «Важны элементы», спачатку запісайце умовы кантракту: неабяжлівыя даныя, сігнал успеху і тое, што выканаецца у разе частковага нявыпання. Такі спіс пераконвае ў тым, што пазнейшыя змены коду будуць чыстымі. Спрыятлівае ставленне да гэтай стадзіі як да кантракту межу данымі і перакананымі выходамі. Дайце назвы элементам, задаце крытэрыя успеху і не падзеўляйцеся частковым завершэнням без паведамлення. Зробіце перапытку пасля дорогіх крокаў. Програма для продакцыі не должна зноў выканаць той самы вызов LLM, калі аператар пракушае пазнейшы вузел.

Пакеты, концэпціі і тое, што вам найбольш цікавае: index.md

Калі працуеце з кансэптамі Bundles і ўрадзаемасцю, спачатку запісайце контракт: неабяжлівыя даныя, сігнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі спіс контроля дапамагае заліцвачыць пазнейшыя змены коду. Запісвайце час выканання і кост токена або запыту празаўсёды разам з рэзультатамі функцыйнасці. Відразлівасць костаў з самага пачатку запобегае неспакойным рахункам, калі працэс пераходзіць з дэмаверсіі ў спяльныя асяроддзя. Зробіце контрольную паўзу пасля дорогіх крокаў. Функцыя адновлення не должна зноў выкарыстоваць той самы вызов LLM, калі аператар прабуе зноў выканаць пазнейшы вузел. Калі працуеце з кансэптамі Bundles і ўрадзаемасцю, спачатку запісайце контракт: неабяжлівыя даныя, сігнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі спіс контроля дапамагае заліцвачыць пазнейшыя змены коду. Дакументавайце як «вдалы» шлях, так і шлях вярнення да нормальнасці. Прабулі, людзкія контролы і обработка неканальных паведамленняў ёсць часткай продукту, а не пазнейшым дапрацоўкам.

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

Цікава, гэта не проста RAG?

Фраза «Цікава, гэта не проста...» работае наяўней, калі яе спрыяваць як мерыемую паверхню. Зафіксавайце адна ідэальная транскрыпцыя, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану перш чым расшырваць масштабы. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выходзіць, прычына неудачы павінна вказываць на адну конкрэтную адпаведальнасць, а не на заплутаны працэс. Раздзеляйце правіла часткавання інфармацыі ад правіл яе выкарыстоўвання. Змена адных не павінна вымагаць перапісву іншых, калі зменяюцыся паказатэлі якосці.

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": "..."
}

А як ўжо з навыкамі агента?

Этап «А як ўжо з навыкамі агента?» працюе наяўней, калі яго розглядаць як мерыемую структуру. Запісаўце адна ідэальная прымерка, адзін кейс неудачы і запіс пра вярнэнне да пачатковага стану перш чым расшырваць масштабы. Разглядзіце гэты этап як кантракт межа вхіднымі данымі і падтверджанымі выходнымі рэзультатамі. Даўце назвы артыфактам, задаце крытэрыя успеху і не падзеўляйцеся частым, непূরным вікананнем задачы. Храніце стан графа ў простам і тыпаваным фармаце. Вкладзеныя структуры маскуюць інфармацыю пра тое, які вузел запісаў кожны поле, і спакшваюць продовжэнне працы пасля перэрываў.

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/

Сцэна выкарыстання OKF, якая вам здаецца найцікавейшая, на самай працоўны спосаб дзеяе як меркаваная структура

Этап сцэны выкарыстання OKF працюе найкрашча, калі яго розглядаць як меркаваную плошчу. Зафіксуйце адны ідэальны прыклад працы, адну сцэну абярошчэння і прыметку па вярненню да пачатковага стану прычым расшырэнню масштаба. Запісвайце часы выканання і косты токеноў або запытак разам з функцыйнальнымі рэзультатамі. Відразлівае прадставлення костаў з’являецца рана, таму не будзе неспакою, калі працэс перэйдзе з дэма-серавера ў спільныя асяроддзя. Размякшчайце стан графа і забезпечыце яго тыпавасць. Вкладаныя структуры маскуюць інфармацыю пра тое, які вузел запісаў які поле, і спакшваюць возз’яджанне пасля перарываў. Этап сцэны выкарыстання OKF працюе найкрашча, калі яго розглядаць як меркаваную структуру. Зафіксуйце адны ідэальны прыклад працы, адну сцэну абярошчэння і прыметку па вярненню да пачатковага стану прычым расшырэнню масштаба. Дакументавайце як шлях успеху, так і шлях вярнення да нормальнага стану разам. Перапрыбуткі, людзкія контрольны пункты і обработка некорэктных паведамленняў ёсць часткай продукту, а не чымсь, што дадаецца пазней.

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

Местныя і цэнтральныя знання не павінны конкуруваць

Для етапу местных і цэнтральных знанняя неабходна ўзгадка вхідных даных, адпаведальнага за кожны крок і крэтарыяў завершэння працы перад змінайом коду. Аператары должны магчымае перзапускаць крок з вядомай точкі контролю, не прабуючы спадарацца пра схованы стан. Валідзіце маленькія, тэставаныя елементы замест большых скрыптаў. Калі крок не выйшоў, прычына нехацкага рэзультата павінна вказываць на адну конкрэтную адпаведальнасць, а не на заплутаны ланцужок задач. Заставляйце людзей апраўдваць тыя крокі, якія ведуць да вітрачання грошаў чы змены дадзэнняў у працоўным сераверы. Компіляцыйныя налашчэння не ўзначаюць повнасці бізнес-процэсаў.

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 — гэта тыя пункт, калі OKF пачаў выглядаць значна болей завершаным

У версіі v0.2 прадакт узначае вхідныя даны, адпаведальнага за кожны крок і крытэрыя завершэння пры зміне коду. Аператары должны магчымаць перзапуск крока з вядомай точкі контролю, не спрабоўваючы здогадвацца пра схованы стан. Спрыяйце таму, каб гэты этап быў схожы на контракт межа вхіднымі данымі і перакананымі выходнымі рэзультатамі. Дайце назвы артыфактам, узначыце крытэрыя успеху і не падтрымайце безсловеснае частковае завершэння. Забезпечыце людскія апраўдкі для тых крокаў, якія выкарыстоўваюць грошы або зміняюць даны ў працэсе віробніцтва. Компіляцыйныя налашчэння не ўзначаюць завершанасці бізнес-процэсу.

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?

Атстацаваныя вычысленнія — гэта іншы тып знаёмасцей.

Калі «Атэставаная вычыслаўная процедура» ёсьць окрэмы этап, перад змянай коду неабходна задаць вхідныя даны, адпаведальнага за шаг і крэтыяры завершэння. Аператары должны магчымае перайсці на выкананне шага з вядомага пункта контролю, не спрабоўваючы здагадвацца пра схованы стан. Запісвайце час выканання і кост токенаў або запытаў разам з функцыйнальнымі рэзультатамі. Відразлівае паказанне костаў запобегае неспадзяваным рахункам, калі працэс пераходзіць з дэмовай асяроддзя ў спадзеленыя. Заставіце людскую апраўдку для тых крокаў, якія выкарыстоўваюць грошы або зміняюць даны ў працэсе віробніцтва. Працэс складання коду не ёсць адпаведнікам повнай готовасці продукту для эксплуатацыі. Калі «Атэставаная вычыслаўная процедура» ёсьць окрэмы этап, перад змянай коду неабходна задаць вхідныя даны, адпаведальнага за шаг і крэтыяры завершэння. Аператары должны магчымае перайсці на выкананне шага з вядомага пункта контролю, не спрабоўваючы здагадвацца пра схованы стан. Дакументавайце як «успешны» шлях, так і шлях вярнення да нормальнага стану. Перапрыбуткі, людскія контрольныя пункты і обработка некорэктных запытаў ёсць часткай самага продукту, а не чымсь, што дадаецца пазней.

>

Here is something we know.

Here is the approved way
to establish that something is true.

То якую ж проблему насправды рашчыляе OKF?

Калі працуеце на этапе «То якая проблема?», спачатку запісайце умовы: неабяжлівыя даны, сігнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі спіс контроля дапамагае заліцвачваць змяны ў кодзе. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выйшоў, прычына нявыпання павінна вказываць на адну конкрэтную адпаведальнасць, а не на заплутаны ланцюг задач. Зробіце перапаказ пасля дорогіх крокаў. Програма не павінна зноў ставіць плату за той самы вызов LLM, калі аператар праканае пазнейшы вузел.

Чэк-ліст для эксплуатацыі

Этап чэк-ліста для эксплуатацыі працюе найэфектывней, калі яго спрыяглядаць як меравальную плошчу. Запісайце адны ідэальны прыклад працы, адзін кейс нявыпання і прыметкі па адкату перш чым расшырваць масштабы.

Зберагаюце канфігурацыю пазначкай за межамі коду прыемліка. Файлы сяродавішча, храненні секрэтных дадзей і флагі функцыйяў должны знаходзіцца ў аднам месцы, куды аператары можаюць адбавіць аўдыт без неабяжнага чытання всей структуры.

Зберагаюце стан графа ў простай і тыпаванай форме. Вярнутыя блокі маскуюць інфармацыю пра тое, які вузел запісаў якое поле, і спакоююць працэс пасля перарываў.

Калі дозволяе бюджэт, дадаце тэст на перакананне, які працюе з крытычным шляхам у CI за дапамогою фіксатываў, а не з рэальнымі платнымі API.

Документаваць трэба як шлях успеху, так і шлях вяснавання. Перапрыбуткі, людзкія контралі і обработка некорэктных паведамленняў ёсць часткай продукту, а не чымсь, што дадаецца пазней.

Зберагаюце стан графа ў простай і тыпаваной форме. Вярнутыя блокі маскуюць інфармацыю пра тое, які вузел запісаў якое поле, і спакоююць працэс пасля перарываў.

Перш чым запускаць стак, заморозьце версіі, зафіксавайце ідэальны транскрыпт для крытычнага шляху і паказвайце спосабы атрыбутавання. У спільных срэдах неабяжна наявнасць лімітавання частоты запыткаў, пераконтроўвання прав на выкорыстоўванне рэсурсаў і чысткая адпаведальнасць за зміну секрэтных даных. Лепш выбраць простую надзею на надзейнасць, чым хітрыя експерыментальныя дэманстрацыі.

Прыметка для 758c51495df5: не кладзіце ключы прадаўца ў рэпазітарый, задаце ліміт токена на кожную сесію і зберагачыце транскрыпты празаўсёды разам з фіксатрамі для ацэнкі, каб пазнейшыя замены мадэляў заставаліся порównаннэй.

Прыметка па забезпечэнню надзейнасці на стадыі 0 работае лепш, калі яе спрыягчваць як мерыемую плошчу. Зафіксавайце адны ідэальны транскрыпт, адзін прыклад неудачы і прыметку па атрыбутаванні перш чым расшырваць масштаб. Запісвайце часы выканання і вартасць токена або запыткаў празаўсёды разам з функцыйнальнымі рэзултатамі. Відкрытая візуабільнасць вартасцей запобегае неспакойным рахункам, калі шлях пераходзіць з дэманстрацыі ў спільныя асяроддзя.

Дзеянне паўжчання 0/782: звярніце увагу на час выканання, клас памылакі і колькасць выкорыстоўваных токенаў для гэтага запісу, а пасля, на аднойчынай базе фіксаванага набору пытанняў, а не на асобістых спазыраннях, выявіце, чы робіць змены.

Для першага этапу запісу паўжчання неабходна перад змянай коду чытко візначыць вхідныя даны, адпаведальнага за крок і крытэрыя завершэння. Аперацыйныя працавнікі павінны магчымае перадзванаць крок з вядомай точкі контролю, не прабуючы спадарацца пра схованы стан. Неабходна адначасова задокументаваць шлях успеху і шлях вярнення да нормальнага стану. Практыка павторных спроб, людзкія перакрыцця і обработка некорэктных паведамленняў ёсць часткай продукту, а не чымсь, што дадаецца пазней.

Дзеянне паўжчання 1/782: звярніце увагу на час выканання, клас памылакі і колькасць выкорыстоўваных токенаў для гэтага запісу, а пасля, на аднойчынай базе фіксаванага набору пытанняў, а не на асобістых спазыраннях, выявіце, чы робіць змены.

Калі працуеце над 2-м ўрадзамом павышэння безпекі, спачатку запісайце контракт: неабяжныя вхідныя даны, сігнал успеху і тое, што выходзіць у разе частковага невыпання. Такі спіс контроля дапамагае залічыць пазнейшыя змены ў кодзе чыстымі. Спрэцьвачайце гэты ўрадзам як контракт межа вхіднымі данымі і перакананымі выходнымі рэзультатамі. Дайце назвы артыфактам, задацьце крытэрыя успеху і адмовіцеся ад мовчанкавага частковага завершэння.

Дзеянні павышэння безпекі 2/782: звярніце увагу на час выканання, класы каштоўкаў і вітрату токенав для гэтага ўрадзама, а пасля вырашыце, чы робіць змены на адной пазначанай базе пытанняў, а не на адной лічбе прыкладаў.

2-й ўрадзам павышэння безпекі працюе найкрашча, калі яго спрэцьвачваюце як меравальную плошчу. Запісайце адну ідэальную транскрыпцыю, адзін прыклад невыпання і змест карэкціі перад расшырэнням масштаба. Зберагайце настройкі праза код аплікацыі. Файлы сяродавішча, хранільнікі секрэтных даных і флагі функцый павінны знаходзіцца ў адном месцы, якое аператары можаць пераглядаць без неабяжнага чытання всіх элементаў.

Дзеянне паўжасткі 3/782: звярніце увагу на час выканання, класы памылак і колькасць выкорыстоўваных токенаў для гэтага запісу, а пасля, на аднойчынай базе фіксаванага набору пытанняў, а не на асобістых спазырах, выявіце, чы хачаце застаўіць змяну.

Для 4-го этапа паўжасткі неабходна перад змянай коду чытко візначыць вхідныя даны, адпаведальнага за шаг і крытэрыя завершэння. Аперацыяныя працавнікі должны магчымае перадзваначыць шаг з вядомай точкі контролю, не падозрываючы прыхованы стан. Лепш выбіраць маленькія, тэставаныя елементы замест большых скрыптов. Калі шаг не выйшоў, прычына неудачы должна вказываць на адну конкрэтную адпаведальнасць, а не на заплутаны працэс.

Дзеянне паўжасткі 4/782: звярніце увагу на час выканання, класы памылак і колькасць выкорыстоўваных токенаў для гэтага запісу, а пасля, на аднойчынай базе фіксаванага набору пытанняў, а не на асобістых спазырах, выявіце, чы хачаце застаўіць змяну.