TeqFW: фреймворк, который объясняет себя ИИ-агенту

Дата публикации: 2026-08-10

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

Вопрос в том, сколько времени и контекста модели уйдёт на это исследование и к какой версии документации агент обратится по пути.

В TeqFW я решаю эту проблему на уровне npm-пакетов. Вместе с кодом пакет поставляет навык с инструкциями для ИИ-агента:

@teqfw/package/
├── src/
├── types.d.ts
└── skills/
    └── teqfw-package/
        ├── SKILL.md
        └── references/

После установки пакета агент может получить описание именно той версии компонента, которая находится в node_modules.

Что находится в навыке

Agent Skills — открытый формат инструкций для ИИ-агентов. Точка входа навыка — файл SKILL.md. В нём можно указать:

за что отвечает пакет;
когда агенту следует использовать этот навык;
как устроены публичные контракты;
как подключать компонент к приложению;
какие соглашения TeqFW нужно соблюдать;
что следует проверить в исходном коде и тестах текущей версии.

Формат Agent Skills не привязан к Codex. Его поддерживают и другие агентские среды, хотя каталоги обнаружения и способы подключения у них различаются. Поэтому пакет TeqFW поставляет сам навык, а проект подключает его способом, принятым в выбранной среде.

Claude Code следует тому же принципу через каталог .claude/skills/; сам пакет при этом не зависит от пути обнаружения, характерного для конкретного агента.

Справочные материалы и примеры находятся рядом с SKILL.md и входят в тот же npm-пакет.

Это не пересказ README для другого читателя. README помогает разработчику начать работу. Навык задаёт агенту маршрут по пакету: какие документы прочитать, какие границы не нарушать и на какие контракты опираться при изменении кода.

Как это работает в TeqFW

TeqFW состоит из отдельных пакетов. Собственные навыки поставляют платформенные компоненты:

@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.

Когда навык входит в пакет, версия фиксируется целиком:

package 2.4
├── code 2.4
└── skill 2.4

package-lock.json закрепляет версию зависимости. Вместе с ней он косвенно закрепляет и версию инструкций для агента.

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

Пакет предоставляет навык, проект его выбирает

Установка и подключение навыка — разные действия.

После npm install навык находится внутри пакета:

node_modules/@teqfw/di/skills/teqfw-di

Но пакет не меняет конфигурацию проекта и не подключает себя автоматически. Проект явно открывает агенту доступ к нужному навыку. В Codex это можно сделать через символическую ссылку:

.agents/skills/teqfw-di
    → ../../node_modules/@teqfw/di/skills/teqfw-di

Команды для подключения:

mkdir -p .agents/skills

ln -s \
  ../../node_modules/@teqfw/di/skills/teqfw-di \
  .agents/skills/teqfw-di

Ссылка может храниться в Git. Тогда репозиторий фиксирует, какие навыки разрешены в проекте, а lock-файл — из каких версий пакетов они получены.

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

Codex поддерживает навыки, подключённые через символические ссылки, поэтому копировать их в проект не требуется. Единственный экземпляр остаётся внутри установленного пакета.

Зачем это нужно разработчику

Навык сокращает исследовательскую работу перед изменением кода. Агент получает от автора пакета ответы на вопросы, которые иначе восстанавливал бы самостоятельно:

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

Это не гарантирует правильный результат. Агент всё равно должен читать текущие контракты и тесты, а разработчик — оценивать изменения. Но стартовая точка становится воспроизводимой: два агента, работающие с одной версией зависимости, получают одни и те же инструкции от её автора.

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

TeqFW как среда для агентской разработки

TeqFW изначально строится вокруг явных зависимостей, модульных границ и контрактов, доступных средствам анализа кода. Навыки внутри пакетов добавляют к этому ещё один слой: описание компонента для ИИ-агента.

У одного пакета появляются разные представления для разных участников разработки:

исходный код       → исполняемая среда
JSDoc и types.d.ts → IDE и статический анализ
README             → разработчик
SKILL.md            → ИИ-агент

Все они выпускаются вместе и относятся к одной версии компонента.

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

Рабочее название подхода — Dependency-bound Agent Skills, навыки агентов, связанные с программными зависимостями. Это не отдельный стандарт, а схема распространения: код и знания о работе с ним доставляются одним менеджером пакетов и версионируются вместе.

Подобная схема обсуждается и за пределами TeqFW. В репозитории Agent Skills есть предложение о распространении навыков через npm-пакеты, а проект skills-npm исследует обнаружение навыков внутри установленных зависимостей.

В TeqFW этот подход уже используется. Пакеты поставляют инструкции, приложение выбирает нужные навыки, а агент работает со знаниями, соответствующими установленному коду.