Практычныя прытамулкі: Google тылькі тыха адпублікуў неяшчэ відсутнюю частку для агентаў AI.
Практычныя прытамулкі: Google тыха адпублікуў неяшчэ недастатковы элемент для агентаў AI — кантракты, перакрыццяі і слоты для коду, якія можна прыўязаць для команд, якія викорыстоўваюць гэты патэрн.
Існавайце гэта як перапрацоўаны варыянт ідэй з артыкула “Google проста тыха выдала нехватную частку для AI-агентаў. Яе называюць OKF.”, адпрацаваны для аператараў: чыстыя этапы, аранжаваныя блакіткі коду і прыметкі з восстанавлення, якія застаюцца пасля перадачы. Этап Аналізу працюе найэфектывней, калі яго розглядаць як вимерную плошчу. Запісаўце адна ідеальная транскрыпцыю, адзін прыклад неудачы і прыметку з вярненням да пачатковага стану, прычаму расшырюваць масштабы. Валідзіце маленькія, тэставаныя елементы замест амаль неконтрольваных скрыптав. Калі якісьць крок не выходзіць, прычына неудачы павінна вказываць на адную адпаведальнасць, а не на заплутаны ланцюг задач.
Проблема, якую гэта рашае
У стадії «Проблема, яку янае», перш чым змяніць код, неабходна ясная ваказка пра вхідныя даны, адпаведальнага за крок і крэтырыя для завершэння. Аперацыіям павінна быць можлівасць перзапускаць крок з вядомага пункта контролю, не спрабоўваючы здагадвацца пра схованы стан. Спрыяйце цій стадіі як даговору межа вхідных даных і перакананых выходных рэзультатаў. Даўце назвы артыфактам, вакажце крэтырыя успеху і не прымайце тыхню частковую рэалізацыю. Заставьце людскія апраўданні для тых крокаў, якія выкарыстоўваюць грошы або змянююць даны для працы. Компіляцыйныя налашчэнні не ўзроўнаваны з абсягам роботы для бізнесу.
+-----------------------+--------------------------------------------+
| WHERE IT LIVES | WHAT'S THERE |
+-----------------------+--------------------------------------------+
| Metadata catalogs | Table schemas (but vendor-locked APIs) |
| Wiki / Notion | Runbooks, metric definitions |
| Code comments | Docstrings, inline notes |
| People's heads | Join paths, deprecation warnings |
+-----------------------+--------------------------------------------+
Што насправды ёсць OKF
Для этапа «Што на самай працо ў OKF?» неабходна пазначыць вхідныя даны, адпаведальнага за крок і критэрыя завершэння пры перадзеіснавленні коду. Аператары должны магчымае запускаваць крок з вядомай точкі контролю, не прабуючы спадарожваць схованы стан. Запісвайце час выконання і вартасць токена або запыту праза функцыйнальныя рэзултаты. Відразлівая вартасць з самага пачатку запобегае неспакоўным рахункам, калі процес пераходзіць з дэмавайнага режыма ў спяльныя сераўры. Заставіце людзкую апрацоўку для тых крокаў, якія выкарыстоўваюць грошы або зміняюць даны ў працэсе виробніцтва. Працэс складання коду не ўзроўнаважваеся з повнасцю бізнес-процэсаў.
Структура: каталог — граф знанняў
Для стадіі «The Structure A Directory» неабяжна ўзначыць вхідныя даны, адпаведальнага за крок і крэтыяры завершэння пры змены коду. Аперацыйныя працавнікі павінны магчымае перазапускаць крок з вядомай точкі контролю, не падозрываючы прыхованы стан. Конфігурацыю трэба захаваць паза кодам прыкладнення. Файлы сераўіса, хранільнікі секрэтных дадзеных і флагі функцыйяў павінны знаходзіцца ў адном месцы, якое працавнікі можуць пераглядаць, не чытаючы весь ланцуг задач. Прызначайце людскія апраўленні для рэлей, якія выкарыстоўваюць грошы або зміняюць даны у працэйным режыме. Підключэння ў час компіляцыі не є падтверджэнням полной адпрацоўкі бізнес-процэсаў. Для стадіі «The Structure A Directory» неабяжна ўзначыць вхідныя даны, адпаведальнага за крок і крэтыяры завершэння пры змены коду. Аперацыйныя працавнікі павінны магчымае перазапускаць крок з вядомай точкі контролю, не падозрываючы прыхованы стан. Валіце маленькія, тэставальныя елементы над велікімі скрыптамі. Калі крок не выйшоў, прычына нехарактернага рэзультата павінна вказываць на адную адпаведальнасць, а не на заплутаны ланцуг прычын.
Канал адміністрацыі.
.okf/
+-- index.md <- progressive entry point
+-- log.md <- dated change history, newest first
+-- services/
| +-- index.md
| +-- auth-api.md <- one concept = one file
| +-- payments-service.md
+-- datasets/
| +-- index.md
| +-- orders-db.md
+-- metrics/
| +-- index.md
| +-- weekly-active-users.md
+-- decisions/
+-- index.md
+-- why-we-use-postgres.md
Структура файла концэпцыі OKF
Калі працуеце над этапам «Структура файла концэпцыі OKF», спачатку запісайте умовы кантракту: неабяжлівыя даннэ, сігнал успеху і тое, што выканаецца у разы частковага нявыполнення. Такі список контроля дапамагае заліцвачыць змяны коду. Спрэтавайцеся да гэтага этапу як да кантракту межу вхіднымі даннымі і перакананымі выходнымі рэзультатамі. Дайце назвы элементам, задаць критэрыі успеху і не прабуйце прыймаць часткова завершанне без паведамлення. Зробіце контрольны пункт пасля дорогіх крокаў. Програма для продакцыі не должна занова ставіць плату за той самы вызов LLM, калі аператар прабуе зноў запрацаваць з пазнейшым вузлам.
---
type: Service
title: "Auth API"
description: "Issues and verifies short-lived access tokens."
resource: https://github.com/acme/auth
tags: [auth, platform]
timestamp: 2026-06-14T10:00:00Z
---
## Endpoints| Method | Path | Description |
|--------|----------|---------------------------|
| POST | /token | Exchange creds for a JWT. |
| GET | /verify | Validate a token. |## Why This ExistsSee the decision at [decisions/why-we-separated-auth.md](../decisions/why-we-separated-auth.md).
Joins with [datasets/orders-db.md](../datasets/orders-db.md) for user scoping.
[auth-api.md]
/ \
links links
/ \
[decisions/why-separated-auth.md] [datasets/orders-db.md]
|
links
|
[datasets/customers-db.md]
Тры прынцыпы дизайна
Калі працюеце над стадзіяй «Тры прынцыпы дизайна», спачатку запісаце кантракт: неабяжлівыя даны, сігнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список перакладоў заходзіць пазнейшыя змены коду чыстымі. Запісваце час выканання і кост токенаў або запытаў праза функцыйнае рэзультат. Відкрытыя даны пра косцы запобегаюць неспакоўным рахункам, калі працэс пераходзіць з дэмаверсіі ў спяльныя среды. Ствараце контрольны пункт пасля дорогіх крокаў. Система адновлення не должна зноў нарахоўваць косты той самай вызову LLM, калі аператар прабуюць зноў запрацаваць пазнейшы вузел.
1. Мінімальна суб’екtyвны
Калі працуеце на стадзіі «1 Minimally opinionated», спачатку запісайце контракт: неабяжлівыя даны, сигнал успеху і тое, што выканаецца пад частковай нявыходзе. Такі список пераканаецца, каб пазнейшыя змены коду былі чыстымі. Зберагаеце настройкі за межамі коду прыемлі. Файлы сераўіснага сэрвісу, храненні секретных дадзенаў і флагі функцыйяй должны знаходзіцца ў аднам месцы, куды аператары можаюць адбавіць аудыт без неабяжлівага чытання всей структуры. Стварайце контрольныя пункты пасля дорогіх крокаў. Функцыя вярнення до роботы не должна занова ставіць плату за той самы вызыв LLM, калі аператар перапрыяўляе роботу да наступнага элемента. Калі працуеце на стадзіі «1 Minimally opinionated», спачатку запісайце контракт: неабяжлівыя даны, сигнал успеху і тое, што выканаецца пад частковай нявыходзе. Такі список пераканаецца, каб пазнейшыя змены коду былі чыстымі. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі крок не выйшае, прычына нявыходзу должна вказываць на адну адпаведальнасць, а не на заплутаную лінію обработкі.
2. Незалежнае функціонаванне виробніка і спожывача
Этап 2 «Виробнік і спожывач» працюе найэфектыўней, калі яго розглядаць як вимерную паверхню. Зафіксавайце адна ідеальная версія, адзін прыклад неудачы і запіс пра вярнэнне да попераднего стану перш чым расширваць масштаб. Разглядайце гэты этап як кантракт межа вхіднымі даннымі і паверыжанымі выхіднымі рэзультатамі. Дайце назвы артыфактам, задаце критэрыя успеху і не падзеўляйцеся частым, непূরным викананнем задачы. Храніце стан графа як просты і з адначытаемымі дадзеннямі. Вкладаныя структуры дадзеных масквяцяюць, який вузел запісаў кожны поле, і спакоююць продовжэнне роботы пасля перерываў.
PRODUCERS CONSUMERS
--------- ---------
Human authors ----> AI agents
BigQuery pipelines ----> HTML visualizers
LLM-generated ----> Search indexes
Wiki exports ----> Other agents / tools
3. Фармат, а не платформа
Фармат 3, які не ўключаюць платформенага этапу, працуюць наякша, калі іх розглядаць як вимерную паверхню. Запісаўце адна «золатая» транскрыпцыя, адзін прыклад неудачы і прыметку па адвярненню змян перш чым расширваць масштаб. Запісвайце часы выканання і кост токена або запиту праза функцыональныя рэзультаты. Відкрытасць костаў з самага пачатку запобегае неспакою з боку расчыткаў, калі процес пераходзіць з дэмавайнага режыма ў спакульнае сераўерное сэрвіса. Храніце стан графаў у простам і типаваным формате. Вкладзеныя блокі маскуюць інфармацыю пра тое, який вузел запісаў кожны поле, і спакштуюць продажчык працы пасля перарываў.
OKF проты всіх іншых апцый, якія вы вжо выкарыстоўвайце
Этап OKF проты ўсіх іншых работае наякраща, калі яго спрыяваць як меравальную паверхню. Зберагучы адна ідеальная транскрыпція, адзін прыклад неудачы і запіс пра вярненне да пачатковага стану, перш чым расширваць масштабы. Храніце конфігурацыю параду ў коду прыемлівання. Файлы сераўнавальнага сэрвісу, хранілішчы секретных дадзеных і флагі функцый должны знаходзіцца ў аднам месцы, куды аператары можаць аудытаваць, не чытаючы весь граф. Храніце стан графа у простам і типаваным формате. Вярнутыя блокі маскуюць тое, який вузел запісаў які поле, і спакоююць продаж чынення пасля перерываў. Этап OKF проты ўсіх іншых работае наякраща, калі яго спрыяваць як меравальную паверхню. Зберагучы адна ідеальная транскрыпція, адзін прыклад неудачы і запіс пра вярненне да пачатковага стану, перш чым расширваць масштабы. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выйшаў, прычына неудачы должна вказываць на адну адпаведальнасць, а не на заплутаны ланцоўкі працы.
+---------------------+---------------------------+---------------------------+
| TOOL | PURPOSE | SCOPE |
+---------------------+---------------------------+---------------------------+
| CLAUDE.md | How the agent behaves | Per-project, one agent |
| AGENTS.md | Repo instructions | Per-repo, tool-specific |
| Karpathy LLM wiki | Agent-maintained notes | Pattern, not a spec |
| MCP | Live tool access | Runtime connections |
| OKF | What the team knows | Cross-project, any agent |
+---------------------+---------------------------+---------------------------+
Звязак з Карпаты
Для этапу «The Karpathy Connection» неабяжна прадзефінавацыя вхідных дадзеных, адпраўніка крока і крэтарыяў завершэння працы перад зменым коду. Аперацыйныя працавнікі павінны магчымае перапрацаваць крок з вядомай точкі контролю, не падозрываючы прыхованы стан. Спрацавляйце гэты этап як кантракт межа вхіднымі дадзенымі і паверанымі выходнымі рэзультатамі. Даўце назвы артыфактам, прадзефінавацыя крэтарыяў успеху і адмовіцеся ад бяспрэчнага частковага завершэння. Заставіце людзкую апраўду на тых кроках, дзе выкорыстоўваюцца грошы або зміняюцыся даныя для працы. Кампайляванне коду не ўзроўнавалася з абсягам выканання бізнес-задач.
KARPATHY LAYER OKF EQUIVALENT
-------------- --------------
Raw sources (immutable) --> External datasets, docs, APIs
(OKF bundles are the compiled layer)
Wiki (LLM-maintained) --> OKF bundle (*.md + frontmatter)
(OKF adds type, resource, tags, timestamp)Schema (CLAUDE.md) --> Producer/consumer conventions + okf/SPEC.md
(org-wide spec replaces per-vault bespoke rules)
Што на самай працы адправіў Google
Для этапа «Што на самай працо выдала Google» неабяжна прадзеўліваць параметры, адпаведальнага за крок і крэтыяры завершэння пры перадзмене коду. Аперацыйныя працавнікі павінны магчымаецца перзапускаць крок з вядомай точкі контролю, не падозрываючы прыхованы стан. Запісваць час выконання і кост токенаў або запытаў разам з функцыйнальнымі рэзултатамі. Відразы костаў з самага пачатку запобегае неспакойным рахункам, калі процес пераходзіць з дэмавай версіі ў спяльныя среды. Пры кроках, якія витрачаюць грошы або зменяюць даны ў працоўнай средзе, неабяжна выкарыстоўваць падтверджэнне чалавека. Праця ў час компілявання не абавесць цэлыснасцю бізнес-процэса.
+--------------------+----------------------------------+
| BUNDLE | WHAT IT DOCUMENTS |
+--------------------+----------------------------------+
| GA4 e-commerce | Analytics tables and metrics |
| Stack Overflow | Public dataset concepts |
| Bitcoin | Blockchain dataset structure |
+--------------------+----------------------------------+
Калі выкарыстоўваць OKF
Для стадіі «Календар змаганняў OKF» неабходна прадзеянне вказаць на вхідныя даны, адпаведальнага за крок і крэтыяры завершэння пры змены коду. Аперацыйныя працавнікі павінны магчымае перзапускаць крок з вядомай точкі контролю, не падозрываючы пра схованы стан. Конфігурацыю трэба захаваць паза кодам прыемлікі. Файлы серавэсу, хранальнікі секретных дадзеных і флагі функцыйяў павінны знаходзіцца ў адном месцы, якое працавнікі можуць пераглядаць, не чытаючы весь ланцуг задач. Прызначайце людскія апраўленні для рэлей, якія витрачаюць грошы або зменяюць даны у працэйнай сістэме. Прыўязка на час компіляцыі не є падтверджэнням полной адпаведнасці да бізнес-трэбаванняў. Для стадіі «Календар змаганняў OKF» неабходна прадзеянне вказаць на вхідныя даны, адпаведальнага за крок і крэтыяры завершэння пры змены коду. Аперацыйныя працавнікі павінны магчымае перзапускаць крок з вядомай точкі контролю, не падозрываючы пра схованы стан. Валіце маленькія, тэставальныя елементы над вялікімі скрыптамі. Калі крок не выйшаў, прычына нехтарактару павінна вказываць на адную адпаведальнасць, а не на заплутаны ланцуг задач.
Як пачаткаць
Калі працюеце над этапам «Як пачаткаць», спачатку запісайте кантракт: неабяжлівыя данні, сигнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список пераконвае ў тым, што пазнейшыя змены коду будуць чыстымі. Спрэчывайце этап як кантракт межа даннімі і перакананымі выходамі. Дайце назвы элементам, задаць критэрыя успеху і не прыймайце часткова завершэння без паведамлення. Зробіце перапытку пасля дорогіх крокаў. Система вярнення не должна зноў выклікаць той самы кантакт з LLM, калі аператар прабуе зноў запрацаваць з пазнейшым вузлам.
/plugin marketplace add scaccogatto/okf-skills
/plugin install okf@scaccogatto
npx skills add scaccogatto/okf-skills
/okf:okf produce .okf # create your first bundle
/okf:validate .okf --strict # check conformance
/okf:visualize .okf # generate viz.html
---
type: Decision
title: "Why we use Postgres over MySQL"
description: "JSONB support and row-level security were decisive."
timestamp: 2026-03-01T00:00:00Z
tags: [infrastructure, database]
---
## ContextIn early 2026 we evaluated both options. MySQL's JSON support was insufficient for our metadata schema...## DecisionPostgres 16. See [datasets/primary-db.md](../datasets/primary-db.md) for schema docs.
Шаровы стакан памяці
Калі працюеце над стадзіяй «The Layered Memory Stack», спачатку запісайце умовы викорыстоўвання: неабходныя даны, сігнал успеху і тое, што выходзіць у разе частковага невыпання. Такі список дапамагае заліцвачыць змяны ў кодзе пазнейшаю часам. Запісвайце час выконання і кост токенаў або запытаў праза функцыйнае рэзультат. Відразлівасць костаў з самага пачатку запобегае неспакойным рахункам, калі працэс пераходзіць з дэмаверсіі ў спяльныя среды. Зробіце перапаконтаванне пасля дорогіх крокаў. Продовжэнне працы не павінна знову нарахоўваць косты за той самы вызов LLM, калі аператар прабуе зноў выконаць пазнейшы вузел.
+--------------------------------------------------+
| AGENT SESSION |
+--------------------------------------------------+
| CLAUDE.md / AGENTS.md |
| (behavioral rules - how agent acts) |
+--------------------------------------------------+
| OKF BUNDLE (.okf/) |
| (curated team knowledge - what we know) |
| - index.md: entry points per domain |
| - concepts/*.md: services, datasets, decisions |
| - log.md: change history |
+--------------------------------------------------+
| AUTO-MEMORY (memory.md) |
| (what the agent picked up implicitly) |
+--------------------------------------------------+
| MCP CONNECTIONS |
| (live tool access - what the agent can do) |
+--------------------------------------------------+
| SKILLS (.claude/skills/) |
| (reusable SOPs - how to do specific tasks) |
+--------------------------------------------------+
Што ўсё яшчэ не завершана
Калі працуеце на стадыі «Што ўсё яшчэ не завершана», спачатку запісайце умовы працы: неабходныя даны, сігнал успеху і тое, што выходзіць пад частковым невяскам. Такі список дапамагае заліцвачыць пазнейшыя змены ў кодзе. Зберагаюце настройкі паза кодам прыемліка. Файлы сераўнавання, хранільнікі секрэтных данных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куды аператары можаюць пераглядаць іх, не чытаяўшы весь ланцуг. Ствараюце контрольныя пункты пасля дорогіх крокаў. Система вярнення роботы не должна занова ставіць плату за той самы вызов LLM, калі аператар перапрыяўляе роботу да наступнага элемента. Калі працуеце на стадыі «Што ўсё яшчэ не завершана», спачатку запісайце умовы працы: неабходныя даны, сігнал успеху і тое, што выходзіць пад частковым невяскам. Такі список дапамагае заліцвачыць пазнейшыя змены ў кодзе. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі крок не выйшоў, прычына невяскі должна вказываць на адну конкрэтную адпаведальнасць, а не на заплутаны ланцуг задач.
Чаму гэта мае большое значэнне, чым здаецца
Этап «Прычыны, чаму гэта ў стадіі» працюе наяўней, калі яго спрыяваць як мерыемую паверхню. Запісайце адна ідеальная версія, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану, перш чым расширваць масштабы. Спрыявайце гэты стадію як кантракт межа вхіднымі дадзеннямі і перакананымі выходнымі рэзультатамі. Дайце назвы артыфактам, задаце критэрыя успеху і не падзеўляйцеся частым, непূরным выкананнем задач. Зберагайце стан графа ў простам і типаваным формате. Вярнутыя структуры дадзення маскуюць інфармацыю пра тое, який вузел запісаў кожны поле, і спакшуюць возз'яднанне пасля перарываў.
Чэк-ліст для эксплуатацыі
Калі працюеце над стадіяй чэк-ліста для эксплуатацыі, спачатку запісайце кантракт: неабходныя вхідныя даны, сігнал успеху і тое, што вядзець да частай неудачы. Гэты чэк-ліст дапамагае заставаць пазнейшыя змены коду чыстымі і працэсабельнымі.
Документавайце як шлях успеху, так і шлях вяснавання пасля неудач. Перапрыбуткі, людзкія контрольныя пункты і обработка некоректных поведэнняў є частью продукту, а не пазнейшым дапрацоўкам.
Пауза пасля дорогіх крокаў. Функцыя продакчу не павинна знова нараховваць плата за той самы вызыв LLM, калі аператар праказвае спробу на пазнейшый вузел.
Забезпечыце фіксацію версій залежнасцей і запісуйце хеш-значэнне зображэння, якое было викорыстана для дэманстраціі. Возможнасць перадзвычайнага запуску важлівей за традыцыйныя методы.
Вядзьмі праўерх маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выйшаў, прычына нехіткасці павинна быць адночыннаю, а не стосавацца цэлага складнага процесу.
Пауза пасля дорогіх крокаў. Функцыя продакчу не павинна знова нараховваць плата за той самы вызыв LLM, калі аператар праказвае спробу на пазнейшый вузел.
Перад апраноўкай стака заморозьце версіі, зафіксуйце ключовыя данні для критычнага маршруту і паказваце крокі для вярнення да пачатковага стану. У спільных средах неабходны ліміты на частоту вызывоў, перакананні ў правах на викорыстоўвання ресурсаў і чысткі власнік для змены секрэтных даных. Вядзьмі праўерх простую надзеянасць на стабільнасць замест крэатыўных, але разовых дэманстрацый.
Запіскі для пакета 7e96a33898ce: не класты ключі прадаўцоў у репазітарыю, задаць максымальны ліміт токена на сесію, а таксама зберагчы транскрыпціі празьле фіксатуў для ацэнкі, каб пазнейшыя замены моделяў заставаліся пораўнанымі.