Практычныя прытамулкі: 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: звярніце увагу на час выканання, класы памылак і колькасць выкорыстоўваных токенаў для гэтага запісу, а пасля, на аднойчынай базе фіксаванага набору пытанняў, а не на асобістых спазырах, выявіце, чы хачаце застаўіць змяну.