Всем привет! Меня зовут Щепетков Константин, я TechLead бэкенд разработки компании ZeBrains, работаю в роли TeamLead бэкенда на проекте мобильного приложения Бургер Кинг.

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

Чтобы ускорить разработку, решил в качестве эксперимента делегировать часть задач ИИ-инструментам. Негативных кейсов поначалу было много, но со временем качество результата заметно выросло.

В статье делюсь, как давать ИИ чёткие задачи, чтобы он писал рабочий код, соответствующий архитектуре, а не выдумки. Рассказываю про workflow, контекст, шаблоны и кодогенерацию — всё, что превращает ИИ из рискованной игрушки в полезный инструмент для бэкенда. В конце статьи будет ссылка на пример подобных практик.

Тут не будет инструкций к конкретным ИИ-иструментам, но при этом поделюсь практическим опытом применения ИИ. Статья будет полезна не только бэкенд‑разработчикам, но и всем, кто хочет использовать ИИ-инструменты осознанно.

Что надо ИИ, чтобы писать нормальный код?

Самое важное при работе с ИИ — качество результата: корректный, читаемый, рабочий код, который точно соответствует ТЗ и не вносит багов.

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

Так что же нужно ИИ для корректного выполнения задач?

• Workflow — минимальное описание того, как вести работу. Это может быть и простая фраза вроде «реализуй функцию по ТЗ», и полноценный чек-лист: сначала разбей задачу, потом предложи интерфейсы, потом напиши реализацию и т.д.

• Чёткое и полное ТЗ — с явным указанием входов, выходов, бизнес-логики и ограничений.

• Контекст проекта — понимание, в какой системе мы работаем: структура каталогов, основные модули, принципы взаимодействия сервисов.

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

• Критерии выполнения задач — что значит «выполнено», что мы хотим увидеть по итогу.

• Механизмы проверки — линтеры, анализаторы, юнит- и интеграционные тесты, контрактные проверки. Всё, что позволяет сразу отсечь 90% некорректных вариантов ещё до ревью человеком.

Как подготовить проект к работе с ИИ

Первым делом стоит понять, где ИИ может пригодиться. По факту — почти везде: где-то он поможет написать регулярное выражение, а где-то реализует целый микросервис.

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

У нас ситуация другая: мы начали писать новый бэкенд с нуля, распиливая старый монолит на независимые сервисы. Это и стало отправной точкой для подготовки к использованию ИИ.

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

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

Где сыграла ключевую роль кодогенерация

Настоящий прорыв случился с кодогенерацией.

Раньше ИИ постоянно ошибался в интеграциях, неверно строил DTO, путал поля в схемах ответа, неправильно вызывал внешние сервисы. Сейчас мы поступаем иначе: сначала пишем OpenAPI для контроллеров или конкретной интеграции, а потом генерируем из них весь контроллер (включая модели ответа) или клиент для вызова другого сервиса.

Так мы убрали с плеч ИИ самую сложную для него работу — кропотливый маппинг полей интеграций.

На этом этапе начали формироваться базовые правила написания кода, workflow для ИИ и контекст проекта — всё то, что превращает хаотичные подсказки в предсказуемый, контролируемый результат.

Итого: главный толчок дали три вещи — шаблоны проектов, чистая понятная архитектура и кодогенерация по OpenAPI. Благодаря им мы смогли один раз «объяснить» ИИ, как устроены сервисы, и теперь он уверенно ориентируется в них, не выдумывая лишнего.

ИИ-ассистент на этапе анализа задачи

ИИ можно подключать с самого первого момента — как только вы взяли задачу в работу. Открыли задачу, увидели ТЗ, начали продумывать реализацию и поняли: «Эту задачу можно доверить ИИ».

Но как объяснить ему, что именно нужно?

По опыту, есть два рабочих подхода:

1. Вы сами описываете задачу — вручную пишете .md-файл (или прямо в чат с ИИ), куда копируете всё из ТЗ: требования, примеры запросов, схемы, комментарии. Главное — дать полную и структурированную картину.

2. Вы поручаете это ИИ — с помощью современных ИИ-браузеров или браузерных плагинов.

Сейчас есть ИИ-браузеры, которые умеют открывать веб-страницы, читать контент и выдавать структурированное ТЗ в Markdown. Это особенно ценно, когда ТЗ большое, на несколько экранов, с вложенными ссылками, примерами curl-запросов, обсуждениями в комментариях. ИИ спокойно проваливается по подссылкам, собирает всё нужное и оформляет кратко, но полно.

Важно: результат обязательно нужно проверить. ИИ может что-то упустить, неправильно интерпретировать или пропустить уточнение в комментарии.

Кроме того, вы дополняете ТЗ своими техническими и архитектурными требованиями — тем, что знает только разработчик: «используй общий клиент логирования», «не создавай новый слой, положи в service», «валидация — только через встроенный мидлвар» и т.п.

Кстати, такие ИИ-браузеры полезны не только для анализа задач: они отлично справляются с поиском информации, анализом логов в Kibana или Grafana, заполнением форм, составлением отчётов — любыми рутинными действиями в браузере.

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

Как дать ИИ нужный контекст — и не утонуть в деталях

У нас уже есть базовый workflow и полное ТЗ, но этого часто недостаточно.

Современные ИИ-ассистенты в IDE умеют индексировать репозиторий и «примерно» понимать структуру проекта… если повезёт. Но нам нужно, чтобы ИИ понял задачу точно, а не «примерно».

Чтобы не полагаться на удачу, контекст мы передаём сами — только тот, что действительно нужен для задачи.

Три ключевых элемента:

1. Описание проекта и правила разработки
   Что это за сервис? На каком стеке написан? Какие соглашения важны именно здесь?
   Часть этой информации уже заложена в единых шаблонах, но для конкретного проекта нужно уточнить:
   
   какие слои использовать;
   как именовать переменные и пакеты;
   где лежит бизнес-логика, а где — инфраструктурный код.
   
   Это не «правила для всех», а локальные договорённости, которые помогают ИИ писать «как мы».

2. Информация об интеграциях
   Если задача затрагивает внешние сервисы — указываем, где лежат готовые клиенты или как их создавать.
   Если интеграции нет, но есть работа с БД — прикладываем DDL-файл с описанием таблиц и полей.
   Это исключает выдумки вроде «а давай добавим колонку user_secret_token» — если её нет в схеме, ИИ её не придумает.

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

P.S. Вообще это подход memory bank: в нём больше файлов и описаний, но не обязательно описывать всё, только то, что вы считаете нужным.

Дополнительно: если задача сложная, с множеством классов, интерфейсов или неочевидными связями, хорошая практика — заранее создать «скелет» кода: пустые файлы, интерфейсы, сигнатуры методов. Так ИИ точно знает, куда вставлять логику, и не начнёт придумывать свою архитектуру.

Как формировать запрос к ИИ

Собираем всё вместе:

• кратко напоминаем workflow (или вставляем его целиком);

• прикладываем структурированное ТЗ;

• даём только нужный контекст (не весь репозиторий!);

• указываем конкретные файлы, с которыми нужно работать;

• добавляем комментарии: «здесь важно использовать общий клиент», «валидация — через валидатор в пакете X», «не пиши код, пока я не подтвержу».

Примеры — очень полезны

ИИ по умолчанию пишет код «как умеет», а не «как вы». Чтобы направить его, покажите, как «правильно».

Это могут быть:

• фрагмент или ссылка на существующий контроллер;

• образец DTO с тегами и комментариями;

• шаблон unit-теста.

Современные ИИ-агенты в IDE иногда сами находят такие примеры, но если явно указать их в контексте — шанс ошибки резко падает.

Проверка и итерации

Можно сразу просить ИИ написать тесты и прогнать линтер, но на практике удобнее делать это отдельным запросом:

1. Сначала — реализация логики.

2. Вы проверяете, всё ли соответствует ТЗ и архитектуре.

3. Затем — отдельный запрос: «напиши unit-тесты» или «добавь проверки, исправь замечания линтера».

И самая эффективная практика:

• Сначала просите ИИ написать план реализации: шаги, файлы, логику.

• Апрувите план или правите его.

• И только потом даёте команду писать код.

Это позволяет сразу увидеть:

• правильно ли ИИ понял задачу;

• хватает ли ему контекста;

• не упустили ли вы что-то в ТЗ.

Если что-то не так — дописываете контекст и запрашиваете новый план. Если всё верно — даёте зелёный свет на генерацию.

Работайте с ИИ как с джуном — итеративно и с обратной связью

К этому моменту у нас уже есть:

• workflow,

• структурированное ТЗ,

• необходимый контекст проекта,

• примеры кода,

• пояснения по реализации,

• критерии проверки.

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

Но на практике почти весь контекст вы создаёте один раз:

• правила разбиваете на отдельные .md-файлы;

• шаблоны, OpenAPI, DDL уже лежат в репозитории;

• примеры кода — в том же проекте.

Дальше вы просто подкидываете нужные файлы в чат как контекст. Остаётся написать только ТЗ и пару комментариев под задачу.

Не перегружайте контекст

ИИ в большинстве задач пишет приемлемый код. Ему не нужно знать всё обо всём.

• Давайте только то, что важно именно сейчас.

• Сами правила формулируйте кратко и по делу.

Главное — не пытайтесь решить задачу одним запросом

Даже опытный разработчик редко пишет идеальный код с первой попытки. Почему ИИ должен?

Правильный цикл работы:

1. Отправляете сформированный запрос.

2. ИИ предлагает план реализации — вы его апрувите или корректируете.

3. Он пишет код — вы читаете, проверяете, задаёте уточнения.

4. Если ИИ «пошёл не туда» — пишете: «Нет, сделай вот так», и даёте подсказку.

5. Если ошибка — просите исправить. Это нормально.

1–5 запросов на задачу — стандартная практика. Если уходит больше, возможно, не хватает контекста… или задача просто не подходит для ИИ (например, требует глубокого понимания бизнес-логики или архитектурных решений).

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

Не забывайте про тесты и проверки

Либо сразу просите написать unit-тесты, либо после апрува кода оформляете отдельный запрос: «Напиши тесты», «Проверь, не сломалось ли что-то в существующих сценариях», «Запусти линтер и исправь замечания».

И самое важное — задавайте ИИ вопросы:

• «Почему ты сделал именно так?»

• На что он опирался?

• Не упустил ли что-то критичное?

Для джунов и миддлов это обязательный шаг — понимать мотивацию за каждым решением. То же самое и с ИИ. Он не «магический генератор», а ассистент, которому нужна обратная связь. Работайте с ним как с коллегой — не идеальным, но обучаемым.

Никогда не лейте код ИИ в мастер без ревью

Итак, задача «готова»: ИИ написал код, тесты проходят, всё выглядит нормально. Но это не повод мёржить без проверки.

Нужно обязательно:

• внимательно прочитать то, что сгенерировал ИИ;

• понять, как работает логика;

• убедиться, что нет скрытых ошибок, избыточных вызовов или потенциальных багов.

Если видите, что решение неоптимально — исправьте сами или попросите ИИ переписать. Даже «рабочий» код может быть неподдерживаемым, избыточным или несоответствующим архитектуре.

Обязательно делайте ревью через git:

• проверьте все изменённые файлы;

• убедитесь, что ИИ не трогал то, что не должен (не изменил соседний хендлер или конфиг);

• сравните результат с изначальным планом.

Помните: за изменения в ветке отвечаете вы, даже если код писал ИИ.

Итог: применяйте ИИ осознанно

ИИ не знает ваш проект. Он не знает, как вы пишете код, не понимает бизнес-контекста и часто не до конца улавливает, чего именно вы хотите.

Если просто написать: «Сделай», — результат будет относительно случайным. А потом ругаться, что «ИИ тупой и ничего не может», — всё равно что взять перфоратор, зажать кнопку «включить» и швырнуть его в стену, а потом удивляться: «Почему полку не повесил?»

ИИ — это инструмент. Как молоток, как IDE, как curl. У него есть возможности и ограничения. Чтобы получить пользу, нужно уметь им пользоваться: понимать, что можно доверить, как правильно объяснить задачу и как проверить результат.

В этой статье я поделился реальным примером, как мы интегрируем ИИ в разработку бэкенда:

• через шаблоны,

• кодогенерацию по OpenAPI,

• структурированные ТЗ,

• управляемый контекст,

• итеративную работу и обязательное ревью.

Это не рецепт, а направление. Ваш путь может быть другим — пробуйте, тестируйте, адаптируйте.

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

Примеры шаблонов, workflow и промптов, использованных в статье, доступны на GitLab:
https://gitlab.com/k.schepetkov/example-workflow

Всем спасибо! И пока ?