Подготовка окружения

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

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

Операционная система

Все инструменты, которые мы используем, рассчитаны на Unix-среду. Если вы на Mac или Linux — откройте встроенный терминал. На Windows установите Windows Terminal и WSL — это виртуальная Linux-среда, которая работает прямо внутри Windows. Откройте WSL в Windows Terminal и перейдите в домашнюю папку:

user@computer:~$ cd ~

Установка Git

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

Помоги установить Git на мою систему.
Подскажи команды для установки и проверки.

После установки проверяем в терминале:

user@computer:~/landing$ git --version

Установка Docker

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

Попросите агента помочь с установкой:

Помоги установить Docker на мою систему.
Подскажи команды для установки и проверки.

После установки проверяем в терминале:

user@computer:~/landing$ docker --version

Создание проекта

Попросите вашего AI-агента создать проект:

Создай новый пустой проект для моего лендинга
в папке landing.
Создай репозиторий и README файл с базовым
описанием: "Здесь будет Vibe Landing приложение"

Агент создаст папку, инициализирует репозиторий и ответит что-то вроде:

Готово — создал папку landing/ с git-репозиторием и README.md.

README.md — это первое, что видит любой, кто открывает проект: вы сами через полгода, коллега или AI-агент. Даже одна строчка с описанием лучше, чем пустой проект — она задаёт контекст. Обычно содержит описание цели проекта, его компонентов, порядок запуска. Мы будем его заполнять по мере прохождения урока.

Перейдём в папку проекта и воспользуемся первой консольной командой — прочитаем файл README:

user@computer:~$ cd landing
user@computer:~/landing$ cat README.md

Вот что вы увидите в терминале:

user@computer:~$ cd landing
user@computer:~/landing$ cat README.md

# Landing

Здесь будет Vibe Landing приложение.

Базовые команды терминала — этого хватит на весь курс:

• ls — показать список файлов и папок
• cd landing — перейти в папку landing
• cd .. — вернуться на папку выше
• cat файл — прочитать содержимое файла

Все следующие действия мы будем выполнять в этой папке. Рекомендуется запустить агента именно из неё:

user@computer:~/landing$ claude

Также рекомендуем использовать IDE для удобного просмотра файлов. Подойдёт любая, но в дальнейшем мы будем опираться на VS Code или Cursor. Открыть IDE в текущей папке:

user@computer:~/landing$ code .
user@computer:~/landing$ cursor .

Это можно сделать прямо из Claude Code, набрав ! и команду прямо в чате — например, ! code . Так можно не только открывать VS Code, но и выполнять другие команды, не требующие расширенных полномочий: создание папок и файлов, чтение, операции с Docker и так далее.

Настройка AI-ассистента

Мы используем Claude Code. Можно использовать другие — Cursor, OpenCode, GitHub Copilot. Настройки будут отличаться, но принцип тот же.

Для Claude Code включаем автоподтверждение операций (YOLO mode), чтобы не подтверждать каждое действие вручную. Создайте папку .claude и в ней файл settings.json в корне проекта. Это можно сделать одной командой:

user@computer:~/landing$ mkdir -p .claude && touch .claude/settings.json

Откройте файл в IDE и вставьте (не забудьте сохранить, Ctrl+S):

{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Edit",
      "Bash(ls:*)",
      "Bash(mkdir:*)",
      "Bash(cp:*)",
      "Bash(mv:*)",
      "Bash(cat:*)",
      "Bash(npm:*)",
      "Bash(npx:*)",
      "Bash(node:*)",
      "Bash(git:*)",
      "Bash(gh:*)",
      "Bash(docker:*)",
      "Bash(docker compose:*)"
    ]
  }
}

Это разрешает ассистенту читать и редактировать файлы, запускать команды сборки, git и Docker. Для других ассистентов настройки будут отличаться — спросите у AI, как настроить именно ваш.

Чтобы агенту применились новые настройки, его нужно перезапустить. Нажмите Ctrl+C в чате с агентом два раза, затем запустите его заново.

Важно: даже с автоподтверждением стоит просматривать, что агент делает. Особенно команды удаления (rm, remove) — их лучше проверять перед выполнением.

Документация для AI-агента

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

• CLAUDE.md (или аналог для вашего агента) — файл с инструкциями: что это за проект, какие технологии, какие правила. Агент читает его автоматически при открытии проекта.
• Конфиги (.claude/settings.json) — разрешения и настройки поведения, которые мы создали выше.
• Скиллы — шпаргалки по конкретным технологиям. Агент подтягивает их, когда видит релевантную задачу.

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

Установка Node.js

Для того чтобы агент мог устанавливать свежие версии пакетов, ему нужен Node.js — среда для запуска JavaScript. JavaScript — это язык, на котором работает браузер, и на нём же будет написано наше приложение.

Мы установим Node.js через Vite+ — инструмент, который управляет версией Node.js, пакетным менеджером и инструментами сборки в одном месте. Он сам скачает нужную версию и настроит окружение.

Запустите команду установки:

user@computer:~/landing$ curl -fsSL https://vite.plus | bash

После установки нужно обновить настройки терминала, чтобы он увидел новые команды:

user@computer:~/landing$ source ~/.bashrc

Если вы используете zsh (по умолчанию на Mac), вместо этого выполните:

user@computer:~/landing$ source ~/.zshrc

Теперь установим последнюю версию Node.js:

user@computer:~/landing$ vp env install latest

Проверяем, что всё работает:

user@computer:~/landing$ vp help
user@computer:~/landing$ node --version
user@computer:~/landing$ npm --version

Если все три команды вывели версии без ошибок — всё готово. Теперь агент сможет запускать npm install и ставить актуальные версии пакетов.

Docker

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

Зачем это нам:

• Предсказуемость — проект работает на сервере ровно так же, как у вас на компьютере
• Чистота — не нужно ничего настраивать на каждом компьютере отдельно. Всё уже описано в конфигурации, Docker воспроизводит её одинаково на любой машине
• Простота — запуск, остановка, перемещение между серверами — всё делается универсальными командами
• Изоляция — если что-то пошло не так, контейнер можно удалить, и сервер останется чистым

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

Вот из чего состоит наш проект:

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

Переменные окружения

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

Для начала нам нужны логин и пароль для базы данных. Создайте файл .env в корне проекта (в папке landing) и впишите:

POSTGRES_USER=myuser
POSTGRES_PASSWORD=mypassword
POSTGRES_DB=landing

Замените myuser и mypassword на свои значения. Это локальная база данных на вашем компьютере, поэтому сложный пароль не обязателен — но и 123456 лучше не ставить.

.gitignore

.gitignore — это список файлов и папок, которые не должны попадать в историю изменений. Туда обычно добавляют секреты (.env), скачанные библиотеки (node_modules/), результаты сборки — в общем, всё, что напрямую не относится к тому, что конкретно вы написали.

Убедитесь, что .env есть в файле .gitignore, чтобы пароли не попали в репозиторий. Если .gitignore ещё нет — агент создаст его при создании проекта.

.env.example

Рядом с .env создайте файл .env.example — это шаблон с теми же переменными, но без реальных значений:

POSTGRES_USER=
POSTGRES_PASSWORD=
POSTGRES_DB=

Этот файл, в отличие от .env, можно и нужно хранить в репозитории. Он показывает, какие переменные нужны для запуска проекта, но не раскрывает их значения.

Некоторые агенты (например, Cursor) не умеют читать и редактировать .env-файлы и могут игнорировать .env.example — это ограничение сделано из соображений безопасности. Claude Code может работать с любыми файлами. В любом случае .env.example полезен для людей: если кто-то (или вы сами через полгода) откроет проект — сразу будет понятно, какие переменные нужно заполнить.

Создание приложения

Попросите вашего агента:

Создай приложение в Docker из трёх сервисов:
- Nginx — принимает запросы и направляет в нужные сервисы
- Приложение — fullstack-сайт на Node.js, React, TanStack и Prisma ORM
- База данных PostgreSQL

Пока что — с простой приветственной страницей,
так чтобы после запуска Docker-контейнеров сайт
был доступен по адресу http://localhost

Используй переменные из .env файла
для подключения к базе данных.
Добавь .env в .gitignore.
Обнови .env.example с новыми переменными.

Важно: сначала создай пустой package.json,
потом установи пакеты через npm install.
НЕ прописывай версии вручную — мне нужны
самые свежие.

Функциональность (формы, события, Telegram) мы добавим позже.

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

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

Зачем в промпте мы отдельно просим установить пакеты через npm install? npm — это стандартный менеджер пакетов Node.js. Интернет работает на JavaScript, и огромное количество готовых решений уже написано за нас — всем этим управляет npm. Мы просим агента отдельно установить свежие пакеты, потому что агенты очень любят ставить те версии, которых больше всего было в их обучающих данных, — и зачастую они устаревшие. Мы хотим использовать самые свежие — с закрытыми уязвимостями и исправленными ошибками.

Проверяем:

user@computer:~/landing$ docker compose up --build

В результате после запуска контейнеров мы должны получить рабочий сайт по адресу http://localhost. Ctrl+C в том же окне терминала остановит контейнеры.

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

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

[+] Building 2.8s (10/18)
 => ERROR [build 4/8] RUN npm ci             1.5s
------
 > [build 4/8] RUN npm ci:
 npm error code EUSAGE
 npm error
 npm error `npm ci` can only install packages
 when your package.json and package-lock.json
 are in sync. Please update your lock file
 with `npm install` before continuing.
 npm error
 npm error Missing: @emnapi/core@1.9.2
 ...
------
failed to solve: process "/bin/sh -c npm ci"
did not complete successfully: exit code: 1

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

Проверяем результат

Должно получиться что-то похожее. Конечно, у вас будет свой вариант, но главное — страница открывается и мы её видим.

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

В docker-compose.yml должны быть три сервиса, а у базы данных — отдельный volume. Volume — это место на вашем компьютере, где хранятся файлы базы данных. Без него при перезапуске контейнера все данные потеряются.

Всё на месте? Попросите агента сделать коммит.

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

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

Когда делать коммиты:

• После окончания работы — обязательно
• Перед важными изменениями — чтобы можно было откатиться
• Во время работы — хотя бы раз в 10 минут
• Просто так — лишний коммит не повредит

Что дальше

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