--- title: "TeqFW: фреймворк, который объясняет себя ИИ-агенту" description: "Как пакеты TeqFW поставляют версионированные Agent Skills, чтобы ИИ-агент работал с инструкциями для установленного кода." date: 2026-08-10 --- ИИ-агент умеет читать исходный код. Поэтому незнакомую библиотеку он в конце концов поймёт: найдёт точку входа, просмотрит типы, сопоставит примеры, восстановит основные соглашения. Вопрос в том, сколько времени и контекста модели уйдёт на это исследование и к какой версии документации агент обратится по пути. В TeqFW я решаю эту проблему на уровне npm-пакетов. Вместе с кодом пакет поставляет навык с инструкциями для ИИ-агента: ``` text @teqfw/package/ ├── src/ ├── types.d.ts └── skills/ └── teqfw-package/ ├── SKILL.md └── references/ ``` После установки пакета агент может получить описание именно той версии компонента, которая находится в `node_modules`. ## Что находится в навыке [Agent Skills](https://agentskills.io/) — открытый формат инструкций для ИИ-агентов. Точка входа навыка — файл `SKILL.md`. В нём можно указать: - за что отвечает пакет; - когда агенту следует использовать этот навык; - как устроены публичные контракты; - как подключать компонент к приложению; - какие соглашения TeqFW нужно соблюдать; - что следует проверить в исходном коде и тестах текущей версии. Формат Agent Skills не привязан к Codex. Его поддерживают и другие агентские среды, хотя каталоги обнаружения и способы подключения у них различаются. Поэтому пакет TeqFW поставляет сам навык, а проект подключает его способом, принятым в выбранной среде. Claude Code следует тому же принципу через каталог `.claude/skills/`; сам пакет при этом не зависит от пути обнаружения, характерного для конкретного агента. Справочные материалы и примеры находятся рядом с `SKILL.md` и входят в тот же npm-пакет. Это не пересказ README для другого читателя. README помогает разработчику начать работу. Навык задаёт агенту маршрут по пакету: какие документы прочитать, какие границы не нарушать и на какие контракты опираться при изменении кода. ## Как это работает в TeqFW TeqFW состоит из отдельных пакетов. Собственные навыки поставляют платформенные компоненты: ``` text @teqfw/di → teqfw-di @teqfw/cfg → teqfw-cfg @teqfw/cli → teqfw-cli @teqfw/log → teqfw-log @teqfw/db → teqfw-db @teqfw/web → teqfw-web ``` Например, навык `teqfw-di` объясняет агенту модель связывания модулей и правила работы с контейнером зависимостей. `teqfw-cfg` описывает источники и жизненный цикл конфигурации. `teqfw-db` задаёт границы работы с распределённой моделью данных (DEM), SQL-диалектами, транзакциями и пересборкой базы. `teqfw-web` описывает серверный конвейер запросов и статические ресурсы. Эти знания относятся к конкретным пакетам. Навык не заменяет документацию проекта и не принимает за владельца архитектурные решения. Он объясняет, как корректно использовать установленный компонент внутри правил конкретного приложения. ## Версия знаний совпадает с версией кода Допустим, приложение использует пакет версии `2.4`, а агент находит в интернете документацию для `3.0` или вспоминает пример из более старой версии. Код может выглядеть правдоподобно и при этом не соответствовать установленному API. Когда навык входит в пакет, версия фиксируется целиком: ``` text package 2.4 ├── code 2.4 └── skill 2.4 ``` `package-lock.json` закрепляет версию зависимости. Вместе с ней он косвенно закрепляет и версию инструкций для агента. При обновлении пакета обновляется его навык. При возврате на предыдущую версию возвращаются соответствующие ей инструкции. Для агента источником становится не абстрактная «последняя документация», а содержимое реально установленной зависимости. ## Пакет предоставляет навык, проект его выбирает Установка и подключение навыка — разные действия. После `npm install` навык находится внутри пакета: ``` text node_modules/@teqfw/di/skills/teqfw-di ``` Но пакет не меняет конфигурацию проекта и не подключает себя автоматически. Проект явно открывает агенту доступ к нужному навыку. В Codex это можно сделать через символическую ссылку: ``` text .agents/skills/teqfw-di → ../../node_modules/@teqfw/di/skills/teqfw-di ``` Команды для подключения:
``` sourceCode mkdir -p .agents/skills ln -s \ ../../node_modules/@teqfw/di/skills/teqfw-di \ .agents/skills/teqfw-di ```
Ссылка может храниться в Git. Тогда репозиторий фиксирует, какие навыки разрешены в проекте, а lock-файл — из каких версий пакетов они получены. Это разделение особенно важно для приложения с большим деревом зависимостей. Наличие пакета в `node_modules` ещё не означает, что инструкции этого пакета должны занимать внимание агента. Владелец проекта сам формирует рабочий набор навыков. [Codex поддерживает навыки, подключённые через символические ссылки](https://developers.openai.com/codex/build-skills), поэтому копировать их в проект не требуется. Единственный экземпляр остаётся внутри установленного пакета. ## Зачем это нужно разработчику Навык сокращает исследовательскую работу перед изменением кода. Агент получает от автора пакета ответы на вопросы, которые иначе восстанавливал бы самостоятельно: - где проходит публичная граница компонента; - какие соглашения обязательны; - какие решения относятся к пакету, а какие остаются за приложением; - какие устаревшие механизмы нельзя переносить в новый код; - чем проверить результат. Это не гарантирует правильный результат. Агент всё равно должен читать текущие контракты и тесты, а разработчик — оценивать изменения. Но стартовая точка становится воспроизводимой: два агента, работающие с одной версией зависимости, получают одни и те же инструкции от её автора. Для меня это одна из практических сторон агентской разработки. Недостаточно подключить сильную модель к репозиторию. Нужно подготовить программную среду так, чтобы агент мог быстро находить локальные правила и отличать их от общих знаний о JavaScript и Node.js. ## TeqFW как среда для агентской разработки TeqFW изначально строится вокруг явных зависимостей, модульных границ и контрактов, доступных средствам анализа кода. Навыки внутри пакетов добавляют к этому ещё один слой: описание компонента для ИИ-агента. У одного пакета появляются разные представления для разных участников разработки: ``` text исходный код → исполняемая среда JSDoc и types.d.ts → IDE и статический анализ README → разработчик SKILL.md → ИИ-агент ``` Все они выпускаются вместе и относятся к одной версии компонента. Так я развиваю не только набор JavaScript-библиотек, но и рабочую среду, в которой ИИ-агенту заранее объяснены правила обращения с ними. Эту же работу я выполняю при подготовке других пакетов и приложений к агентской разработке: выделяю границы, формализую соглашения, создаю навыки и связываю их с версиями программных компонентов. Рабочее название подхода — **Dependency-bound Agent Skills**, навыки агентов, связанные с программными зависимостями. Это не отдельный стандарт, а схема распространения: код и знания о работе с ним доставляются одним менеджером пакетов и версионируются вместе. Подобная схема обсуждается и за пределами TeqFW. В репозитории Agent Skills есть [предложение о распространении навыков через npm-пакеты](https://github.com/agentskills/agentskills/issues/81), а проект [skills-npm](https://github.com/antfu/skills-npm) исследует обнаружение навыков внутри установленных зависимостей. В TeqFW этот подход уже используется. Пакеты поставляют инструкции, приложение выбирает нужные навыки, а агент работает со знаниями, соответствующими установленному коду. ------------------------------------------------------------------------ ### Ссылки - [Agent Skills](https://agentskills.io/) - [Agent Skills Specification](https://agentskills.io/specification) - [OpenAI Codex: Agent Skills](https://developers.openai.com/codex/build-skills) - [RFC: Standardize npm/JavaScript Package Distribution](https://github.com/agentskills/agentskills/issues/81) - [npm-based Agent Skills Convention](https://github.com/antfu/skills-npm/blob/main/PROPOSAL.md) - [skills-npm](https://github.com/antfu/skills-npm)