Практические заметки: 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).

Агенты могущественны, но они всё равно не знают, как работает ваш продукт

При работе с агентами сначала запишите условия контракта: необходимые входные данные, сигнал успешного выполнения и что происходит при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. Если какой-то шаг не сработает, причина неудачи должна указывать на конкретную ответственность, а не на запутанную цепочку операций. Выполняйте контрольные точки после дорогостоящих шагов. Система возмещения расходов не должна снова взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий этап.

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?

На этапе определения проблемы сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и что происходит при частичной неудаче. Такой чек-лист помогает сохранять честность при последующих изменениях кода. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. Когда какой-то шаг не срабатывает, причина неудачи должна указывать на конкретную ответственность, а не на запутанную цепочку операций. Выполняйте контрольные проверки после дорогостоящих шагов. Механизм возобновления работы не должен повторно взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий этап.

Чек-лист операций

Этап чек-листа операций работает наилучшим образом, если рассматривать его как измеримую основу. Соберите один идеальный пример выполнения, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ.

Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь граф.

Сохраняйте состояние графа простым и типизированным. Вложенные структуры данных скрывают информацию о том, какой узел записал какое поле, и мешают возобновлению работы после прерываний.

При наличии бюджета добавляйте тесты для проверки критического пути в процессе CI с использованием фикстчеров, а не реальных платных API.

Документируйте как успешный, так и восстановительный пути работы. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не последующими улучшениями.

Сохраняйте состояние графа простым и типизированным. Вложенные структуры данных скрывают информацию о том, какой узел записал какое поле, и мешают возобновлению работы после прерываний.

Перед внедрением стека заморозьте версии, сделайте «золотой» отчет для критического пути и уточните шаги отката. В совместных средах необходимы ограничения по частоте запросов, проверки принадлежности и четко определенный ответственный за обновление секретов. Лучше выбирать надежность, даже если она кажется скучной, чем умные одноразовые демонстрации.

Примечание для 758c51495df5: не храните ключи поставщика в репозитории, установите лимит токенов на сессию и сохраняйте отчеты рядом с фикстурами для оценки, чтобы последующие замены моделей оставались сопоставимыми.

Примечание по усилению безопасности для этапа 0 наиболее эффективно, когда его рассматривают как измеримую поверхность. Сделайте один «золотой» отчет, один пример сбоя и запись шагов отката перед расширением объема работ. Записывайте время выполнения, стоимость токенов или запросов рядом с функциональными результатами. Отслеживание затрат на раннем этапе предотвращает неожиданные счета при переходе от демо-среды к совместным средам.

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

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

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

При работе над вторым этапом записки по усилению безопасности сначала запишите контракт: необходимые входные данные, сигнал о успехе и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Рассматривайте этот этап как контракт между входными данными и проверенными выходными данными. Дайте названия результатам работы, определите критерии успеха и не допускайте молчаливого частичного выполнения задач.

Подробности усиления безопасности 2/782: измерьте время выполнения, класс ошибки и расход токенов для данной записки, затем решите, следует ли сохранять изменение на основе фиксированного набора критериев, а не на основе единичных примеров.

Второй этап записки по усилению безопасности работает наилучшим образом, когда его рассматривают как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, которое операторы могут проверять, не читая весь код.

Подробности усиления безопасности 3/782: измерьте время выполнения, класс ошибки и количество потраченных токенов для этой записи, затем решите, следует ли сохранить изменения на основе фиксированного набора вопросов, а не на основе единичных примеров.

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

Подробности усиления безопасности 4/782: измерьте время выполнения, класс ошибки и количество потраченных токенов для этой записи, затем решите, следует ли сохранить изменения на основе фиксированного набора вопросов, а не на основе единичных примеров.