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

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

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

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

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

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

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

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

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

При этом он подсвечивает вещи, которые легко упустить глазом. Например, переполнение. Вот короткий пример на 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. Как писать код, как организовывать проект, каких подходов придерживаться.
В моей тогдашней настройке все эти правила загружались в контекст при каждом запросе.

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

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

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

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

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