Главное в двух строках
Читать код вам не нужно. А вот понимать, из чего приложение состоит, нужно: без этого любая мелкая поломка выглядит как катастрофа, а разговор с агентом превращается в угадайку.
Как водителю не обязательно знать устройство двигателя, но обязательно знать, где двигатель, а где бензобак. Карта ниже — ровно такого размера. Ни одной строчки кода наизусть.
Эта страница продолжает серию: установка комплекта, первое приложение, как ставить задачу. Здесь мы ничего не строим, а разбираемся в том, что уже построили.
Карта: пять частей
Любое приложение состоит из пяти частей. Ваше тоже. Каждая функция, которую вы просите у агента, трогает одну-три из них, и умение сказать, какие именно, — половина хорошей постановки задачи.
В нашем приложении четвёртой части пока нет вообще, а пятая пустая: всё работает на одном компьютере и никуда не обращается. Обе появятся, когда подключим нейросеть.
Путь одной записи
Я пишу «кофе 350» и нажимаю Enter. Вот что происходит за эти сто миллисекунд.
Интерфейс отправляет строку
Забирает то, что вы напечатали, и передаёт серверу. Сам ничего не решает и ничего не хранит.
Сервер разбирает
350 — это сумма, «кофе» — это категория «Кафе». Вот здесь принимаются все решения.
База записывает
Строка: сумма, категория, дата, счёт. База ничего не решает, она только хранит то, что ей дали.
Сервер отвечает
«Сохранено, вот новые итоги за месяц». Итоги считает он, а не браузер.
Интерфейс перерисовывает
Список и сумма месяца обновились. Круг замкнулся.
Это видно своими глазами. В браузере откройте панель разработчика (F12, или Cmd + Option + I на Mac), вкладку «Сеть», и добавьте запись. Появится строка запроса — это и есть «интерфейс поговорил с сервером». Нажмите на неё: слева уйдёт просто текст «кофе 350», а обратно придёт разобранная запись с суммой, категорией, датой и счётом.
В базе сумма 350 рублей лежит как 35000. Это копейки: с деньгами так делают всегда, чтобы не копились ошибки округления. Если увидите в плане агента строчку «хранить в копейках» — это не причуда, это нормальная практика.
Три правила
Из карты следуют три правила. Они короткие, и их стоит запомнить.
Интерфейс никогда не хранит
Всё, что вы видите на экране, — копия. Настоящее лежит в базе.Сервер никогда не рисует
Он считает и решает. Как это выглядит — не его дело.База ничего не решает
Она только хранит то, что ей дали, и отдаёт обратно.Зачем это вам: если агент предлагает что-то, что нарушает любое из правил — например, «посчитаем итоги прямо в браузере» или «сохраним настройку в интерфейсе», — это повод спросить «зачем». Обычно оказывается, что задачу поняли не так.
Папка проекта: шесть мест
Откройте папку проекта и разложите её по карте. Читать файлы не нужно, нужно понимать, что где.
app/ — экраны
Интерфейс. То, что человек видит и на что нажимает.
app/api/ — что считает и решает
Сервер. В разных проектах эта папка может называться server/
или src/api/.
prisma/ — устройство хранилища
База: описание того, какие поля есть у записи. Рядом лежит и сам файл базы.
.env — адреса и ключи
Секреты. Единственное место, где они должны лежать. Рядом обычно есть
.env.example — тот же список, но без значений.
package.json — список чужого кода
Перечень библиотек, которые проект использует. По нему видно, что агент притащил в проект.
node_modules/ — сам чужой код
Сюда не заходим никогда и никому эту папку не отправляем: она огромная и всегда собирается заново одной командой.
Больше в папке знать не нужно. А спрашивать, где что лежит, можно у самого агента — это быстрее, чем искать глазами.
Три вопроса своему проекту
Задайте их любому своему проекту, хоть собранному сегодня, хоть чужому. Ответы сверьте с картой из пяти частей.
Три вопроса подряд вставить агенту одним сообщением
Ответь коротко, без кода, как человеку без опыта программирования: 1. Какие внешние сервисы использует проект и куда уходят мои данные? 2. Где хранятся данные и что будет, если удалить файл базы? Как сделать резервную копию? 3. Какие секреты и ключи нужны проекту и где они должны лежать?
Где лежит конкретная функция когда надо понять, что трогать
Покажи, какие файлы отвечают за [название функции]. Для каждого скажи одним словом, это интерфейс, сервер или база. Код не показывай.
На нашем приложении ответы были такие: внешних сервисов пока ни одного, всё работает локально; данные лежат в одном файле базы и при удалении пропадут безвозвратно, копия делается копированием файла; секретов пока нет. Это знание стоит дорого, а получено за десять секунд.
API и ключ простыми словами
API — это дверь с правилами, через которую одна программа говорит с другой
Всё. Остальное — подробности про то, как именно устроена эта конкретная дверь.Внутренний API
Наш интерфейс говорит с нашим сервером. Тот самый запрос, который видно в панели разработчика: «вот строка кофе 350» — «вот сохранённая запись». Он у вас уже есть, вы просто о нём не знали.
Внешний API
Наш сервер говорит с чужой программой: нейросетью, почтой, платежами. Разберём в восьмом выпуске. Вместе с ним появится и ключ.
API-ключ — это пропуск и счётчик оплаты одновременно. По нему чужой сервис понимает, кто пришёл и с чьего баланса списывать деньги. Отсюда всё остальное: украденный ключ — это не «кто-то увидел буквы», это чужие траты с вашего счёта.
Где ключ живёт и где не должен
Правильный путь один: ключ лежит в файле .env рядом с проектом,
его читает только сервер, и дальше сервер сам идёт к чужому сервису. До браузера
ключ не доезжает никогда.
Можно
- Файл
.envна сервере, рядом с проектом - Личный кабинет сервиса, откуда вы ключ взяли
- Менеджер паролей, если хочется копию
- Файл
.env.example— но только имена переменных, без значений
Нельзя
- В интерфейсе: всё, что попало в браузер, видно любому
- В истории проекта: оттуда его уже не вычистить
- В чате и переписке, даже «на минутку, для диагностики»
- В скриншоте и в кадре ролика
Не прячьте и не переживайте — отзовите. В кабинете сервиса удалите старый ключ
и выпустите новый, потом поменяйте значение в .env. Это пять минут
и ровно та реакция, которая здесь нужна. Я сам однажды засветил ключ в переписке
и сделал именно это.
Проверить, что файл с секретами не попадёт в историю проекта, можно одним вопросом агенту.
Проверка секретов перед тем, как делиться проектом
Проверь, что файлы с секретами не попадают в историю проекта. Скажи, какие файлы перечислены в .gitignore, и есть ли среди них .env. Если нет - добавь и объясни одной фразой, что изменилось.
«А можно подключить банк, чтобы само?»
Самый частый вопрос за всю серию. Честный ответ: нет, и вот три причины.
У банков нет открытого API для обычных людей
То, что называют банковским API, — это для бизнес-счетов, юридических лиц. Физическому лицу такой доступ просто не выдают.
Отдавать логин и пароль от банка чужой программе нельзя
Никогда и никакому сервису, как бы красиво он ни выглядел. Это касается и приложения, которое вы собрали сами.
Открытые API Банка России — это пилот для организаций
Они существуют, но не для приложения, собранного дома на выходных.
Поэтому путь другой: выписка файлом. Если ваш банк позволяет её скачать, в восьмом выпуске научим приложение её читать и раскладывать по категориям. Заодно это хорошее упражнение на карту: «подключить банк» — это внешний сервис, плюс база, плюс согласия. Сразу понятно, почему это дорого.
Чек-лист: проверьте себя
Не про приложение, а про понимание. Отмечайте то, что действительно можете сделать или объяснить.
Если пошло не так
В папке проекта нет app/api/ или prisma/
Нормально: имена папок зависят от того, на чём собран проект. Спросите агента: «разложи папки моего проекта по пяти частям — интерфейс, сервер, база, внешние сервисы, секреты». Карта та же, подписи другие.
В панели разработчика на вкладке «Сеть» пусто
Панель показывает только то, что произошло при открытой панели. Откройте её и после этого добавьте запись или обновите страницу.
Агент отвечает кодом вместо объяснения
Добавьте в вопрос одну фразу: «объясни словами, без кода, как человеку без опыта программирования». Работает почти всегда.
Файла .env вообще нет
Значит, секреты проекту пока не нужны. Он понадобится при подключении базы, а затем при подключении нейросети. Пустой файл заранее создавать не надо.
Случайно открыл node_modules и испугался
Там десятки тысяч файлов, и это нормально. Закройте и забудьте: эта папка не ваша и всегда собирается заново.
Не помогло — напишите в Telegram, с описанием того, что видите на экране.
Что дальше
В следующем выпуске я специально сломаю приложение одним запросом, который выглядит абсолютно невинно, а потом за одну команду верну всё назад. Разбор и команды — на странице «Если нейросеть сломала проект». Внешние сервисы разберём в восьмом, а сервер и постоянный адрес — в десятом.
Откуда эти материалы
Страница к четвёртому выпуску серии «Vibe Coding с нуля» — единственному теоретическому. В нём я рисую карту приложения из пяти частей, провожу одну запись по всем слоям на живом приложении, показываю папку проекта глазами не-программиста и честно отвечаю на вопрос про подключение банка.
Остальные выпуски: установка комплекта, первое приложение за 15 минут, как ставить задачу, поломка и откат. Если нейросети для вас вообще впервые, есть бесплатная раздатка: как формулировать запросы, проверять ответы и что нельзя отправлять. По шагам это разбирается в курсе «ИИ для чайников», остальные курсы на витрине.