Интенсив 21–22.11 · БесплатноБесплатный 2-дневный интенсив по вайбкодингу 21–22 ноября в 16:00 МСК (Сб–Вс) · Живой Поток 3 стартует 23.11Записаться бесплатно →Поток 3 (23.11)
РелизКод / SDK · В работуHabr AI→ оригинал

Обвязка Claude Code работала у одного, но сломалась у коллег: 5 шагов к переносимости

Обвязка (harness) — это скиллы, MCP-подключения, субагенты и проверки вокруг ИИ-агента вроде Claude Code. У автора из Directum она год работала без сбоев, но у коллег сломалась: в скриптах остались пути с его машины, а на чистой виртуалке не было Python и Node.js. Он описал пять шагов, как убрать себя из схемы: пути теперь считаются от корня репозитория, а установщик сам проверяет окружение. Вывод: тестируйте установку на чистой машине до первого коллеги.

AI-обработка оригинала Habr AI; редакция Hamidun News
Обвязка Claude Code работала у одного, но сломалась у коллег: 5 шагов к переносимости
Источник: Habr AI. Коллаж: Hamidun News.
Слушать статью
Паспорт материала и цифры
ПараметрДанные
ПервоисточникHabr AI ↗
Главный редактор
Ключевой факт #1Цикл «ревью — исправление» ограничен тремя попытками, затем зовут человека
Ключевой факт #2Подписка для задач автора заметно выгоднее токенов API, сервер не нужен
Ключевой факт #3Evals — проверочные сценарии — ловят поломку скиллов после доработок

Многие уже собрали вокруг ИИ-агента личную обвязку: насмотрелись коротких видео, накидали скиллов, подключили MCP — и получилось «обвязанное» рабочее место. Обвязка, или harness, — это всё, что окружает модель: инструменты, инструкции, база знаний, субагенты и проверки. Пока пользователь один, она работает. Автор этого разбора, специалист Directum по продвижению платформы Directum RX, выяснил, что происходит дальше. Его обвязка год работала безотказно, но стоило отдать её коллегам, и она сломалась: главной её частью оказался сам автор, а через установщик автора не поставишь. Дальше он описывает пять шагов, как убрать себя из схемы. Часть решений уже работает, часть ещё дорабатывается, и сам он называет текст личным опытом, а не инструкцией по построению ИИ-команды.

Что именно передавали

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

Работа поделена между субагентами: product owner готовит требования и критерии приёмки, архитектор проектирует решение, разработчик пишет код и тесты, тестировщик проверяет сценарии, три ревьюера параллельно смотрят код, безопасность и соответствие архитектуре. Артефакты каждого этапа лежат в папке .pipeline, а переходами управляет скрипт: он проверяет обязательные результаты и сохраняет состояние, поэтому после перерыва координатор продолжает с того же места.

Есть два цикла «проверил — исправил»: для проекта решения и для кода. У каждого лимит в три попытки. Без лимита субагенты могут долго и увлечённо исправлять друг друга, сжигая лимиты подписки. Если третья попытка не прошла, координатор зовёт человека и сохраняет описание бага, результаты проверок и историю попыток.

Общий сервер или локальная установка

Автор рассматривал два варианта. Первый — общий сервис с песочницами (например, GoClaw или OpenHands): пользователь получает преднастроенную среду с нужной версией продукта. Для одной команды с одним окружением это удобно. Но обвязкой должны были пользоваться несколько команд с разными продуктами, версиями платформы и наборами решений. Одно окружение на всех не собрать, а поддержка нескольких вариантов потребовала бы отдельной команды.

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

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

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

Первый запуск на чистой машине

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

Теперь новый участник запускает установщик: он проверяет окружение, ставит зависимости и настраивает MCP-серверы. Прерванную установку можно повторить, выполненные шаги пропускаются. Если ошибка повторяется у нескольких людей, её решение попадает в установщик. Он учитывает операционную систему, СУБД и версию платформы. Например, платформа работает и с PostgreSQL, и с MSSQL, но утилиты автора на psql с MSSQL недоступны, и установщик об этом предупреждает. Инструменты проверяют именно из Claude Code, потому что работать в терминале и быть доступным агенту — разные вещи. А поскольку Bash под антивирусом на Windows запускался нестабильно, точки входа скриптов перенесли на Node.js.

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

Что делать на практике

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

Сюжет

Вопросы и ответы по материалу

Что известно по теме: что именно передавали?

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

Что известно по теме: общий сервер или локальная установка?

Автор рассматривал два варианта. Первый — общий сервис с песочницами (например, GoClaw или OpenHands): пользователь получает преднастроенную среду с нужной версией продукта. Для одной команды с одним окружением это удобно. Но обвязкой должны были пользоваться несколько команд с разными продуктами, версиями платформы и наборами решений. Одно окружение на всех не собрать, а поддержка нескольких вариантов потребовала бы отдельной команды.

Что известно по теме: первый запуск на чистой машине?

Хук появился не первым. Сначала автор развернул чистую виртуалку, склонировал репозиторий и запустил агента. Ошибки пошли раньше первой полезной задачи: не было зависимостей, которые он давно поставил у себя и забыл. Одному инструменту нужен Python, другому Node.js, третьему не хватало библиотек. Сначала с настройкой помогал сам агент, но иногда на подготовку уходил весь лимит пятичасового окна Claude. Теперь новый участник запускает установщик: он проверяет окружение, ставит зависимости и настраивает MCP-серверы.

ЖХ
Жемал Хамидун — CPO Alpina Digital, продакт-менеджер AlpinaGPT. Делает AI-продукты с 2019 года. Hamidun News — pet project, который вырос в production-агрегатор с 6000+ читателей.
✦ Практика · Hamidun Academy

Соберите рабочего ИИ-агента или сервис своими руками без ручного кода

В Академии Жемала Хамидуна (academy.hamidun.com) открыт бесплатный 72-часовой тест-драйв: интерактивные скетч-уроки по Claude Code и Cursor, живой Tech Radar и готовые шаблоны агентов.

Открыть 72ч бесплатный доступ →Интенсив по Вайб-кодингу
Что вы думаете?
Загружаем комментарии…