Всем привет!

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

В конце статьи я оставлю ссылку на свой DEV-блог, если захотите узнать больше о соло-разработке SaaS продуктов.

Первым делом давайте разберём пару интересных замечаний с прошлой публикации и проработаем их. Тут будет душно, но после сделаем интересные выводы. Эту часть можно вообще скипнуть, если вы не в контексте шаблона из прошлой статьи. Можно сразу перейти к выводам. Я постарался не лить сильно воду, а высказаться по существу.

Зачем в хендлерах на каждую команду заново создавать сервисы и репозитории? Почему бы не сделать хендлер на основе класса, добавить тод register, который будет вешать команды на нужный метод класса, а сервисы и репозитории передать в инит?

Вообще я делал это для простоты. Однако замечание действительно интересное. Давайте разбираться.

В чём была проблема:

В каждом хендлере была новая инициализация сессии БД, что делало невозможным тестирование без реальной живой сессии БД.
Не было единой точки композиции. Хендлеры во многом похожи, однако собираются каждый раз заново. Это создавало риски неправильной сборки и, в целом, могло замедлять добавление новых хендлеров.

Теперь же мы имеем такую картину:

TelegramHandlers - это нормальный класс, теперь с ним можно делать что угодно.
У него есть единая точка сборки всех роутов.
Инъекция фабрики сессии через конструктор.

Ну и чем это лучше:

Теперь изи подменяется зависимость от БД для тестов - можно мокать, давать другую фабрику и что угодно.
Весь список роутов теперь до крайности нагляден - вместо хаоса тегов @router у нас единый register - короткий и очевидный.
Код легче масштабировать.

Вывод:
— Код нагляднее, а зависимости поставляются чище.

сервисы почему-то знают что-то об arq и sqlalchemy, а не работают через абстракции

Да, получилась не-очень-чистая архитектура, которая не решает проблемы. В текущем виде мне будет сложно, например, заменить sqlalchemy с arq на что-нибудь другое, ведь мои сервисы напрямую работают с объектами sqlalchemy. (Абстракции, сюда!)

В чём была проблема:

Это была не "чистая архитектура", а довольно таки грязная. Слои смешаны. Сервисы и репозитории - то бишь бизнес код - был явно завязан на SQLAlchemy и arq. А хендлеры и воркер тянули инфу напрямую из app.models.
Репозитории отдавали ORM наружу. Любой потребитель знал про модели в БД и зависел от них.
Отправка задачи в очередь без какой-либо абстракции. Сложно подменять и тестировать.

Что изменилось:

Добавили DTO'шки на границы сервисов!
Паттерн "Порты и Адаптеры". Добавяем Порты (интерфейсы) для всяких бизнес штук и добавляем Адаптеры - реализации этих интерфейсов. Суть - абстракция, не известно какая, но возвращает известный и понятный DTO.
Слой сервисов теперь работает через абстракции портов и ничего не знает об arq и sqlalchemy.

В чём профит:

Явные границы зависимостей, проще расширять и изменять правила домена, проще даже думать о домене.
Тестируемость выше.
Код не привязан к sqlalchemy - можем заменить, например.

Вывод:
— Улучшение архитектуры в сторону масштабирования.

Таким образом мы слегка улучшили наш шаблон. Но давайте подумаем, принесло ли это реальную пользу проекту? Напомню, что цель этого шаблона - ускорить создание MVP прототипов приложений. Раньше архитектура была не достаточно "чистой", но зато не было избытка абстракций и, вцелом, будем честны, разрабатывать на "недочистой" архитектуре много проще. Теперь же у нас есть контракты, которые позволяют делать всякое - тестировать например, заменять что-то на что-то, думать сфокусированее и так далее.

Но вот только реальной пользы на MVP это не приносит.

Мы получили улучшенную архитектуру, но усложнённый код. Это обосновано, если на базе этого шаблона мы хотим создать нечто большее чем прототип - нормальный расширяемый продукт. Тогда конечно - архитектура становится критичным звеном. Однако в случае создания MVP'шек - сложная архитектура - почти всегда оверхед.

Тем не менее есть и плюсы. Современные плюсы. Обоснованные. Связанные с таким актуальным AI-first подходом к разработке.

Нынче на рынке активно используются AI-агенты для разработки. Те кто их до сих пор не применяют в работе, рискуют серьёзно отстать от рынка.

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

Если ваш код большой и вы дадите задачу переписать его, отрефакторить и даже снабдите нейронку подробнейшим ТЗ с описанием архитектуры и методов есть риск что агент в какой-то момент начнёт выпадать из контекста, галлюцинировать и просто всё портить вокруг себя. Большие грязные неархитектурные легаси проекты вообще невозможно отрефакторить нейронками без сумасшедшего планирования и декомпозиции.

Поэтому, при AI-First подходе к работе обязательно пишите архитектурный план.
Можете даже советоваться с теми-же нейронками какую реализацию лучше применить.

Раньше чистая архитектура казалась мне избыточной для MVP.

Но с появлением AI-агентов я всё больше прихожу к мысли, что архитектура нужна уже не только людям.
Она становится способом объяснить проект машине.

Бонусная секция

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

Скилы (skills) - это заранее подготовленные команды для вашего агента. Например, если ввиду вашей привычки или принятым правилам вам часто нужно документировать фичи, то для такого можно создать себе skill и не придётся писать большой промпт с объяснением что нужно сделать каждый раз.

Правила (Rules) - это вроде правил разработки. Представьте что ai'шка - это ваш программист падаван и он каждый день словно только пришёл на проект - ничего о нём не знает. Чтобы каждый раз не объяснять ему что тут к чему, можно описать это в файлах. Упомяните там основные модули проекта, принятые архитектурные стандарты, правила и запреты, что где лежит и какая в этом всём логика.

Лайфхак (Lifehack). 👾
Можно попросить агента самому себе написать правила и навыки, прикиньте. Только дайте ему по-больше контекста, а потом всё тщательно перепроверьте. Не забудьте упомянуть чтобы он всё писал кратко, а то мало-ли, забьёт весь контекст одними своими правилами :)

На этом всё, уважаемые хабровчане и гости хабра. Рад был снова оказаться в вашем инфополе и надеюсь вам это было полезно!

В свободное время я занимаюсь своим SaaS стартапом. Создаю нечто вроде генератора рекламных креативов и вскоре планирую выпускать его на рынок. Если вам интересно понаблюдать за процессом или вы хотите узнать как самим создавать продукты нужные людям, окунуться немного в маркетинг и подобные темки - обязательно подписывайтесь на мой dev-блог: https://t.me/videogem_devblog.

GitHub шаблона, о котором речь в статье, кстати здесь - https://github.com/wizardloong/PythonDockerTemplate .

Если что, версия, которую мы улучшаем в коммите 55505089d7fee07e1579839b2983b7c8f4227d7c.

С вами был Виктор @wizardloong, всего отличного!

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

Чистая архитектура для MVP — оверхед. Пока в проект не пришёл AI