Знание и умение разрабатывать на Spring Data JPA — это обязательный навык для разработчика, если он хочет заниматься разработкой приложений на Spring. Этого мы ожидаем и от AI-агента.
Удовлетворяют ли наши AI-агента этому условию? Во многом зависит от того, насколько продвинутую модель вы используете. Значит ли это, что Opus 4.8 не совершает ошибок? Совсем нет. Более того, иногда удивляешься, почему еще вчера он настроил связь правильно, а уже сегодня сделал ту же работу, но добавил CascadeType.ALL.
В сегодняшнем эпизоде еженедельной рубрики Skill of the Week разберёмся, как, используя Spring Data JPA Skill, научить своего агента важным навыкам при работе со Spring Data JPA.
Этот Skill входит в состав набора скиллов для Spring-разработчика. Исходный код всех скиллов доступен на GitHub. Рекомендую поставить звёздочку, чтобы не потерять.
Качество модели в AI-агенте
Открывая очередной пост с описанием того, как улучшить поведение агента, можно обнаружить, как автор, используя Claude Code 20x Max-подписку, не обращая внимания на лимиты и ограничения, настраивает Harness. Однако реальность немного отличается.
Реальное рабочее окружение накладывает свои ограничения. Начиная со стоимости самих подписок, например, работодатель выдает Claude Code на 20$ или же базовую подписку на Cursor, и заканчивая разрешением использовать только те модели, что доступны в контуре организации. Такие ограничения приводят разработчика к необходимости использовать в качестве основных модели среднего класса: Sonnet, Haiku, OpenAI OSS 120b, MiniMax... Я буду использовать Haiku/Sonnet далее в примерах.
Использование Skill, которые улучшают понимание фреймворков для AI-агентов с моделями среднего класса, имеет критически важное значение для получения качественного результата. Такой Skill может легко поднять качество генерации в отдельных задачах с Haiku до Opus.
Spring Data JPA
Spring Data JPA — Skill, задача которого — предоставить AI-агенту знания о том, как именно ведется разработка на Spring Data JPA. Дать представление о том, что такое сущность, поле сущности, типы полей, правила связывания сущностей. Каким правилам необходимо следовать при использовании Lombok совместно с JPA, а также что учитывать при генерации equals/hashcode/toString (с/без учета наличия Lombok).
Уникальностью данного Skill является тот факт, что он учитывает особенности/соглашения при работе с JPA именно в вашем/текущем проекте (естественно, если это в явном виде не порождает ошибки). Делает он это, выполняя анализ в несколько шагов. Данный анализ может быть сохранен в память проекта; как результат, повторный вызов Skill пропустит этот шаг.
Как установить
Установить Spring Skills глобально во все обнаруженные агенты:
npx skills add Amplicode/spring-skills -gУстановить только для конкретных агентов (пример — Claude Code + Codex + Gemini CLI):
npx skills add Amplicode/spring-skills -g -a claude-code -a codex -a gemini-cliС более подробной инструкцией можно ознакомиться тут.
Явная/ручная активация
Для начала разберемся, как воспользоваться Skill в ручном режиме. Необходимо это в ситуации, когда вы, например, занимаетесь моделированием доменной области, создавая JPA-сущности.
В идеальном мире агент должен из контекста задачи понять, что необходимо выполнить активацию Skill, и выполнить ее. К сожалению, это не всегда так, особенно на моделях среднего класса, поэтому приходится указывать активацию непосредственно в чате или, например, в плане, если вы используете режим планирования.
В качестве примера сгенерируем чистый Spring Boot-проект, используя start.spring.io и добавив в него только два модуля: Spring Data JPA и Bean Validation. Далее попросим Claude Code с Haiku создать сущности ветеринара, домашнего животного и визита, но усложним задачу, указав, что домашнее животное является частью агрегата владелец, а визит является независимым рутом.
Как видно, в результате было создано три сущности, в качестве id используется sequence per table, что является best practice в общем случае. Для связи Owner -> Pet в качестве коллекции используется Set, что для корректной работы требует корректного определения equals & hashcode на стороне many, то есть для Pet. Обратите внимание, что equals & hashcode определены с учетом возможного HibernateProxy. Также для связи Owner -> Pet определены дополнительные параметры cascade = CascadeType.ALL, orphanRemoval = true, что согласуется с исходным требованием о том, что домашнее животное является частью агрегата владелец. Для Pet -> Visit связь не определена, что тоже согласуется с постановкой.
В результате, несмотря на то, что мы использовали модель Haiku, сгенерированный код соответствует тому, который мы бы получили от Opus 4.8. На самом деле даже лучше, поскольку Opus до сих пор не умеет корректно генерировать equals & hashcode без использования Spring Data JPA Skill.
Использование в плане
Если вы разрабатываете, предварительно запуская режим планирования, то вы замечали, что агент не особо активирует Skill-ы в процессе выполнения плана. Мотивировать агента использовать Skill можно, указав его в плане явным образом. Для этого достаточно в начале шага плана указать на использование конкретного Skill.
> **JPA skill required (amplicode-spring-skills:spring-data-jpa).** Before writing any entity code: activate the skill and verify the implementation follows its rules. For any deviation — ask the developer before continuing.Вот как это выглядит в конечном плане:
Если теперь попросить агента приступить к реализации плана, то он активирует его с высокой вероятностью.
Использование в других Skill
Постепенно, развивая собственный harness и добавляя новые скиллы, мы видим, как в наших коллекциях появляются скиллы, которые уже не просто отдельные действия, а являются полноценными сценариями, включающими создание сущностей, генерацию кода сервисов, описание новых endpoint и т.д. В такого рода Skill полезно использовать другие Skill, которые как раз помогают качественно выполнять отдельные специализированные шаги.
В качестве примера напишем Skill, который при добавлении сущности сразу создаст Rest Endpoint и Service для получения элементов сущности по Id.
---
name: entity-service-rest
description: >
Scaffolds a full vertical slice for one domain entity in three steps: the JPA entity, a Spring
service for it, and a REST controller with a find-by-id endpoint. The controller calls the
repository ONLY through the service (controller → service → repository), never directly. Use
this skill when the user asks to create an entity together with its service and controller, to
build a feature/vertical slice around an entity, or to add an entity plus a service plus a REST
endpoint that looks up by id — even when the skill is not named explicitly.
---
## Step 1 — Entity
Determine the entity name (and any fields) from the user's prompt; ask only if it is missing.
**Activate the `spring-data-jpa` skill** and use it to create the JPA entity. Let it own the
project's entity conventions. If the entity already exists, this step just confirms it.
Also make sure a Spring Data repository exists for the entity (e.g. `{Entity}Repository extends
JpaRepository<{Entity}, {IdType}>`). If none exists, create one following the same skill's
repository guidance.
## Step 2 — Service
The service returns a DTO, so first make sure a DTO and an entity↔DTO mapper exist:
**Activate the `dto-creator` skill**, telling it the DTO is **for a service / REST controller**.
That skill creates the DTO and automatically delegates to `mapper-creator` for the mapper. Reuse
an existing DTO/mapper if the project already has one.
The mapper **must be a MapStruct mapper** — pass this to `dto-creator` / `mapper-creator` so the
mapper type is MapStruct (not a custom converter). If `mapper-creator` needs MapStruct
dependencies added to the build file, let it add them.
Then create a `@Service` that injects the **repository** and the **mapper**, with a `findById(id)`
method that calls `repository.findById(id)` and returns the entity mapped to the DTO.
## Step 3 — REST controller
Create the controller:
- annotate it `@RestController` with a request mapping like `/rest/{entities}`
- inject **the service only** — never the repository
- add `GET /{id}` that calls `service.findById(id)`, returns the DTO with 200, or 404 when absent
---
## Done
Before finishing, double-check the core invariant: the controller goes through the service, and
only the service touches the repository.Проверим его работу на практике. Решим ранее озвученную задачу с ветеринарами, домашними животными и визитами. Вызовем агента с той же формулировкой, но теперь будем использовать вновь созданный нами Skill. В этот раз будем использовать модель Sonnet 4.6.
Как видно на видео, в результате работы Agent с нашим новым Skill мы получили все ожидаемые компоненты: Entity, Service, RestController, Repository и связывающий их воедино код. Обратите внимание, что Agent не создал rest endpoint для pet — видимо, таким образом он трактовал понятие агрегата. Поправить это оставим читателю в качестве домашнего задания.
Если тебе интересно, как настроить свой Agent для разработки на Spring, а также ты не хочешь пропустить новые выпуски Skill of the Week и другие полезные материалы по разработке на Spring с AI Agent — подписывайся на наш канал в ТГК.
А больше полезных Skill для разработки на Spring/Spring Boot можно найти в нашем репозитории (звездочки приветствуются).
Предыдущий выпуск Skill of the Week: Spring Explore — первичный сбор контекста
