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

VasilevNStas1 час назадОбъяснить с

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

Время на прочтение6 минОхват и читатели2.1KУправление разработкой*Искусственный интеллектМнениеИз песочницыЗдравствуйте дамы и господа. Меня зовут Васильев Стас и я, как многие участники этого прекрасного сообщества, пытаюсь научится эффективному использованию 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‑Агентом. В следующих статьях я подробнее расскажу что находится в том или ином файле шаблона.

Спасибо за внимание.

С уважением,Васильев СтасТеги:• OKF
• Opencode
• knowledge bundle
• AGENTS.mdХабы:• Управление разработкой
• Искусственный интеллект