Выпуск 4 · вайбкодинг · агенты · как это работает · безопасность · api

Из чего состоит приложение: пять частей

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

Главное в двух строках

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

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

Если вы попали сюда раньше времени

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

Карта: пять частей

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

Часть 1Интерфейс то, что видит человек: экраны в браузере и на телефоне
Часть 2Сервер то, что считает и решает. Пока живёт на вашем компьютере
Часть 3База данных то, что хранит: ваши записи о расходах
Часть 4Внешние сервисы чужие программы: нейросеть, почта, платежи
Часть 5Настройки и секреты адреса и ключи, отдельно от всего остального

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

Путь одной записи

Я пишу «кофе 350» и нажимаю Enter. Вот что происходит за эти сто миллисекунд.

1

Интерфейс отправляет строку

Забирает то, что вы напечатали, и передаёт серверу. Сам ничего не решает и ничего не хранит.

2

Сервер разбирает

350 — это сумма, «кофе» — это категория «Кафе». Вот здесь принимаются все решения.

3

База записывает

Строка: сумма, категория, дата, счёт. База ничего не решает, она только хранит то, что ей дали.

4

Сервер отвечает

«Сохранено, вот новые итоги за месяц». Итоги считает он, а не браузер.

5

Интерфейс перерисовывает

Список и сумма месяца обновились. Круг замкнулся.

Это видно своими глазами. В браузере откройте панель разработчика (F12, или Cmd + Option + I на Mac), вкладку «Сеть», и добавьте запись. Появится строка запроса — это и есть «интерфейс поговорил с сервером». Нажмите на неё: слева уйдёт просто текст «кофе 350», а обратно придёт разобранная запись с суммой, категорией, датой и счётом.

Почему суммы выглядят странно

В базе сумма 350 рублей лежит как 35000. Это копейки: с деньгами так делают всегда, чтобы не копились ошибки округления. Если увидите в плане агента строчку «хранить в копейках» — это не причуда, это нормальная практика.

Три правила

Из карты следуют три правила. Они короткие, и их стоит запомнить.

Интерфейс никогда не хранит

Всё, что вы видите на экране, — копия. Настоящее лежит в базе.

Сервер никогда не рисует

Он считает и решает. Как это выглядит — не его дело.

База ничего не решает

Она только хранит то, что ей дали, и отдаёт обратно.

Зачем это вам: если агент предлагает что-то, что нарушает любое из правил — например, «посчитаем итоги прямо в браузере» или «сохраним настройку в интерфейсе», — это повод спросить «зачем». Обычно оказывается, что задачу поняли не так.

Папка проекта: шесть мест

Откройте папку проекта и разложите её по карте. Читать файлы не нужно, нужно понимать, что где.

1

app/ — экраны

Интерфейс. То, что человек видит и на что нажимает.

2

app/api/ — что считает и решает

Сервер. В разных проектах эта папка может называться server/ или src/api/.

3

prisma/ — устройство хранилища

База: описание того, какие поля есть у записи. Рядом лежит и сам файл базы.

4

.env — адреса и ключи

Секреты. Единственное место, где они должны лежать. Рядом обычно есть .env.example — тот же список, но без значений.

5

package.json — список чужого кода

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

6

node_modules/ — сам чужой код

Сюда не заходим никогда и никому эту папку не отправляем: она огромная и всегда собирается заново одной командой.

Больше в папке знать не нужно. А спрашивать, где что лежит, можно у самого агента — это быстрее, чем искать глазами.

Три вопроса своему проекту

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

Три вопроса подряд вставить агенту одним сообщением
Ответь коротко, без кода, как человеку без опыта программирования:

1. Какие внешние сервисы использует проект и куда уходят мои данные?
2. Где хранятся данные и что будет, если удалить файл базы?
   Как сделать резервную копию?
3. Какие секреты и ключи нужны проекту и где они должны лежать?
Где лежит конкретная функция когда надо понять, что трогать
Покажи, какие файлы отвечают за [название функции].
Для каждого скажи одним словом, это интерфейс, сервер или база.
Код не показывай.

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

API и ключ простыми словами

API — это дверь с правилами, через которую одна программа говорит с другой

Всё. Остальное — подробности про то, как именно устроена эта конкретная дверь.

Внутренний API

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

Внешний API

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

API-ключ — это пропуск и счётчик оплаты одновременно. По нему чужой сервис понимает, кто пришёл и с чьего баланса списывать деньги. Отсюда всё остальное: украденный ключ — это не «кто-то увидел буквы», это чужие траты с вашего счёта.

Где ключ живёт и где не должен

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

Можно

  • Файл .env на сервере, рядом с проектом
  • Личный кабинет сервиса, откуда вы ключ взяли
  • Менеджер паролей, если хочется копию
  • Файл .env.example — но только имена переменных, без значений

Нельзя

  • В интерфейсе: всё, что попало в браузер, видно любому
  • В истории проекта: оттуда его уже не вычистить
  • В чате и переписке, даже «на минутку, для диагностики»
  • В скриншоте и в кадре ролика
Если ключ всё-таки утёк

Не прячьте и не переживайте — отзовите. В кабинете сервиса удалите старый ключ и выпустите новый, потом поменяйте значение в .env. Это пять минут и ровно та реакция, которая здесь нужна. Я сам однажды засветил ключ в переписке и сделал именно это.

Проверить, что файл с секретами не попадёт в историю проекта, можно одним вопросом агенту.

Проверка секретов перед тем, как делиться проектом
Проверь, что файлы с секретами не попадают в историю проекта.
Скажи, какие файлы перечислены в .gitignore, и есть ли среди них .env.
Если нет - добавь и объясни одной фразой, что изменилось.

«А можно подключить банк, чтобы само?»

Самый частый вопрос за всю серию. Честный ответ: нет, и вот три причины.

1

У банков нет открытого API для обычных людей

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

2

Отдавать логин и пароль от банка чужой программе нельзя

Никогда и никакому сервису, как бы красиво он ни выглядел. Это касается и приложения, которое вы собрали сами.

3

Открытые API Банка России — это пилот для организаций

Они существуют, но не для приложения, собранного дома на выходных.

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

Чек-лист: проверьте себя

Не про приложение, а про понимание. Отмечайте то, что действительно можете сделать или объяснить.

Если пошло не так

1

В папке проекта нет app/api/ или prisma/

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

2

В панели разработчика на вкладке «Сеть» пусто

Панель показывает только то, что произошло при открытой панели. Откройте её и после этого добавьте запись или обновите страницу.

3

Агент отвечает кодом вместо объяснения

Добавьте в вопрос одну фразу: «объясни словами, без кода, как человеку без опыта программирования». Работает почти всегда.

4

Файла .env вообще нет

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

5

Случайно открыл node_modules и испугался

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

Не помогло — напишите в Telegram, с описанием того, что видите на экране.

Что дальше

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

Откуда эти материалы

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

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

Пройти курс