Обвязку для агента сейчас собирают многие. Насмотрелся шортсов, накидал скиллов, подключил MCP, и вот ты весь обвязанный. Моя прошла эту стадию год назад и с тех пор обросла инструментами, проверками и базой знаний. Работала она безотказно, пока пользователь был один. Стоило отдать её коллегам, и она сломалась. Главной её частью оказался автор, а автора через установщик не поставишь.

Дальше пять шагов о том, как убрать автора из схемы. Что-то ушло в код, что-то в инструкции, а где-то пришлось сесть рядом с коллегой.
Часть решений уже работает, часть ещё дорабатываю. Это мой опыт, а не инструкция по построению AI-команды.

Если термины «скилл» и MCP пока незнакомы, начать можно со статьи «Tools, Hooks, Skills, MCP — что есть что?».

🛠️ Шаг 1. Создать личную обвязку

Сначала коротко о том, что именно я передавал и для чего.

Я работаю в компании Directum и отвечаю за продвижение платформы Directum RX. Ко мне приходят требования заказчиков, и мне нужно быстро показать на рабочем прототипе, как их реализовать на платформе. Если коротко, Directum RX — цифровая платформа для управления компанией, на которой построена экосистема продуктов и решений. В ней ведут документы, задачи и бизнес-процессы, от делопроизводства и договоров до кадровых процессов и проектов. Готовые модули можно дорабатывать под себя. Типовые вещи аналитик настраивает без кода, а когда настроек не хватает, разработчик в Development Studio пишет логику на C# поверх объектной модели.

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

Элементы решения создаёт Development Studio (DS), среда разработки Directum RX. У неё есть JSON-RPC API, и я подключил его к Claude Code через MCP. Агент создаёт через него сущности, свойства и заготовки методов тем же механизмом, что и разработчик через окно среды, а потом дописывает прикладную логику.

Инструменты обвязки проверяют код и собирают пакет. Дальше в дело идёт штатный Deployment Tool (DTC). Это утилита командной строки, которой разработчики публикуют пакеты на стенд, инициализируют модули и переносят настройки между стендами. Агенты вызывают её так же, как человек, а потом проверяют результат на стенде через API и веб-интерфейс.

Роли и знания

Крупную задачу я делю между субагентами. Состав зависит от задачи, но основные роли такие:

• Product owner готовит документ требований (PRD) и критерии приёмки.

• Архитектор определяет устройство решения, связи между его частями и технические ограничения. Объясняет, почему выбрал этот подход и какие альтернативы рассматривал.

• Разработчик меняет файлы проекта и добавляет тесты бизнес-логики.

• Тестировщик проверяет сценарии и связывает результаты с критериями приёмки.

• Ревьюеры проверяют код, безопасность и соответствие архитектуре.

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

База знаний — Markdown-файлы в репозитории. Индекс подсказывает агенту, какие правила и примеры загрузить под роль и задачу, а по ссылкам он переходит к нужному разделу справки или примеру в коде. Для поиска по коду использую open-source инструмент Graphify. Он строит локальный граф зависимостей, и агент видит, что затронет изменение.

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

От задачи к результату

Я использую spec-driven подход. Сначала пишем спеку, где зафиксированы результаты, критерии приёмки и сценарии проверок, и только потом пишем код.

Для большой задачи эти этапы собраны в пайплайн. Агент-координатор запускает субагентов по этапам и передаёт каждому нужные документы. Артефакты этапов лежат рядом с проектом:

.pipeline/
├── 00-prd/               требования и критерии приёмки
├── 01-research/          факты о платформе под задачу 
├── 02-design/            проект решения
├── 03-plan/              план реализации и проверки
├── 04-implementation/    результаты тестов и ревью
└── 05-final-review/      итоговый отчёт

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

Проверить, исправить, повторить

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

Возвратами управляет координатор. Ошибка в коде уходит субагенту-разработчику, ошибка в проекте решения — субагенту-архитектору, а после исправления координатор запускает проверку снова. Человеку не приходится быть мясным прокси между субагентами. У каждого цикла лимит в три попытки. Если и третья не прошла, координатор зовёт человека, а обвязка сохраняет описание бага, результаты проверок и историю попыток. Как разбираем такие обращения — в разделе про обратную связь. Без лимита субагенты могут долго и увлечённо исправлять друг друга, сжигая лимиты подписки.

Человек в этой схеме появляется там, где нужно решение. Он согласует PRD до начала работы. Если по ходу выясняется, что менять надо сами требования, работу останавливаем и возвращаемся к PRD. Его зовут, когда цикл исчерпал три попытки. И он же принимает итог. Финальный ревьюер, ещё один субагент, сводит отчёты и независимо проверяет критерии приёмки, причём блокер по безопасности нельзя перекрыть хорошей оценкой кода. Спорные замечания и окончательное решение остаются за человеком.

Дальше — о совместном использовании обвязки.

🤝 Шаг 2. Организовать совместную работу

Я рассматривал два варианта передачи обвязки коллегам.

Расскажу сначала про песочницы, хоть и выбрал другой вариант. На сервере разворачивается сервис, который запускает агентов в изолированных средах (например, GoClaw или OpenHands). Подключаются к нему инструменты и готовятся песочницы для команд, где уже стоит нужная версия платформы, подключены инструменты и настроены проверки. Человек выполняет задачу, проверяет результат и переносит изменения в свой репозиторий. Для команды с одним продуктом и согласованным окружением так можно подготовить всё заранее.

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

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

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

Где хранится обвязка

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

Общее, проектное и личное хранятся раздельно:

• Общие исправления и правила попадают в репозиторий обвязки.

• Требования проекта хранятся рядом с его кодом.

• Персональные настройки и доступы остаются локально и не попадают в Git.

С путями тоже пришлось разобраться. Пока обвязкой пользовался я один, в скриптах и инструкциях были захардкожены пути с моей машины. Теперь свои файлы обвязка ищет относительно корня репозитория, куда бы его ни склонировали. А пути к внешним программам, таким как Development Studio или Deployment Tool, установщик берёт из конфига, который появляется после установки самой системы. Раскладывать их по тем же папкам, что у меня, никому не нужно.

Доставка обновлений

Когда я исправляю общую ошибку, все должны получить исправление без повторной ручной настройки. Для этого есть хук Claude Code — скрипт, который запускается при старте сессии. Он замечает новую версию, предлагает подтянуть изменения, обновляет зависимости и проверяет, что инструменты запускаются. Обновление сохраняет локальные настройки, показывает конфликты с доработками и позволяет откатиться на предыдущую версию.

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

🚀 Шаг 3. Подготовить запуск у коллег

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

Сначала с настройкой помогал сам агент. Он находил недостающие пакеты и чинил подключения к MCP. Бывало, что на эту подготовку уходил весь лимит пятичасового окна Claude. Инструмент ещё не принёс пользы, а перерыв уже понадобился.

Установка и первый запуск

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

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

• От операционной системы зависят команды запуска, пути и установка зависимостей.

• От СУБД зависят настройки подключения и набор инструментов обвязки. Платформа работает и с PostgreSQL, и с MSSQL, а вот мои утилиты, завязанные на psql, на MSSQL недоступны, и установщик об этом предупреждает.

• От версии платформы зависят доступные API и инструменты.

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

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

Инструмент может работать в терминале и при этом быть недоступным агенту. Поэтому проверяем его из Claude Code, которым и будет пользоваться человек. А поскольку Bash под антивирусом на Windows запускался нестабильно, точки входа скриптов я перенёс на Node.js.

Доработки и проверка изменений

Адреса стендов, доступы и настройки проектов остаются локальными, но общие инструменты, правила и скиллы команды могут дорабатывать. Кроме merge-конфликтов нужно проверять, как доработка повлияла на поведение агента.

Здесь помогают evals, проверочные сценарии с заранее заданными критериями успеха. После изменения скилла прогоняем их и смотрим, сохранилась ли его основная функция. Скажем, кто-то доработал базовый скилл под свой проект, а тот перестал выполнять обязательную проверку перед завершением задачи. Такой сценарий покажет регрессию. Evals охватывают только описанные в них случаи и не гарантируют правильную работу на любых запросах, зато команды могут менять обвязку под себя и видеть последствия.

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

🔒 Шаг 4. Настроить безопасность

Следом нужно защитить стенды и данные от тех, кто первым делом включает bypassPermissions. Иногда и сам так делаю — кто из нас без греха.

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

Защита данных

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

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

Контроль действий агента

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

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

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

• доступы к стендам разделены, и перед операцией записи проверяется, на какой стенд она идёт;

• файлы с секретами закрыты от агента;

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

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

🎓 Шаг 5. Помочь коллегам освоить обвязку

Знакомство с агентом

Установка, обновления и защита работают, пусть и с доработками. Пора знакомить людей с агентом. Что тут может пойти не так?

Это как знакомить между собой двух своих приятелей. С каждым по отдельности тебе классно, общих тем полно. Но стоит свести их за одним столом — один несёт пургу, второй зажимается и молчит. А в голове крутится: «Вы кто вообще? Почему я раньше этого не замечал?»

С агентом похоже. Знаешь, какие задачи он вытягивает. Знаешь коллегу, с которым вы эти задачи раньше решали вручную. Кажется, сейчас случится мэтч. Но коллега формулирует вопрос непривычно, агент выдаёт что-то странное, и в ответ доносится: «Шляпа весь этот ваш AI».

Чтобы знакомство состоялось, приходится показывать человеку возможности агента и дополнять обвязку контекстом его задач. А ещё у всех разный настрой. Кто-то уже пробовал агентов и больше исправлял, чем экономил время. Кто-то беспокоится о безопасности. А у кого-то привычный способ и так работает, и «попробовать AI» звучит как ещё одна задача на неделю.

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

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

Обратная связь

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

Обращение тоже может потеряться. Токену не дали прав создавать issues, он протух или его вообще никто не создавал. Агент подготовил описание, попытался отправить и бодро сообщил, что проблема передана. А в GitLab пусто.

Поэтому подтверждением считаются только номер и ссылка на созданную issue. Если отправка не удалась, описание сохраняется локально, а человек видит причину сбоя. Секреты и лишние данные проекта в обращение не попадают.

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

Через issues приходят и предложения с вопросами. Пишущему не обязательно заранее понимать, сломан инструмент или непонятно написана инструкция, — это уже задача автора обвязки.

🎯 Итоги

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

Вот что сработало:

• Проверять установку на чистой машине до того, как её увидит первый коллега.

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

• Закреплять запреты правами и проверками, не полагаясь только на инструкции агенту.

• Считать обращение доставленным только по номеру issue, а не по словам агента.

• Показывать агента на знакомой человеку задаче, иначе знакомство не состоится.

Путь от задачи до прототипа стал короче и у коллег. Но то, как поставить задачу и где не верить агенту, пока приходится объяснять лично.

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