Практические замечания: Google незаметно выпустил нехватавый элемент для ИИ-агентов.
Пошаговое руководство по практическим заметкам: Google незаметно выпустил нехватавый элемент для ИИ-агентов — контракты, проверки и готовые блоки кода для команд, использующих эту модель.
Используйте это как переработанную версию идей из статьи «Google тихо выпустил недостающий элемент для ИИ-агентов. Его называют 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» необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рядом с функциональными результатами следует записывать время выполнения и стоимость токенов или запросов. Отображение затрат на раннем этапе предотвращает неожиданные счета при переходе с демо-среды в общедоступные среды. Для операций, связанных с расходами или изменением производственных данных, необходимо ввести утверждение человека. Настройка на этапе компиляции не гарантирует полноты решения с точки зрения бизнес-процессов.
Структура: каталог — это граф знаний
На этапе «Структура — каталог» необходимо определить входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, которое операторы могут проверять, не читая весь граф. Вводите утверждение человека для операций, связанных с тратой денег или изменением производственных данных. Подключение на этапе компиляции не гарантирует полноты бизнес-логики. На этапе «Структура — каталог» необходимо определить входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Предпочитайте небольшие, тестируемые единицы кода большим скриптам. При сбое шага он должен указывать на конкретную причину, а не на запутанную ситуацию.
пайплайн.
.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» сначала запишите условия соглашения: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список поможет сохранять честность при последующих изменениях кода. Рассматривайте этот этап как соглашение между входными данными и проверенными выходными результатами. Дайте названия элементам, определите критерии успешности и не допускайте безусловного частичного завершения работы. Выполняйте контрольные точки после дорогостоящих операций. Функция возобновления работы не должна повторно запрашивать тот же вызов большой языковой модели, когда оператор пытается выполнить следующий узел заново.
---
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]
Три принципа проектирования
При работе над этапом «Три принципа дизайна» сначала запишите условия работы: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой список помогает избегать ошибок при последующих изменениях кода. Рядом с результатами работы запишите время выполнения и стоимость токенов или запросов. Отображение затрат с самого начала предотвращает неожиданные расходы при переходе с демо-среды в общедоступные среды. Выполняйте контрольные точки после дорогостоящих операций. Система возмещения расходов не должна снова взимать плату за один и тот же вызов большой языковой модели, если оператор попытается выполнить последующий шаг заново.
1. Минимально предвзятый подход
При работе над этапом «1 Minimally opinionated» сначала запишите условия работы: необходимые входные данные, сигнал о успехе и действия при частичной неудаче. Такой список помогает сохранять честность последующих изменений в коде. Храните конфигурацию отдельно от кода приложения. Файлы с настройками, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Создавайте контрольные точки после дорогостоящих операций. Система возобновления работы не должна повторно оплачивать один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий шаг. При работе над этапом «1 Minimally opinionated» сначала запишите условия работы: необходимые входные данные, сигнал о успехе и действия при частичной неудаче. Такой список помогает сохранять честность последующих изменений в коде. Предпочитайте небольшие, тестируемые единицы кода большим скриптам. При сбое какого-либо шага причина неудачи должна указывать на конкретную ответственность, а не на запутанную структуру обработки данных.
2. Независимость производителя и потребителя
Этап производителя и потребителя работает наилучшим образом, когда рассматривается как измеримая структура. Соберите один идеальный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объёма работ. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия всем элементам, определите критерии успешного выполнения и не соглашайтесь на молчаливое частичное завершение работы. Сохраняйте структуру графа простой и типизированной. Вложенные структуры данных маскируют информацию о том, какой узел заполнил тот или иной поле, что приводит к нарушению возобновления работы после перерывов.
PRODUCERS CONSUMERS
--------- ---------
Human authors ----> AI agents
BigQuery pipelines ----> HTML visualizers
LLM-generated ----> Search indexes
Wiki exports ----> Other agents / tools
3. Формат, а не платформа
Формат «3 Format not platform stage» работает наилучшим образом, если рассматривать его как измеримую поверхность. Сначала зафиксируйте один успешный пример, один случай сбоя и записку о возврате к предыдущему состоянию, прежде чем расширять объем работы. Записывайте временные показатели, а также стоимость токенов или запросов рядом с функциональными результатами. Отслеживание затрат на раннем этапе предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Сохраняйте структуру графа простой и типизированной; вложенные структуры скрывают информацию о том, какой узел заполнил тот или иной поле, и могут нарушить возобновление работы после прерываний.
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» необходимо определить входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Предпочитайте небольшие, тестируемые единицы кода большим скриптам. При сбое шага он должен указывать на конкретную причину, а не на сложную структуру обработки данных.
Как начать
На этапе «Как начать» сначала запишите условия контракта: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой список поможет сохранять честность при последующих изменениях кода. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия элементам, определите критерии успеха и не допускайте безответственного частичного выполнения задачи. Выполняйте контрольные точки после дорогостоящих операций. Система возмещения расходов не должна снова взимать плату за один и тот же вызов большой языковой модели, если оператор попытается выполнить следующий шаг заново.
/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.
Многоуровневая стек-структура памяти
При работе над этапом «Многоуровневая стек-структура памяти» сначала запишите условия использования: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список поможет избежать ошибок при последующих изменениях кода. Рядом с функциональными результатами занесите информацию о времени выполнения и стоимости токенов или запросов. Отображение затрат с самого начала предотвращает неожиданные расходы при переходе с демо-среды в общедоступные среды. Выполняйте контрольные точки после дорогостоящих операций. Функция возобновления работы не должна снова взимать плату за один и тот же вызов большой языковой модели, если оператор попытается выполнить последующий узел заново.
+--------------------------------------------------+
| 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 при повторной попытке оператора обработки последующего узла.
Перед повышением уровня стека заморозьте версии, сохраните эталонный отчет для критической части работы и убедитесь в наличии шагов для возврата к предыдущему состоянию. В совместных средах необходимы ограничения на частоту запросов, проверки принадлежности ресурсов и четко определенный ответственный за обновление секретов. Лучше надежность, чем креативные одноразовые демонстрации.
Примечание к пакету 7e96a33898ce: не включайте ключи поставщиков в репозиторий, установите лимит токенов на сессию и храните транскрипции рядом с фиксами для оценки, чтобы последующие замены моделей оставались сопоставимыми.