Архитектура проекта простыми словами

ИИ создал папки и сервисы, но как всё это работает вместе? Разбираем устройство проекта на записи на занятие: от кнопки и правил до базы, писем и сбоев.

Урок для вайбкодеров: составляем карту сервиса, находим ответственность частей и проверяем, что произойдёт при повторе запроса или отказе почты.

Архитектура проекта простыми словами
Дмитрий Борейчук
Автор
Дмитрий Борейчук
• 13 лет опыта в маркетинге и продажах • Более 1000 проектов • Основатель портала Wake up Marketing • Практикует маркетинг и внедрение ИИ в бизнес клиентов
Страница автора
💡 Хотите прокачаться в ИИ и маркетинге?
Подпишитесь на Telegram-канал Дмитрия: дневник развития портала Wake up Marketing, билдера сайтов и приложений в Ноя и маркетплейса шаблонов. Плюс выжимка 13 лет опыта в суровом маркетинге и плоды 2 лет работы с ИИ 24/7
Перейти в Telegram-канал

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

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

Если пока трудно обсуждать устройство своего сервиса, в Ное можно создать текстового помощника для разбора архитектуры. Ниже дадим инструкцию: вы присылаете обезличенное описание, помощник объясняет связи и помогает найти вопросы к разработке.

Коротко

  • Начинайте с одного действия человека. Проследите его от кнопки до сохранённого результата.
  • Различайте устройство кода и то, что запущено. Пять папок в проекте могут работать одной программой.
  • Узнайте, где хранятся важные данные и какие правила проверяются на сервере.
  • Отдельно разберите сбои: повторное нажатие, недоступность почты, перезапуск программы.
  • Хорошая первая схема помещается на листе и помогает найти конкретный код. Количество технологий само по себе ничего не доказывает.

Что входит в архитектуру проекта

Представим небольшой сервис записи на занятия. Посетитель выбирает время, оставляет имя и получает подтверждение. Организатор видит список участников. Это вымышленный учебный проект; дальше будем разбирать именно его.

Владелец обычно думает о возможностях: календарь, личный кабинет, письма. Архитектура связывает эти возможности с конкретными решениями. Календарь откуда-то получает свободные места. Кто-то проверяет, можно ли занять выбранное время. Где-то хранится запись. Отдельная часть отправляет письмо.

Для начала полезно составить четыре небольших описания:

Что описываемНа какой вопрос отвечаем
Действие посетителяЧто происходит после нажатия «Записаться»
Части программыГде проверяются места, сохраняются записи и готовятся письма
Запущенные программы и хранилищаЧто должно работать, чтобы посетитель смог записаться
Работа при сбоеЧто увидит человек, что сохранится и как продолжить работу

Эти описания должны совпадать друг с другом. Если на схеме есть отправщик писем, а в рабочем запуске его никто не включает, схема обещает несуществующую возможность.

Выбранные технологии называют стеком: язык, библиотеки, база и другие инструменты. Названия вроде React, Python или PostgreSQL описывают инструменты. По ним одним нельзя понять, где проверяется право отменить чужую запись и что будет при повторном запросе. Для этого нужна архитектура конкретного приложения.

Если отчёт ИИ непонятен
Разберитесь, что произошло в вашем проекте
  • Пришлите очищенный отчёт своего помощника
  • Получите объяснение на вашем примере
  • Определите, какого подтверждения пока нет
Создать помощника по проекту
Для учебного разбора нужно только описание ситуации. Условия старта — на странице регистрации.

Как проходит запись на занятие

Фронтенд — часть приложения, с которой взаимодействует человек: страница с календарём, полями и кнопками. В нашем примере она работает в браузере. Бэкенд — серверная часть: принимает запрос, проверяет условия и сохраняет результат.

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

Вот путь одной записи. Стрелка означает передачу запроса или данных; строки нужно читать сверху вниз.

Промпт
Браузер → сервер приложения: запиши меня на выбранное занятие.
Сервер → база данных: сохрани запись и задачу отправить письмо.
Сервер → браузер: запись сохранена, вот её номер.
Фоновый обработчик → база: возьми ожидающую задачу.
Фоновый обработчик → почтовый сервис: отправь подтверждение.

База данных хранит сведения, которые приложение должно находить и изменять: занятия, участников, записи. Фоновый обработчик выполняет работу отдельно от ожидания посетителя. Здесь он отправляет письма после сохранения записи. Внешний сервис — чужая система, к которой обращается наше приложение, например поставщик почты.

Браузер и сервер общаются через HTTP — Hypertext Transfer Protocol, протокол передачи запросов и ответов. Сервер может вернуть готовую страницу или данные, из которых браузер обновит страницу. Оба подхода используются в веб-приложениях. MDN показывает этот обмен на примере клиентской и серверной частей.

Как браузер вообще находит сайт и получает страницу, разбирали в отдельном уроке про путь после клика. Сейчас нас интересует следующий уровень: кто внутри сервиса отвечает за результат.

Где должны жить правила сервиса

Допустим, на занятии осталось одно место. Страница показывает его свободным. Пока посетитель вводит имя, другой человек успевает записаться.

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

Это бизнес-правило: условие, по которому работает продукт. В нашем сервисе оно звучит просто: «Нельзя записать больше участников, чем есть мест». Слово «бизнес» здесь не требует продаж: правила есть и у бесплатного кружка.

Теперь добавим запись через Telegram. Если правило спрятано в обработчике кнопки на сайте, для бота его придётся писать заново. Два варианта легко начнут расходиться. Удобнее, когда и страница, и бот обращаются к одной серверной операции записи.

Код можно разделить так:

Часть кодаЕё работа в нашем сервисе
Обработчик запросаПрочитать присланные данные и вернуть понятный ответ
Правила записиПроверить занятие, участника и доступность места
Работа с базойСохранить согласованные изменения и прочитать результат
Работа с почтойПревратить задачу в обращение к выбранному поставщику

Выделенную часть кода с понятной задачей называют модулем. Ему не обязательно быть отдельной программой. Модули записи и почты могут лежать в одном проекте и выпускаться вместе.

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

Не обязательно сразу создавать десяток слоёв и папок. Начните с разделения, у которого есть понятная причина: например, правило записи требуется и сайту, и боту. В руководстве Microsoft разделение ответственности внутри программы рассматривается отдельно от размещения частей по серверам.

Кто проверяет права

Посетитель может отменить свою запись, организатор — любую. Это тоже правило, и оно должно проверяться в доверенной серверной части.

Аутентификация отвечает на вопрос «Кто обращается?». Например, человек вошёл в свой аккаунт. Авторизация отвечает на вопрос «Что этому человеку разрешено?». Вход в аккаунт не даёт права менять запись другого участника.

Скрытая кнопка отмены помогает интерфейсу, но запрос можно отправить без этой кнопки. Сервер должен проверить и пользователя, и его право на конкретную запись. OWASP рекомендует проверять разрешения для каждого запроса и не полагаться на проверки в браузере.

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

Как части договариваются об обмене данными

У формы и сервера должна быть общая договорённость: куда отправить запрос, какие поля передать и что считать успехом. Такой способ взаимодействия называют API — Application Programming Interface, программный интерфейс. Веб-API часто выглядит как набор адресов, к которым программа обращается по HTTP.

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

Промпт
Запрос: POST /api/bookings
Данные: занятие, имя участника, ключ операции.
Успех: запись сохранена; ответ содержит её номер.
Нет места: запись не создана; ответ объясняет причину.
Письмо: отправляется отдельно; сохранение записи не означает доставку письма.

POST здесь означает метод запроса, которым просим создать запись. Ключ операции позволяет узнать одну попытку записаться: его сохраняют при повторе того же действия. Зачем он нужен, скоро увидим на сбое.

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

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

В проекте с ИИ-генерацией текста граница устроена похоже. Языковая модель может предложить описание занятия, но решение о свободном месте должно опираться на данные и правила сервиса. Убедительная фраза модели «место забронировано» ещё не подтверждает, что программа выполнила запись.

Где хранятся данные и файлы

Приложение хранит разные вещи, и у каждой своя судьба при перезапуске или выкладке.

Что хранитсяВозможное местоЧто важно выяснить
Участники и записиБаза данныхКак прочитать запись после перезапуска и восстановить копию
Фотографии занятийХранилище файловСохранятся ли файлы после замены программы и кто может их читать
Временно посчитанное число местКешКак долго допустимо показывать старое значение
Настройки программыКонфигурацияКакие настройки отличаются в учебной и рабочей среде
Ключ почтового сервисаХранилище секретов или защищённые настройки сервераКто может использовать ключ и не попадает ли он в браузер

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

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

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

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

Резервная копия должна покрывать нужное состояние. Если восстановили таблицы, а загруженные файлы потеряли, сервис может показать карточки с отсутствующими фотографиями. Проверка восстановления важнее отметки «копирование включено»: подробнее в уроке про резервные копии.

Что действительно запущено в проекте

ИИ создал папки web, api и worker. Из этого можно узнать намерение автора, но нельзя заключить, что работают три отдельные программы.

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

Для нашего сервиса возможен такой список:

  • Браузер посетителя показывает страницу и отправляет запросы.
  • Сервер приложения принимает запросы, проверяет правила и работает с базой.
  • Обработчик писем периодически берёт ожидающие задачи.
  • База хранит записи и задачи между запусками программы.
  • Почтовый сервис находится у внешнего поставщика.

Сервер приложения и обработчик можно запускать из одного набора кода. Но если это разные процессы, у каждого должен быть свой способ запуска и проверки. Файл обработчика, который никто не запускает, письма не отправит.

Инфраструктура — среда для этой работы: машины, сеть, хранилища, настройки запуска. Развёртывание, или деплой, — выпуск версии в эту среду. В уроке про CI/CD разбирали цепочку проверок и выпуска. CI — Continuous Integration, непрерывная интеграция: изменения объединяют и автоматически проверяют. CD может означать Continuous Delivery, подготовку проверенной версии к выпуску, или Continuous Deployment, её автоматическую выкладку. Здесь полезно спросить: «Какие части должны обновиться вместе и чем подтвердим их работу?»

В описании запуска могут встретиться ещё два слова. Контейнер упаковывает программу с нужным окружением для запуска. Serverless, буквально «без серверов», означает модель, в которой запуском и машинами управляет платформа. Серверы при этом существуют. Ни контейнер, ни serverless сами по себе не решают, где хранить записи и как пережить повтор запроса.

Среда — отдельное место запуска со своими настройками и данными. У локального опыта на вашем компьютере, тестового стенда и рабочего сервиса должны быть явно различимые подключения. Иначе безобидная команда из учебного задания может обратиться к настоящим данным.

Что произойдёт при сбое почты

Вернёмся к началу. В простом варианте сервер делает три действия подряд: сохраняет запись, отправляет письмо, возвращает ответ. Пока почта отвечает быстро, проблема незаметна.

Но поставщик завис. Запись уже сохранена, сервер ждёт письмо, браузер перестаёт ждать сервер. Посетитель не понимает, получилось ли записаться. Так возникает тайм-аут — прекращение ожидания после установленного времени. Он не доказывает, что предыдущая операция не выполнилась.

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

Это решение подходит именно для подтверждающего письма. Если письмо необходимо для проверки адреса, приложение может сначала создавать запись в состоянии «ожидает подтверждения». Какой результат обещать человеку, зависит от смысла операции.

Как не забыть отправить письмо

Недостаточно сохранить запись, а потом положить поручение «куда-нибудь в память». Программа может завершиться между этими шагами. Запись останется без письма и без следа о том, что его нужно отправить.

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

Таблицу ожидающих поручений называют outbox, то есть «исходящие». Обработчик читает её и обращается к почте. Такой подход описан в руководстве AWS о transactional outbox.

Outbox можно использовать без отдельного сервиса очередей. Очередь задач — способ хранить и выдавать работу обработчикам. Специализированная очередь бывает полезна при росте проекта, но первая задача — вообще не терять поручение. Уведомление и запись не становятся одной общей транзакцией с чужой почтой: между системами остаётся возможность сбоя.

Почему повтор всё ещё опасен

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

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

В нашем учебном варианте повтор записи с тем же ключом возвращает прежний номер. Если под тем же ключом пришли другие данные, сервер отклоняет запрос. А подставной почтовый сервис узнаёт ключ отправки и не создаёт второе письмо.

У настоящего поставщика нужно отдельно выяснить, есть ли такая возможность и как долго она работает. Например, Stripe документирует ключи идемпотентности для своего API. Условия Stripe нельзя автоматически переносить на почту или другой сервис. Если поставщик не умеет узнавать повтор и нет способа проверить прежний результат, простая отметка в нашей базе не гарантирует отсутствие дублей.

Кто заметит зависшие поручения

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

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

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

Что показал наш учебный опыт

Мы воспроизвели эти ситуации отдельной программой на Python и SQLite. SQLite — база, которая в этом опыте хранит данные в локальном файле. В одном временном файле находились записи и поручения; второй файл изображал чужой сервис с собственной фиксацией результата. Настоящие письма и сетевые запросы не отправлялись.

Вот что программа проверила при последовательном выполнении действий:

ДействиеЧто получилось
Дважды записаться с одним ключом и теми же даннымиОдин номер записи, одна запись и одно поручение
Повторить ключ с другим именемОтказ, прежние данные сохранены
Остановить операцию до фиксации транзакцииНи дополнительной записи, ни дополнительного поручения
Сделать подставную почту недоступнойЗапись сохранена, поручение осталось ожидающим
Остановить обработчик после приёма письма поставщикомУ поставщика один результат, у нас поручение ещё ожидает
Повторить обработку и затем запустить её ещё разОдин результат у поставщика, поручение завершено; новой отправки нет

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

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

Чтобы повторить его со своим помощником, задайте точную задачу:

Промпт
Сделай отдельный локальный учебный опыт архитектуры записи на занятие. Не меняй мой проект и не используй его настройки, секреты, базу или сеть. Все имена вымышленные, файлы — в новой временной папке.

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

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

Объясни простыми словами, почему сбой после отправки оставляет неопределённость. Отдельно назови, что этот опыт не проверяет. Если можешь запускать код, выполни его и покажи действительный вывод. Иначе дай код для отдельного запуска и не придумывай результат. После проверки удали только созданную тобой временную папку.

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

Когда нужны монолит и микросервисы

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

Микросервисы — подход, при котором функции системы разделены между отдельно развиваемыми и выпускаемыми сервисами. Они общаются по сети. Это позволяет менять или масштабировать отдельные части, но добавляет сетевые ошибки, согласование данных и обслуживание нескольких запусков.

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

СитуацияЧто выяснить перед усложнением
ИИ предлагает пять сервисов для первой формыКакую наблюдаемую проблему решает каждый отдельный запуск
Письма мешают отвечать посетителямМожно ли отделить выполнение писем, сохранив общий код
Одна операция перегружает весь проектГде измерена задержка и поможет ли отдельная обработка
Разные команды постоянно мешают друг другу выпускать измененияКакие части действительно можно выпускать независимо

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

У второго экземпляра приложения есть важное последствие: память первого ему недоступна. Если записи или задачи живут только в переменных, разные посетители могут попасть в разные картины мира. Поэтому вопрос хранения нужно решить раньше, чем копировать запущенные программы.

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

Как понимать архитектуру сервиса с ИИ

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

Не начинайте с просьбы «нарисуй идеальную архитектуру». В ответ легко получить убедительную схему приложения, которого у вас нет. Начните с существующего проекта и одного действия.

Такое задание подойдёт помощнику с доступом к репозиторию в Claude Code, Codex, Antigravity или другой среде:

Промпт
Помоги мне понять архитектуру этого проекта на одном действии пользователя: [опиши действие]. Сначала только изучение, без правок, установки зависимостей, сетевых запросов, запуска команд проекта и обращения к базам.

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

Отдельно покажи:
1. Где проверяются данные, права пользователя и главные правила операции.
2. Где хранятся постоянные данные, загруженные файлы и отложенные задачи. Значения секретов и строки подключения не выводи.
3. Какие программы должны работать и какими файлами описан их запуск. Отличай описание запуска от подтверждения, что он состоялся.
4. Какие обращения идут к внешним сервисам. Что произойдёт при отказе, повторе запроса и перезапуске программы.

Составь короткую карту: часть → ответственность → с чем общается → где хранит данные. Раздели найденные факты и неизвестное. Новые термины объясняй рядом простым языком.

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

Сверьте хотя бы два перехода сами. Откройте названный файл: действительно ли форма вызывает указанный адрес? Откройте обработчик: действительно ли он сохраняет данные в названном месте? Это не экзамен по программированию. Вы учитесь отличать найденную связь от уверенного объяснения.

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

Как разобрать описание в Ное

Если сейчас нет доступа к репозиторию, можно начать с объяснения словами. В Ное создайте помощника для разбора архитектуры и присылайте ему обезличенные описания: что делает посетитель, какие части проекта известны, где сохраняются сведения и что происходит при ошибке.

Промпт
Ты объясняешь архитектуру небольшого сервиса человеку, который создаёт его с ИИ. Работай только с присланным описанием. Не придумывай файлы, технологии, запущенные процессы, проверки или доступ к проекту. Не проси секреты, строки подключения и реальные данные пользователей.

Мой случай: [действие посетителя, известные части, место хранения, наблюдения и предложение помощника].

Сначала объясни путь одного действия простым языком. Назови, кто за что отвечает и что действительно известно о сохранении результата. Новые термины объясняй сразу. Папка не доказывает отдельный работающий сервис; описание проверки не доказывает её выполнение. Пустой список после перезапуска сам по себе не доказывает отсутствие записи в базе: могло не сработать чтение. Утверждай отсутствие сохранения только если это прямо известно из описания. Ошибка ответа не доказывает отсутствие записи, а сохранённая запись не доказывает отправку письма.

Затем укажи главное неизвестное. При нехватке данных задай не больше двух конкретных вопросов. Не советуй переписывать проект на микросервисы без установленной причины. Для повторов различай создание записи и внешнюю отправку: защита одной операции не означает защиту другой. Не советуй повторять отправку без выяснения прежнего результата и возможностей поставщика. Идемпотентность объясняй как «повтор той же операции не создаёт второй результат», а не как одноразовость. Один идентификатор письма сам по себе не доказывает защиту поставщика от дублей. Если она неизвестна, для следующего опыта предложи только локального подставного поставщика без сети и настоящих писем. Не подставляй предполагаемые обязанности папок в раздел известных фактов. Предложи один безопасный следующий шаг для проверки в отдельной учебной среде; не выдавай его за выполненный. Не давай команды для рабочего запуска и не предлагай менять доступы или удалять данные.

Ответь тремя короткими частями: «Как это устроено», «Что нужно выяснить», «Следующий шаг». Для первой беседы достаточно примерно 150–220 слов. Если устройство неизвестно, объясни известный участок и не достраивай остальное.

Создайте такого помощника в Ное, поставьте инструкцию и вернитесь к нему с описанием следующей функции. Так постепенно получится понятная карта сервиса. Файлы и результаты запуска нужно проверять отдельно в проекте.

Мы проверили эту инструкцию на двух случаях: папки приняли за работающие сервисы; защиту записи от повторов приняли за защиту письма. Во втором случае помощник ответил:

Промпт
Повторное создание записи у нас защищено: при повторной попытке запись не дублируется. Но это не распространяется автоматически на внешнюю отправку письма.

В ответах он отделил известное от предположений, но оставил отдельные слова без объяснения. Например, Network — вкладка браузерных инструментов со списком сетевых запросов, а localStorage — хранилище данных в самом браузере. Если помощник предлагает опыт с подставным поставщиком, результат объяснит работу учебной программы. Поведение настоящей почты нужно выяснять отдельно по её документации и проверкам.

Как проверить решение перед изменением

Понимание архитектуры становится полезным в момент правки. Допустим, вы хотите разрешить перенос записи на другое занятие. Теперь нужно не только передвинуть карточку в календаре, но и освободить старое место, занять новое, сохранить изменение и правильно отправить письмо.

До написания кода составьте короткую запись решения. ADR — Architecture Decision Record, запись архитектурного решения, — название такого документа. Для маленького проекта достаточно нескольких абзацев обычным языком:

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

Цена решения есть даже у хорошей архитектуры. Отложенная почта делает ответ посетителю независимым от её скорости, зато создаёт работу по наблюдению и повторным попыткам. Полезное объяснение ИИ должно показывать обе стороны.

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

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

С чего начать прямо сейчас

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

Попросите ИИ подтвердить ответы конкретными файлами. Начните с первого места, где вместо ответа стоит предположение. Часто уже один такой разбор объясняет, почему маленькая просьба «добавь поле» затронула несколько частей проекта.

Частые вопросы

Нужна ли архитектура маленькому проекту?

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

Можно ли доверить архитектуру ИИ?

ИИ может предложить вариант и найти связи в коде, если имеет к нему доступ. Но выбранные обязанности, сохранность данных и последствия ошибок должны проверяться. Просите объяснить решение на вашем сценарии и показать, чем оно подтверждено.

Как понять, что архитектуру пора менять?

Сначала назовите повторяющуюся проблему: разные правила записи на сайте и в боте, потеря задач, изменения одной функции постоянно ломают другую. Затем найдите причину. Отдельный сервис нужен тогда, когда его польза оправдывает новый запуск, сетевые сбои и обслуживание.

Чем архитектура отличается от структуры папок?

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

С какого навыка начать вайбкодеру?

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

Продолжите разбор
Ведите понятную историю своего проекта
  • Возвращайтесь с результатом следующей проверки
  • Разбирайте новый сбой на конкретной правке
  • Просите объяснить незнакомое слово на примере
Создать помощника по проекту
Вставьте инструкцию из статьи в текстового сотрудника Нои.

💬 Комментарии

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

🍋Ещё статьи в категории «IT и AI простыми словами»

В категорию
Миграции базы данных: что это и как сохранить заявки
16.10.2026#IT и AI простыми словами
Миграции базы данных: что это и как сохранить заявки
ИИ добавил поле и просит применить миграцию. Разбираем, что он меняет в базе, как сохранить старые заявки и проверить результат на отдельном примере.
Дмитрий Борейчук
Автор
Дмитрий Борейчук
Как искать ошибку в проекте вместе с ИИ: разбор одной формы
16.10.2026#IT и AI простыми словами
Как искать ошибку в проекте вместе с ИИ: разбор одной формы
Кнопка не работает, а ИИ уже переписал полпроекта? Разбираем одну настоящую учебную ошибку: от запроса с неверным полем до проверенного исправления.
Дмитрий Борейчук
Автор
Дмитрий Борейчук
Фронтенд, бэкенд и база данных: куда уходит заявка с сайта
16.10.2026#IT и AI простыми словами
Фронтенд, бэкенд и база данных: куда уходит заявка с сайта
Форма написала «Отправлено». Где теперь заявка и переживёт ли она перезапуск? Прослеживаем одну запись от кнопки до хранения на учебном сайте.
Дмитрий Борейчук
Автор
Дмитрий Борейчук
Как браузер открывает сайт: что происходит после клика
16.10.2026#IT и AI простыми словами
Как браузер открывает сайт: что происходит после клика
Страница появилась, а товары не загрузились? Показываем путь от адреса сайта до отдельных запросов браузера на маленьком работающем примере.
Дмитрий Борейчук
Автор
Дмитрий Борейчук
CI/CD простыми словами: как выложить свои изменения
14.10.2026#IT и AI простыми словами
CI/CD простыми словами: как выложить свои изменения
ИИ поправил файлы. Как понять, что новая версия дошла до посетителей? Разбор на одной кнопке и нашем настоящем поезде выкладок.
Дмитрий Борейчук
Автор
Дмитрий Борейчук

🏆Другие категории

Все категории
Как оплатить из России
Как оплатить из России
Как оплатить зарубежные сервисы, приложения, подписки и игры из России: пошаговые инструкции, способы оплаты и активация цифровых покупок.
Дневник разработки: билдер Нои и Wake Up
Дневник разработки: билдер Нои и Wake Up
Открытый дневник: как строится билдер сайтов и приложений Нои и как портал Wake Up Marketing становится источником трафика для него. С цифрами из базы, ошибками и планами.
Биографии великих и ИИ-наставники
Биографии великих и ИИ-наставники
Истории успеха предпринимателей и создателей нейросетей — по развилкам и кризисам, а не по годам. К каждой — ИИ-наставник, думающий по принципам героя.
Книги для бизнеса и саморазвития
Книги для бизнеса и саморазвития
Главные идеи книг по маркетингу, продажам и саморазвитию — и что с ними делать.
Заработок на ИИ
Заработок на ИИ
Как зарабатывать на ИИ: услуги, свои продукты, партнёрки, контент.
ИИ-видео и нейромультики
ИИ-видео и нейромультики
Как делать вирусные ролики нейросетями: промпты, платформы, заработок.