От нуля до работающего AI-продукта с оплатой за 10 недель — Рома РайтРаздел 7 · урок 1 из 5
12345уроки раздела 7
Раздел 7. Отладка, рефакторинг, деплой на Railway и личный сайт-визитка

Диагностика и лечение пяти частых поломок — порты, кириллица, ENV, гидрация и CSS

≈ 8 минРома Райт

«Я нажал одну кнопку, а экран покраснел и высыпал сотню непонятных английских строчек — как вообще понять, что сломалось?» С такого вопроса начинается путь почти каждого, кто впервые запускает свой проект с ИИ-агентами и не имеет за плечами диплома программиста.

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

Почему ошибки в AI-разработке неизбежны и где проходит твоя зона ответственности

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

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

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

Проверяй уверенность агента

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

Где искать правду о поломке: терминал VS Code против браузерной консоли

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

Отсюда простое разделение, откуда забирать текст ошибки:

  1. Серверные сбои, база данных и сборка — терминал VS Code. Если не стартует проект, падает запрос к PostgreSQL или OpenAI, или вместо страницы вылетает красная ошибка 500, причина почти всегда уже напечатана в нижней панели терминала, где запущен dev-сервер.
  2. Поломки кнопок, запросов и интерфейса — панель разработчика в браузере. Нажми правую кнопку мыши на странице и выбери «Посмотреть код» (или нажми клавишу F12), затем открой вкладку Console и вкладку Network. Красные строчки в Console показывают клиентские сбои JavaScript, а Network подсказывает, какой именно запрос к API вернул ошибку вместо данных.
  3. Визуальные перекосы — скриншот или Playwright. Если ничего не упало с красным текстом, но уехали отступы, наложился текст или кнопка не нажимается, текстом объяснять долго: проще сделать скриншот проблемного места или запустить проверку через Playwright.

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

Пять главных поломок новичка и их экспресс-лечение на практике

Шпаргалка по пяти частым ошибкам среды и настроек: порт 3000, кириллица в пути, Node.js, .env и Prisma.

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

Первая поломка — занятый порт 3000 (EADDRINUSE). Ты правишь интерфейс, сохраняешь файлы, обновляешь страницу по адресу localhost:3000, а на экране ничего не меняется, будто агент вообще не трогал код. На деле в фоне завис старый процесс dev-сервера или запустилась вторая копия приложения на порту 3001, и ты смотришь не на тот адрес; лечится остановкой процессов через Ctrl+C в терминале, принудительным освобождением порта или перезапуском сервера на свободном порту.

Вторая поломка — кириллица или пробелы в пути к папке. Проект может спокойно работать неделю, а потом внезапно отказаться запускаться после установки новой библиотеки или запуска скрипта сборки. Почти всегда виновата папка вроде «Рабочий стол» или «Мои проекты» в пути к репозиторию — перенеси весь код в латинскую директорию без пробелов, например Documents/brainapp.

Третья поломка — переменные окружения .env и остановленная база. Интерфейс BrainApp открывается, кнопки нажимаются, но вход по паролю не пускает, а OpenAI API молчит. Причины обычно три: ты добавил ключ в .env.local, но забыл перезапустить dev-сервер, поставил лишние пробелы вокруг знака =, либо забыл поднять локальную базу (например, при работе с локальным Docker вылетает connection refused или The table does not exist, если не выполнен прогон схемы).

Четвёртая поломка — ошибки гидратации в Next.js (Hydration failed). Так фреймворк ругается, когда сервер сгенерировал одну разметку страницы, а браузер на твоём компьютере посчитал другую — классический пример в BrainApp, когда на сервере одно часовое время или формат даты, а в браузере другое, либо когда внутри карточек работают сложные анимации и перетаскивание drag-and-drop. Обычным скриншотом такой баг почти не объяснить: нужно скопировать полный красный текст предупреждения из Console и попросить агента вынести зависимую от браузера логику в клиентский рендер.

Пятая поломка — конфликты CSS и «подсунутый» дефолтный UI. ИИ-агенты обожают забывать, что в проекте уже есть свои красивые стили, и рисовать новые компоненты поверх старых. В том же Yoolip.ai агент с завидным упорством подсовывал стандартный браузерный календарь выбора дат вместо нашего кастомного дизайна, пока мы жёстко не закрепили запрет в CLAUDE.md.

Если после правок в BrainApp ты подозреваешь, что порт 3000 занят, кэш сборки .next/ застрял на старой версии, а схема базы данных рассинхронизировалась, не переустанавливай проект с нуля — выполни короткий сброс в терминале VS Code.

# Останавливаем текущий процесс в терминале клавишами Ctrl+C, затем освобождаем порт 3000
npx kill-port 3000
# Удаляем кэш сборки Next.js, синхронизируем схему Prisma и поднимаем сервер заново
rm -rf .next && npx prisma db push && npm run dev

Первая команда принудительно закрывает зависший процесс на порту 3000, который мешал видеть свежие изменения. Вторая удаляет кэшированную папку .next/, проталкивает актуальную схему schema.prisma в базу данных (эту часть используй, если ты менял таблицы или видишь ошибку отсутствующей таблицы) и чисто поднимает локальный сервер. На Windows без установленного rm просто попроси Claude Code удалить кэш .next/ и перезапустить dev-сервер — он подставит синтаксис под твою систему.

Не забудь про кэш браузера

Иногда код и сервер уже обновились, а браузер упорно показывает старую картинку или старый редирект. Прежде чем переделывать компонент с агентом, сделай жёсткую перезагрузку страницы без кэша: Ctrl+Shift+R на Windows или Command+Shift+R на Mac.

Формула идеального баг-репорта для Claude Code и шпаргалка быстрого поиска

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

Сильный баг-репорт для агента всегда состоит из трёх деталей: скриншота сломанного экрана (если баг визуальный), точного текста ошибки из терминала VS Code или браузерной Console и одного предложения о том, что ты нажал и что ожидал увидеть. Чтобы не придумывать формулировку каждый раз заново, используй готовый шаблон прямо в диалоге с Claude Code.

Исправь следующие ошибки в проекте:
[вставь полный текст ошибки из терминала VS Code или консоли браузера]

Что я делал перед сбоем: [1–2 предложения: какую кнопку нажал и что должно было открыться].
Дополнительно:
- Сначала проверь причину в коде и подтверди, что это не гипотеза, а точный источник сбоя.
- Проверь, не вызвала ли эта ошибка побочные эффекты в соседних файлах.
- После исправления запусти dev-сервер и убедись, что ошибка полностью ушла.
- Дай короткий отчёт: что было сломано, что изменено и какие файлы затронуты.

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

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

Симптом сбояВероятная причинаГде проверятьЧто сказать или сделать для Claude Code
Правки не видны, localhost:3000 висит или стартует на 3001Порт 3000 занят старым процессом (EADDRINUSE)Терминал VS Code«Освободи порт 3000, очисти .next/ и перезапусти npm run dev»
Проект внезапно падает при запуске или сборкеКириллица или пробелы в пути к папке проектаПолный путь в проводнике или терминалеПеренести папку в латинский путь без пробелов вроде Documents/brainapp
Сайт открывается, но вход, OpenAI или БД не отвечаютНе подгружен .env.local, пробелы у =, не запущена БДТерминал VS Code + файл .env.local«Проверь чтение переменных окружения, перезапусти dev-сервер и проверь связь с БД»
Предупреждение Hydration failed на датах, анимации или drag-and-dropРассинхрон серверного HTML и клиентского рендераВкладка Console в DevTools (F12)Скинуть текст из Console и попросить аудит гидратации проблемного компонента
Уехали отступы, кнопки в две строки или вылез дефолтный UIКонфликт классов Tailwind или забытый стиль компонентаЭкран браузера + правила в CLAUDE.mdПриложить скриншот, ссылку на нужный стиль и закрепить правило в CLAUDE.md