Наборы знаний для AI‑агентов: от AGENTS.md к структурированному контексту

Здравствуйте дамы и господа. Меня зовут Васильев Стас и я, как многие участники этого прекрасного сообщества, пытаюсь научится эффективному использованию LLM и AI‑Агентов в разработке.

С моей стороны будет этично сказать, что данный материал был написан в соавторстве с LLM. Кто, если не LLM, знает и понимает как лучше с ней разговаривать и работать. Я рассматриваю работу разработчика и AI‑агента не как замену одного другим, а как симбиоз: человек задаёт направление, опыт и ответственность, а агент расширяет возможности разработчика

В 2026 году возможности Больших Языковых Моделей достигли таких вершин, что окружающий их контекст при разработке перестал в полной мере им соответствовать, либо он очень быстро замусоривался и качество работы начинало сильно проседать. Тогда группа инженеров из Google Cloud 12 июня 2026 года анонсировала открытый формат Open Knowledge Format (OKF), в котором они предложили Миру концепцию LLM‑wiki:

Knowledge bundle (набор знаний) — каталог Markdown‑документов с YAML frontmatter, где в начале каждого файла прописан краткий блок метаданных в формате YAML, содержащий структурированный контекст, необходимый агенту для работы с проектом.

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

Пакет документов OKF — это:

• Простое форматирование — читается в любом редакторе, отображается на GitHub, индексируется любым поисковым инструментом;

• Только файлы — можно отправить в виде архива, разместить в любом репозитории git, подключить к любой файловой системе;

• Только преамбула YAML — для небольшого набора структурированных полей, которые должны быть доступны для запросов: type, title, description, resource, tags и timestamp;

24 июля 2026 года эта же группа инженеров предлагает обновление этого формата OKF v0.2 tackles agentic trust. В OKF v0.2 появились механизмы, позволяющие агенту учитывать происхождение, подтверждение и актуальность знания при его использовании. Это не устраняет галлюцинации само по себе, но даёт агенту дополнительные сигналы, по которым он может оценивать источник.

Были добавлены новые необязательные поля в YAML:

• Provenance (происхождение) — откуда взяты данные;

• Trust (доверие) — кто создал и кто проверил информацию (человек или алгоритм);

• Lifecycle & Freshness (жизненный цикл и актуальность) — статус документа и дата, после которой знания считаются устаревшими;

• Attestation / Attested computations — было ли вычисление выполнено тем способом, которым заявлено;

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

Я решил собрать для себя небольшой шаблон по методике Open Knowledge Format в надежде держать свои проекты в чистоте и чтобы пар от сжигания токенов не только в гудок уходил, но и работа шла качественнее, продуктивнее. В моём текущем варианте часть возможностей v0.2 я практически не использую, но дальнейшее погружение в эту спецификацию, я надеюсь, мне позволит применить эти идеи.

В своей работе я использую Opencode. Я пробовал разных Агентов, но остановился на этом. И мой шаблон ориентируется в первую очередь на требования Opencode, но доработать их под любого другого Агента не составит большого труда. Со временем я планирую сам сделать шаблоны максимально универсальными.

Один из главных плюсов такого подхода к работе с Агентами это чёткая структура хранения информации и Lazy‑loaded. Вы не храните всё в памяти, вы получаете ту или иную информацию/данные именно тогда, когда вам это необходимо. У Google в самом описании OKF прямо присутствует идея progressive disclosure: агент или человек получает возможность двигаться по дереву знаний постепенно, не загружая весь bundle в контекст. Ну и сам факт того, что информация по проекту где‑то структурировано записана это половина успеха.

Из чего всё это состоит:

• AGENTS.md — точка входа, минимальное описание проекта и рабочий процесс; это не база знаний, это маршрутизатор по базе знаний;

• _*.md — тематические справочные файлы (architecture, setup, CI, codestyle, security, testing, API, performance, release и многое другое) — загружаются по запросу;

• рабочие директории — issue/, playbook/, pr/, analysis/, runbooks/, archive/

В результате такого подхода мы имеем, вместо одного файла AGENTS.md на 500 строк, сфокусированное ядро на ~60 строк и более 25 тематических файлов, которые предполагается загружать только при необходимости.

Я попробовал применить эту идею на практике и собрать отдельный knowledge bundle для Opencode. Его задача — не заменить документацию проекта, а дать агенту структурированную карту проекта и набор специализированных знаний, которые можно получать по мере необходимости.

root-project/
├
└── .opencode/ ← what gets copied into projects
├── AGENTS.md ← entry point, project context + workflow
├── SPEC_REFERENCE.md ← OKF v0.2 spec extract with trust signals
├── index.md ← bundle table of contents (no frontmatter per OKF v0.2)
├── log.md ← change history pointer
├── WORK_LOG.md ← chronological work sessions
├── _concepts.md ← architecture, patterns, data flow
├── _setup.md ← get the project running locally
├── _env.md ← deployment environments map
├── _codestyle.md ← linting, conventions, SPDX headers
├── _commands.md ← build/test/run command reference
├── _files.md ← key files navigation guide
├── _glossary.md ← domain-specific terms
├── _security.md ← secrets handling, vulnerability reporting (with sources)
├── _troubleshooting.md← local (non-CI) problem diagnostics
├── _decisions.md ← ADR log for significant choices
├── _backlog.md ← future work, tech debt, ideas
├── _worklog.md ← work log entry format rules
├── _templates.md ← issue/pr/playbook templates (v0.2 compatible)
├── _ci.md ← CI workflows and failure patterns
├── _meta.md ← bundle organization and template version
├── _testing.md ← testing strategy, fixtures, mocking (with sources)
├── _api.md ← endpoints, auth, CLI commands, versioning
├── _release.md ← versioning, changelog, rollback procedures
├── _performance.md ← profiling, benchmarks, SLA/SLO targets (with sources)
├── analysis/
│ ├── index.md ← analysis findings index (draft)
│ └── _finding.md ← individual finding template
└── runbooks/
├── index.md ← incident response index (draft)
└── _runbook.md ← single runbook template
Подкаталоги содержат создаваемые в процессе работы находки/открытия: issue/, playbook/, pr/, archive/

Ключевые принципы:

• Ленивая загрузка (Lazy‑loaded) AGENTS.md — это оглавление, а не энциклопедия: агент считывает тематические файлы только при необходимости;

• Локальный файл .opencode/ - я предпочитаю держать этот bundle отдельно от исходного кода проекта, чтобы знания агента и производственный репозиторий имели независимый жизненный цикл, но ни что не запрещает его хранить в Git наравне с кодом проекта;

• Соответствие требованиям OKF v0.2: удобный Markdown + YAML frontmatter с достоверными признаками (trust signals) (generated, status, sources);

• Доступно всем. Если вы можете просмотреть содержимое файла, значит, вы можете читать OKF; если вы можете выполнить git clone, значит, вы можете распространять его

• Не требует дополнительных инструментов. Не требует сборки, не требует центрального реестра. Потребители могут добавлять валидаторы, но это необязательно;

Данная статья является попыткой поделиться с уважаемой общественностью своим небольшим опытом работы с AI‑Агентом. В следующих статьях я подробнее расскажу что находится в том или ином файле шаблона.