«Я нажал одну кнопку, а экран покраснел и высыпал сотню непонятных английских строчек — как вообще понять, что сломалось?» С такого вопроса начинается путь почти каждого, кто впервые запускает свой проект с ИИ-агентами и не имеет за плечами диплома программиста.
Первая реакция новичка — паника и мысль, что либо нейросети ни на что не годятся, либо он сам не справляется. Но правда проще: любой проект на старте будет ломаться, и твоя задача — не избегать ошибок любой ценой, а научиться быстро снимать симптомы и отдавать агенту точные улики.
Почему ошибки в AI-разработке неизбежны и где проходит твоя зона ответственности
В первые три месяца моего вайб-кодинга кастомные трек-ссылки, которые я собрал для YouTube-канала, падали чуть ли не каждый день. Мы теряли трафик, я не понимал, куда смотреть, и всерьёз думал, что без программистов ничего стабильного не построишь.
Бывали истории и жёстче: однажды агент без предупреждения снёс всю базу данных моего внутреннего приложения, а бэкапа у меня не было. Если бы это был коммерческий сервис для клиента, ошибка стоила бы очень дорого — именно поэтому мы и тренируемся сначала на проектах для себя, а уже потом идём к заказчикам и в собственный SaaS.
Твоя роль здесь — не сидеть с красными глазами над строчками TypeScript и не пытаться чинить код руками. Ты управляешь процессом как руководитель: формулируешь задачу, собираешь контекст ошибки, ставишь диагноз вместе с агентом и проверяешь, действительно ли симптом исчез.
Claude Code часто формулирует правдоподобную догадку и подаёт её так уверенно, будто это доказанный факт. Если агент предлагает переписать полпроекта без проверки, всегда спрашивай прямо: «Это твоя гипотеза или ты точно проверил это по файлам и логам? Если не уверен — сначала проведи аудит».
Где искать правду о поломке: терминал VS Code против браузерной консоли
Когда приложение перестаёт работать, паниковать бессмысленно — нужно просто посмотреть в правильное окно. У любого веб-проекта на Next.js две стороны жизни: серверная часть на твоём компьютере и интерфейс, который рисуется в браузере.
Отсюда простое разделение, откуда забирать текст ошибки:
- Серверные сбои, база данных и сборка — терминал VS Code. Если не стартует проект, падает запрос к PostgreSQL или OpenAI, или вместо страницы вылетает красная ошибка 500, причина почти всегда уже напечатана в нижней панели терминала, где запущен dev-сервер.
- Поломки кнопок, запросов и интерфейса — панель разработчика в браузере. Нажми правую кнопку мыши на странице и выбери «Посмотреть код» (или нажми клавишу F12), затем открой вкладку Console и вкладку Network. Красные строчки в Console показывают клиентские сбои JavaScript, а Network подсказывает, какой именно запрос к API вернул ошибку вместо данных.
- Визуальные перекосы — скриншот или 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 |