Главная › Domain Driven Design › Гайд для AI-агента

DDD-спецификация: гайд для AI-агента

AI-агент с DDD: генерация кода и тестов, ревью, промпты.

DDD AI-агент

DDD AI-агент — aI-агент (Claude, ChatGPT, Copilot и др.) -- полноценный участник команды, работающей с DDD-спецификацией. Агент помогает заполнять шаблон, генерировать код и тесты из спецификации, проводить ревью, отвечать на вопросы о домене и поддерживать спецификацию в актуальном состоянии.

Основа работы AI-агента -- Шаблон спецификации. Загруженный целиком, он дает агенту полный контекст предметной области: границы контекста, глоссарий, доменную модель, state machine, бизнес-правила, команды, события, ошибки и критерии приемки.

Все примеры ниже используют единый домен -- "Интернет-магазин: оформление заказа".

DDD AI-агент: 1. Спецификация как контекст для AI

Загрузите Use Case спецификацию целиком как системный контекст (system prompt или прикрепленный файл). После этого AI-агент знает:

  • Все BR-коды и их формулировки -- может ответить "что проверяет BR-4?"
  • Все статусы и допустимые переходы -- может объяснить "можно ли отменить оплаченный заказ?"
  • Все роли и матрицу доступа -- может подсказать "кто может инициировать возврат?"
  • Все коды ошибок -- может ответить "что означает ORDER_CANCEL_FORBIDDEN?"
  • Все доменные события -- может перечислить "какие события публикуются при подтверждении заказа?"

Рекомендация: при каждом новом диалоге с AI прикладывайте актуальную версию спецификации. Устаревший контекст приводит к устаревшим ответам.

2. Генерация кода из спецификации

Каждый раздел спецификации транслируется в конкретные артефакты кода:

Раздел 3 (Domain Model) -> Java-классы агрегата, VO, Entity. AI генерирует класс Order (Aggregate Root) с private-полями, OrderItem (Entity), record-типы Money, DeliveryAddress, ProductSnapshot (Value Objects) с JPA-аннотациями.

Раздел 4 (State Machine) -> enum OrderStatus. AI создает enum со всеми состояниями из диаграммы переходов и метод canTransitionTo(), реализующий матрицу допустимых переходов.

Раздел 6 (Business Rules) -> валидация в доменной модели. Каждый BR-код превращается в проверку внутри доменного метода. BR-1 (заказ не пустой) -> if (items.isEmpty()) throw new OrderEmptyException() в методе Order.confirm(). BR-2 (количество 1--99) -> проверка в конструкторе OrderItem.

Раздел 7 (Commands) -> DTO + Application Service + REST Controller. Команда CreateOrder порождает record CreateOrderCommand, метод OrderApplicationService.createOrder() и эндпоинт @PostMapping("/api/v1/orders").

Раздел 8 (Events) -> event classes + Outbox entity. Каждое доменное событие (OrderCreated, OrderConfirmed, OrderPaid, OrderCancelled) становится классом-наследником DomainEvent, а для гарантированной доставки создается @Entity OutboxEvent.

Раздел 9 (Queries) -> Repository + Specification + Projection. Запрос SearchOrders порождает OrderSearchCriteria, OrderSpecification для динамических фильтров и interface OrderSummary как JPA Projection.

Раздел 13 (Errors) -> exception hierarchy + GlobalExceptionHandler. Каталог ошибок превращается в иерархию исключений (OrderEmptyException, OrderCancelForbiddenException) и маппинг в @RestControllerAdvice с корректными HTTP-кодами.

Раздел 12 (Saga) -> Saga orchestrator + SagaState entity. Описание процесса "резерв -> оплата -> доставка" порождает класс OrderProcessingSaga с @EventListener и @Retryable, а также @Entity SagaState для персистенции состояния саги.

3. Генерация тестов из спецификации

Спецификация содержит достаточно информации для генерации полного набора тестов:

Раздел 4 (матрица переходов) -> unit-тесты state machine. AI создает тесты для каждой пары (текущий статус, целевой статус): CREATED -> CONFIRMED -- успешный переход, DELIVERED -> CANCELLED -- ожидаем false от canTransitionTo(). Покрываются все ячейки матрицы.

Раздел 6 (BR таблица) -> позитивные, негативные и граничные тесты. Для BR-2 (количество 1--99): позитивный -- количество 5, граничные -- количество 1 и 99, негативные -- количество 0, 100, -1. AI генерирует параметризованные тесты @ParameterizedTest с @ValueSource.

Раздел 5 (матрица доступа) -> тесты авторизации. Для каждой комбинации "роль x действие" AI создает тест: Customer вызывает shipOrder() -> ожидаем AccessDeniedException. Manager вызывает createOrder() -- тоже. Admin вызывает initiateRefund() -- успех.

Раздел 15 (AC-1..AC-8) -> integration тесты. Каждый Acceptance Criteria в формате Given-When-Then транслируется в @SpringBootTest с Testcontainers: AC-1 -> POST /api/v1/orders с валидными данными -> 201 Created, заказ в БД, событие в outbox. AC-2 -> POST с пустым items -> 422, code: ORDER_EMPTY, в БД ничего.

4. Ревью кода против спецификации

AI-агент может провести систематическое ревью реализации по спецификации:

  • Полнота модели: проверить, что класс Order содержит все атрибуты из раздела 3 -- не пропущен ли ProductSnapshot, корректны ли типы полей
  • Корректность state machine: проверить, что OrderStatus.canTransitionTo() соответствует матрице из раздела 4 -- нет ли лишних или пропущенных переходов
  • Покрытие BR: проверить, что каждый BR-код реализован в доменной модели -- где именно проверяется BR-4, бросается ли правильное исключение
  • Маппинг ошибок: проверить, что все ошибки из раздела 13 обработаны в GlobalExceptionHandler -- корректны ли HTTP-коды, не утекают ли stack traces
  • Именование по глоссарию: проверить, что классы, методы и переменные следуют терминам из раздела 2 -- используется Order, а не Purchase; addItem(), а не addProduct()

Пример промпта: "Сравни класс OrderStatus.java с матрицей переходов из раздела 4 спецификации. Есть ли расхождения?"

5. Помощь бизнес-аналитику в заполнении шаблона

AI-агент помогает БА структурировать знания о домене:

  • Глоссарий: на основе описания процесса агент предлагает термины, определения и антислова. "Опиши процесс оформления заказа" -> агент выделяет сущности Order, OrderItem, DeliveryAddress и предлагает записи для таблицы глоссария
  • Бизнес-правила: из описания "заказ нельзя оформить без товаров, количество от 1 до 99" агент формулирует BR-1: Заказ должен содержать хотя бы одну позицию, BR-2: Количество товара в позиции -- от 1 до 99
  • Acceptance Criteria: из user story "Как покупатель, я хочу отменить заказ" агент формулирует AC в формате Given-When-Then с привязкой к BR и кодам ошибок
  • Альтернативные потоки: для Use Case "Создание заказа" агент предлагает ветки: корзина пуста, товар закончился, каталог недоступен, превышен лимит позиций

6. Помощь тестировщику

AI-агент помогает QA-инженеру построить полное покрытие:

  • Матрица переходов: из state diagram агент строит полную матрицу N x N всех комбинаций статусов, отмечая допустимые и запрещенные переходы
  • Граничные тест-кейсы: для каждого BR агент генерирует граничные значения. BR-2 (количество 1--99): тест-кейсы для 0, 1, 50, 99, 100
  • Негативные сценарии: агент предлагает сценарии, не описанные явно в спецификации -- конкурентное изменение заказа двумя пользователями, повторная отправка команды, таймаут внешнего сервиса на границе допустимого времени

7. Помощь DevOps

AI-агент помогает инженеру инфраструктуры:

  • Kubernetes manifests: из диаграммы C2 (контейнеры) агент генерирует Deployment, Service, ConfigMap для каждого компонента
  • Алерты: из NFR раздела 16 (время отклика < 2 сек, доступность 99.9%) агент предлагает Prometheus alerting rules с конкретными порогами
  • Docker Compose: агент генерирует docker-compose.yml для локальной разработки с PostgreSQL, Kafka, Redis и сервисом заказов

8. Помощь Security

AI-агент помогает специалисту по безопасности:

  • Ревью API-контракта: проверка эндпоинтов на утечку PII -- не возвращается ли полный адрес доставки в списке заказов, не передается ли customerId в URL
  • Каталог ошибок: проверка на information leakage -- ошибки не раскрывают внутреннюю структуру (SQL-запросы, stack traces, имена таблиц)
  • OWASP-чеклист: агент генерирует чеклист OWASP Top 10, адаптированный к конкретному контексту -- инъекции в поисковых фильтрах, IDOR через orderId, mass assignment через CreateOrderCommand

9. Актуализация спецификации

AI-агент поддерживает консистентность спецификации при изменениях:

  • Изменение кода -> обновление спецификации: если в коде появился новый статус REFUNDING или новое бизнес-правило -- агент предлагает добавить запись в соответствующие разделы шаблона
  • Проверка перекрестных ссылок: после добавления нового BR агент проверяет, что на него ссылаются AC, каталог ошибок и UI-спецификация. "BR-7 добавлен, но ни один AC его не проверяет -- нужен новый критерий приемки"
  • Drift detection: агент сравнивает текущий код с текущей спецификацией и указывает расхождения -- "В спецификации 6 BR-кодов, в коде реализовано 5 -- пропущен BR-3"

10. Примеры промптов для AI

Промпты для генерации кода:

  • "На основе раздела 3 сгенерируй Java-класс Order с JPA-аннотациями"
  • "Из раздела 4 создай enum OrderStatus с canTransitionTo() и unit-тестами"
  • "Сгенерируй CreateOrderCommand, OrderApplicationService.createOrder() и OrderController из раздела 7"

Промпты для ревью:

  • "Проверь, что все BR из раздела 6 покрыты тестами в OrderTest.java"
  • "Сравни GlobalExceptionHandler с каталогом ошибок из раздела 13 -- все ли ошибки обработаны?"
  • "Проверь именование классов в пакете domain.model по глоссарию из раздела 2"

Промпты для анализа:

  • "Какие ошибки может вернуть эндпоинт POST /api/v1/orders?"
  • "Какие роли имеют доступ к команде CancelOrder?"
  • "Какие события публикуются при переходе заказа в статус PAID?"

Промпты для расширения спецификации:

  • "Сгенерируй AC для нового бизнес-правила: минимальная сумма заказа 500 руб."
  • "Предложи негативные тест-кейсы для команды CancelOrder"
  • "Добавь в каталог ошибок запись для нового правила BR-7"
← Предыдущая
Гайд для сопровождения