Путь ИИ-инженера

Агент-агностик

При работе с разными агентами заметил, что у одного из них контекстное окно заполняется гораздо быстрее.

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

Нужная информация могла занимать несколько строк, но во втором случае вместе с ней в контекст попадало всё остальное содержимое файла. После нескольких таких чтений разница становилась заметной)

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

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

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

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

Что такое агент?

Обычно агент для разработки — это плагин для IDE, CLI или отдельная программа.
Внутри — промпты, инструменты и код, который связывает их с языковой моделью. Модель может работать локально или на сервере провайдера.

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

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

Например, просим исправить ошибку — агент находит код, вносит правки, запускает тесты и при необходимости исправляет ещё раз.

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

Виртуальная команда в одном скилле

Допустим, нам нужна виртуальная команда: Go-разработчик, React-разработчик, тестировщик, QA, аналитик.

Можно сделать один общий скилл «Виртуальная команда». В `SKILL.mdые инстр` оставить общие правила и условия выбора ролей, а подробнукции для каждого участника вынести в отдельные файлы — референсы.

Нужно изменить бэкенд — агент читает инструкцию Go-разработчика. Дошёл до тестов — инструкцию тестировщика. Остальные подгружает только по мере необходимости.

Так описания всей команды хранятся в одном скилле, а контекст не заполняется всеми инструкциями сразу)

Кто заменит программистов?
Многие программисты говорят: «Нас заменит ИИ».

Думаю, их заменит не ИИ, а другие программисты — те, кто научился его использовать.

Референсы для агентов

Допустим, у нас есть огромная документация по проекту. Архитектура, API, база данных, тесты, деплой. Если загружать её целиком в контекст агента, она займёт значительную его часть ещё до начала работы.
При этом для конкретной задачи большая часть этих сведений может вообще не понадобиться. Чтобы поменять кнопку в интерфейсе, вряд ли нужно читать подробную инструкцию по миграциям базы)

Такую документацию можно разбить на отдельные файлы. А в стартовом файле оставить общие правила и ссылки на нужные разделы — референсы.

Но рядом со ссылками важно написать, когда читать каждый файл. Например:
- references/api.md — прочитай перед добавлением или изменением API.
- references/database.md — прочитай перед изменением схемы базы или созданием миграций.
- references/testing.md — прочитай перед написанием и запуском тестов.
И явно указать: «Читай дополнительные файлы по мере необходимости для текущей задачи».
Если какой-то раздел тоже разросся, его можно разделить дальше: оставить в нём краткое описание и ссылки на более подробные инструкции с такими же условиями чтения.

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

Обновляйте свои скиллы!

Написать скилл один раз — только начало)
В реальной работе агент может упереться в то, чего в инструкции нет. Например, как правильно связать страницы в Wiki или загрузить файл и прикрепить его к странице.
Он разбирается, находит рабочий способ и выполняет задачу. Но если решение осталось только в текущем чате, в следующей сессии ему может понадобиться проходить тот же путь заново. Снова поиск, попытки, время и токены на уже решённую проблему.
Поэтому после такой задачи можно попросить:

«Если во время работы ты нашёл полезные детали, которых нет в скилле, допиши их туда. Сохрани проверенный способ, чтобы в следующей сессии не разбираться заново».

Например, добавить нужный формат ссылки, порядок загрузки файла или обязательный параметр запроса, без которого ничего не работало.

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

Зачем нужен скилл для доступа к Wiki
Агент может достать информацию из Wiki и без скилла) Сам изучит API, разберётся с авторизацией и нужными запросами — если у него есть необходимые инструменты и доступ.

Но на этот разбор уйдут время и токены. А в новой сессии, где этих сведений нет, придётся разбираться заново.

Скилл сохраняет проверенный способ работы с Wiki. Агент читает готовую инструкцию и использует её для своей задачи. Так мы сокращаем повторный поиск и траты токенов на уже решённую задачу.

Как не слить токен ИИ

Если API требует токен, его необязательно отдавать модели. Достаточно объяснить агенту, где он лежит и как его использовать.

Самостоятельно сохраняем в `~/.config/wiki.com/token` готовый заголовок со своим токеном:

Authorization: Bearer YOUR_TOKEN

В скилле пишем:

Не открывай файл с токеном для просмотра и не выводи его содержимое. Передавай заголовок в curl через `-H @файл` или `-H "$(cat "$HOME/.config/wiki.com/token")"`, только для запросов к `https://wiki.com`, без отладочного вывода.

И добавляем пример для условного API Wiki:

file="@$HOME/.config/wiki.com/token"
curl -q -fsS \
-H "$file" \
"https://wiki.com/api/pages"

`curl` сам прочитает заголовок из файла и отправит его серверу. Модели для этого не нужно видеть секрет.

Это помогает не засветить токен случайно. Но инструкция в скилле не запрещает агенту технически прочитать файл, если у него есть такой доступ.

А можно без MCP?

Конечно)
Допустим, вы хотите научить агента работать с условным порталом wiki.com: искать страницы, читать их и обновлять документацию. Для этого можно подготовить скилл.

Если у портала есть спецификация OpenAPI, отдайте её агенту. Или дайте ссылку на Swagger UI и попросите:

Сделай скилл для работы с этим порталом. Нужны поиск, чтение, создание и редактирование страниц

По описанию API агент сможет подготовить инструкции: какие запросы отправлять, какие параметры передавать, как устроена авторизация и в каком порядке выполнять действия. При необходимости — добавить скрипты для обращения к API.
А если Swagger нет?
Можно самим дать адреса нужных страниц и документации. Или попросить агента пройтись по ссылкам сайта, разобраться в доступной структуре и описать найденные способы работы в скилле. Если подходящего API нет, можно описать работу через браузер.

А сами запросы к API агент может отправлять с помощью curl — по инструкциям из скилла.

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

MCP: как дать агенту доступ к другим системам

Чтобы агент мог работать с внешней системой, один из вариантов — написать для неё MCP-сервер.

MCP — Model Context Protocol — задаёт общий протокол взаимодействия AI-приложений с внешними инструментами и данными. А MCP-сервер — это промежуточный сервис, который предоставляет возможности конкретной системы через этот протокол. Например, внутри он может обращаться к её API.

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

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

Например, мы просим: «Найди в Wiki инструкцию по запуску проекта и добавь туда новый шаг».
Агент может сначала вызвать поиск, затем прочитать найденную страницу и после этого отправить изменения через инструмент редактирования. Один наш запрос превращается в несколько действий в другой системе.