Создание харнесса для код-агентов под enterprise-фреймворк на Java

Вайб-кодинг, или AI-assisted development, отлично работает на уровне прототипа: агент получает текстовое ТЗ и быстро собирает первый рабочий вариант. Но в корпоративной разработке этого мало.

Проблема начинается там, где нужно не просто написать код, а собрать полноценное корпоративное приложение. В Джеймикс между «экран открылся» и «система действительно работает как надо» лежит пропасть.

В какой-то момент мы задались вопросом: можно ли научить ИИ-агента проходить этот путь самостоятельно? Можно, если собрать вокруг него харнесс (англ. harness) . Именно о нем статья.

В Джеймикс мы строим этот мост как инженерную обвязку: набор скиллов, инструментов и проверок, который помогает довести работающий прототип до реально работающей системы. Для его строительства мы используем агентную платформу KodaCode (далее — Koda) в собственной разработке на Джеймикс и регулярно гоняем ее на бенчмарках. Если оценивать по делу, Jmix-задачи агент решает уверенно. Разброс от сессии к сессии есть, мы видим его в собственных прогонах, и строгие pass/fail-бенчмарки его даже преувеличивают. Поэтому ставка не на идеального агента: обвязка и контроль не дают этому разбросу попасть в ваш продакшен. Это SKILLS.md под Джеймикс, преднастроенные инструменты и проверки на выходе. 

Ниже разберем шесть составляющих такого харнесса. Мы собрали их в KodaCode для Jmix-проектов: пакет навыков, преднастроенные инструменты и проверки на выходе. Это можно собрать самостоятельно, но на практике такой путь занимает месяцы проб и ошибок.

Теперь про доступ. Для российских команд это больное место: Claude Code, Codex и Gemini CLI (и тем более Antigravity CLI) официально недоступны. Koda доступна из России, и ее можно взять в работу уже сегодня.

1. Дайте агенту карту проекта

Память у агента короткая, а нового агента вы порой подключаете «с улицы», когда он еще не знает ни вашего кода, ни ваших соглашений. Положите в репозиторий понятный README.md и файл инструкций для агента (AGENTS.md): зачем нужен этот код, почему выбран такой стек, как устроена архитектура, как все собирается и тестируется, какие у вас правила код-стайла и коммитов. Заготовка такого AGENTS.md под Джеймикс входит в наш пакет, останется дописать специфику вашего проекта. 

Koda первым делом читает AGENTS.md и подхватывает контекст, ей не нужно перелопачивать весь проект, чтобы начать работать. Экономия времени, токенов и нервов.

2. Опишите доменные правила как навыки

Джеймикс создан для бизнес-задач, и для ИИ-агента он палка о двух концах. 

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

Обратная сторона: эта защита не срабатывает сама собой, а многие правила Джеймикс вообще не проверяются компилятором. Код собирается зеленым, экран падает на этапе отрисовки в рантайме. 

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

Граблей хватает. Денежное поле требует bigDecimalField, а не numberField; заголовки и описания полей задаются через msg://-ключи; @Composition-коллекцию редактируют в property-bound контейнере, а не загружают через query-loader; списание со склада логичнее вешать на EntityChangedEvent. Человек это знает. Агенту нужно подсказать.

Для подсказок в Koda есть навыки (skills): короткий markdown-файл с инструкцией под одну задачу, который агент сам подгружает в нужный момент. Навык и есть ваша спецификация, записанная под агента: прочитал и применил.

И вот тут главный вклад с нашей стороны. У нас собран готовый пакет навыков под Джеймикс: главный AGENTS.md плюс файлы-навыки под сущности, экраны (тот самый bigDecimalField), роли (никаких лишних прав), i18n, события, миграции.
Каждый навык появился из прогонов: ловили агента на конкретной ловушке и записывали правило — теперь подсказка есть в каждой сессии.

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

При этом AI-guidelines в пакете навыков не привязаны к одной модели: они одинаково помогают и локальным моделям, которые, кстати, без подсказок галлюцинируют чаще, и фронтирным. А тесты мы гоняем на разных моделях, чтобы знать, как ИИ-агенты поведут себя в проде у наших клиентов.

3. Подключите свежую документацию и IDE через MCP

Самая частая беда автономного агента в том, что он выдумывает имена методов, которых нет, и потом по кругу ловит ошибки компиляции. Лечится это доступом к свежим источникам. 

Koda подключает внешние инструменты по стандарту MCP (Model Context Protocol). Мы преднастраиваем стек из нескольких инструментов:

• Docs Search: встроенный в KodaCode инструмент поиска помогает ИИ находить нужные знания в документации Джеймикс, Vaadin и Spring Boot без внешних инструментов вроде Context7 и без встроенного Google-поиска.

• Context7 дает свежую документацию Джеймикс: агент сверяется с настоящим API, а не выдумывает его. Этот MCP более актуален для Kilo Code и других open-source агентов, которые не имеют встроенного векторного поиска по код-сниппетам.

• JetBrains-like IDE MCP (OpenIDE MCP) показывает агенту те же инспекции IDEA, что видит ваш разработчик, включая ошибки Jmix Studio (например, отсутствие локализации у поля сущности).

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

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

4. Сделайте тесты спецификацией

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

На Джеймикс это UI-тесты на jmix-flowui-test-assist (они же UI Integration Tests): они поднимают контекст приложения и кликают по экранам (View) программно, без браузера. Навык для таких тестов лежит в нашем пакете: попросите вашего агента писать их вместе с фичами, и каждый следующий прогон агента становится безопаснее.

5. Поставьте контроль на выходе

У автономного агента «готово» и «работает» иногда расходятся: он честно рапортует об успешной сборке, не заметив, что экран не открывается. Поэтому не полагайтесь на самоотчет агента. Заведите обязательную проверку, которую он не может пропустить: приемочные тесты и статический анализ в CI на каждый коммит, и результатом считается только зеленый прогон.

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

6. Дайте агенту логи и трейсинг

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

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

Возьмите готовое

У подписки на KodaCode есть честная альтернатива: собрать все то же самое самостоятельно. Свой пакет навыков, свой стек MCP, свой контроль на выходе в CI.

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

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

Что вы получаете, работая с нами:

• Единая подписка на Jmix + KodaCode;

• Полный доступ к большому числу передовых моделей без “костылей”;

• проверенный пакет навыков под Джеймикс (SKILLS.md плюс файлы-навыки) и преднастроенный набор инструментов;

• помощь с интеграцией в ваш процесс и поддержку, чтобы команда начала работать сразу;

• обновление навыков под новые версии Джеймикс и свежие практики.

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

Если хотите попробовать, как все работает, пришлите нам запрос на info@jmix.ru и получите бесплатную подписку на Jmix + KodaCode PRO на месяц и инструкцию по установке. В конечном счете такие вещи лучше оценивать своими руками.