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

Зачем нужен скилл для доступа к 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 инструкцию по запуску проекта и добавь туда новый шаг».
Агент может сначала вызвать поиск, затем прочитать найденную страницу и после этого отправить изменения через инструмент редактирования. Один наш запрос превращается в несколько действий в другой системе.

Код-ревью в пайплайне

Конечно, захотелось автоматизировать всё. И мы это сделали)

Начали с автоматизации код-ревью в пайплайне. Это работало на локальных моделях, и качество в целом было приемлемым.

У такого ревью есть ограничение: бот видит только дифф. Ему сложно судить о проекте в целом, когда за пределами изменений остаются бизнес-логика, связи между компонентами и проверки в других местах.

При этом он подсвечивает вещи, которые легко упустить глазом. Например, переполнение. Вот короткий пример на Go:

timeoutMs := int32(3000)
timeout := time.Duration(timeoutMs * 1_000_000)

Ожидаем таймаут в три секунды, а получаем отрицательную длительность: `-1.294967296s`. Умножение выполняется в `int32`, и результат в этот тип уже не помещается. Приведение к `time.Duration` происходит после переполнения.

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

ub-mode — скилл от Uncle Bob
Решил поделиться находкой: ub-mode от Uncle Bob — набор инженерных правил для AI-агентов, оформленный как скилл. Сам пока не пробовал его в работе.

Внутри собраны правила для разных сторон работы с кодом:

- Архитектура: продумывать модель данных и границы системы, использовать типы, чтобы исключать недопустимые состояния.
- Разработка: делать минимальные изменения, использовать TDD и рефакторинг, убирать лишнюю сложность и исправлять причины ошибок.
- Проверка качества: тестировать поведение программы, контролировать сложность функций и дублирование кода.
- Рабочий процесс: двигаться небольшими проверяемыми шагами, вести журнал действий и следить за контекстом агента.
Для проверки результата в скилле указаны конкретные инструменты: Crapper оценивает сложность и покрытие тестами, Dryer ищет структурные дубликаты, а Mutator проверяет, ловят ли тесты специально внесённые изменения в код.

От rules к skills
Поначалу я записывал все инструкции для агента в rules. Как писать код, как организовывать проект, каких подходов придерживаться.
В моей тогдашней настройке все эти правила загружались в контекст при каждом запросе.

И меня это устраивало. Я писал промпты, агент писал код. Правила были про написание кода, поэтому нужны были практически в каждой задаче)

Сейчас у нас в команде десятки скиллов: написание кода, подготовка контрактов, ресерч по документации, создание задач и так далее.

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

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

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

Проблема контекста

В контексте агента накапливаются наши сообщения, ответы модели, код и результаты работы инструментов. Часть этих данных со временем становится лишней.
У контекстного окна есть предел. Поэтому в длинных сессиях может использоваться сжатие контекста — compaction: историю заменяют более компактным представлением, сохраняя важное для продолжения работы.

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

Кэширование может снизить затраты на обработку истории, но место в контекстном окне не освобождает.

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

Как устроен агент

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

Например, мы просим исправить ошибку в коде. Программа передаёт модели задачу, инструкции и описание доступных инструментов. Модель выбирает следующий шаг — допустим, прочитать файл — и формирует вызов инструмента.

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

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

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

То есть мы пишем короткое «да, продолжай», а рядом с ним в контексте уже могут быть десятки сообщений, куски кода и логи)

Одна опечатка может перевернуть всё

В прошлом посте я писал о том, что важные детали задачи могут остаться у меня в голове и не попасть к ИИ.
А иногда достаточно одной опечатки, чтобы смысл стал противоположным)

Однажды я написал «ну активити» вместо «не активити».

Всего одна буква — и отрицание исчезло. Как вы понимаете, получил противоположный результат.

У меня в голове всё ещё было «не активити». А модель получила совсем другой текст.

Поэтому мало сформулировать задачу. Нужно ещё перечитать то, что отправляешь, и проверить, совпал ли результат с тем, что ты хотел получить.

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