ИИ код: как найти причину, если проект не запускается, за 5 шагов

Почему проект не запускается и чем здесь поможет ИИ?

Фраза «не запускается проект» описывает результат, но не причину. Для ИИ это слишком мало данных. Он не знает:

• из какой папки запущена команда;
• какую команду ты выполнил;
• что именно напечатал терминал;
• на какой строке возник сбой;
• менялся ли проект перед ошибкой.

В справке Claude Code для собственных runtime-ошибок предлагают сопоставить сообщение терминала с разделом диагностики:

В Error reference Anthropic предлагает сопоставлять сообщение из терминала с разделом диагностики собственных runtime-ошибок Claude Code.

"Match the message you see in your terminal to a section below." Anthropic, Error reference

Поэтому не начинай с пересказа вроде «страница пустая» или «сервер не отвечает». Сначала повтори запуск и сохрани весь вывод. Последняя строка может быть следствием, поэтому проверь полный вывод и строки выше. Среди возможных причин бывают missing script, Cannot find module, неправильный порт или отказ браузера отправить запрос.

ИИ для работы с кодом полезен в трёх местах:

1. читаешь вместе с ним структуру проекта;
2. сопоставляешь сообщение ошибки с командами и файлами;
3. проверяешь гипотезу повторным запуском.

ИИ не доказывает исправность словами «готово». Доказательство здесь проще: команда завершилась без прежней ошибки, сборка прошла, тесты прошли или API вернул ожидаемый ответ.

Из-за каких ошибок проект не запускается?

Неправильная папка или package.json

Коротко: Если команда запуска выполняется не из каталога с нужным package.json, npm может не найти скрипт или зависимости.

Убедись, что команда выполняется в каталоге нужного приложения и используется правильный package.json; в monorepo каталог запуска может отличаться от корня репозитория. В такой ситуации npm может показать:

npm ERR! Missing script: "start"

Сначала проверь текущий каталог и содержимое package.json. Не подставляй наугад npm start: команда зависит от проекта, package manager, фреймворка и среды.

Нет зависимости

Коротко: Ошибка Cannot find module обычно означает, что зависимость не установлена или команда выполняется не из каталога с правильным package.json.

Ошибка выглядит так:

Error: Cannot find module 'react'

Сообщение Cannot find module означает «модуль не найден». Причина может быть в том, что зависимости ещё не установлены или проект запускается не из каталога, где лежит нужный package.json. Сверь текущий каталог, lock-файл и результат установки зависимостей из корня проекта.

Фронтенд не видит сервер

Коротко: Если интерфейс загружается, но запросы не проходят, сначала сравни состояние сервера, его порт и адрес API в клиенте.

Интерфейс может открываться, но запрос к API не проходит. Например, клиент обращается к серверу, который не запущен, или отправляет запрос на неправильный порт. В терминале и браузере это часто выглядит как отказ соединения.

Не меняй сразу весь код. Сначала проверь по шагам:

1. Убедись, что сервер запущен.
2. Узнай, на каком порте он слушает.
3. Сверь этот порт с адресом, к которому обращается клиент.
4. Проверь, что путь API совпадает.

Переменная окружения не загрузилась

Коротко: Проверь имя переменной, правила её публикации сборщиком и перезапусти dev-сервер после изменения .env.

Способ чтения переменных зависит от сборщика; для Vite используется import.meta.env. В Vite переменная для клиентского кода должна начинаться с VITE_ и читаться через import.meta.env.

.env:

VITE_API_URL=http://localhost:3001

Клиентский код:

const apiUrl = import.meta.env.VITE_API_URL

Такой вариант в браузерной части Vite обычно не сработает:

const apiUrl = process.env.API_KEY

После изменения .env dev-сервер нужно перезапустить. Секретные ключи нельзя помещать в VITE_*: такие значения попадают в клиентский бандл.

Порт занят

Коротко: Ошибка EADDRINUSE означает, что выбранный порт уже занят другим процессом; найди его перед изменением конфигурации.

Терминал может показать:

Error: listen EADDRINUSE: address already in use :::3000

Другой процесс уже использует этот порт, поэтому сообщение означает «адрес уже занят». Частый вариант - предыдущий запуск приложения остался в другом терминале. Сначала найди процесс, потом заверши именно его.

macOS или Linux:

lsof -i :3000
kill PROCESS_ID

Windows:

netstat -ano | findstr :3000
taskkill /PID YOUR_PROCESS_ID /F

Или назначь приложению другой порт.

CORS блокирует запрос

Коротко: При CORS-сбое сервер должен разрешить фактический origin клиента, либо клиент должен обращаться к API через настроенный proxy.

React может работать на условном localhost:<CLIENT_PORT>, а API - на localhost:<API_PORT>. Для браузера разные порты означают разные origins. Сервер должен разрешить запрос через CORS-заголовки.

MDN описывает причину так:

MDN объясняет, что браузеры ограничивают междоменные HTTP-запросы, которые инициируют скрипты, из соображений безопасности.

"For security reasons, browsers restrict cross-origin HTTP requests initiated from scripts." MDN, Cross-Origin Resource Sharing

На сервере разреши конкретный origin:

import cors from "cors"

app.use(cors({
  origin: "http://localhost:<CLIENT_PORT>"
}))

Либо используй proxy dev-сервера и обращайся к API по относительному адресу:

fetch("/api/users")

Не отключай защиту целиком, пока не проверил фактические порты, путь endpoint и заголовок Access-Control-Allow-Origin.

Как ИИ читает код проекта?

Открой терминал в папке проекта:

cd /path/to/your/project
claude

В Quickstart Anthropic описывает открытие терминала в каталоге проекта и запуск Claude Code: Quickstart.

Следующая деталь важнее самого запуска:

В Quickstart Anthropic указывает, что Claude Code читает файлы проекта по мере необходимости, поэтому весь код не обязательно вставлять в чат: Quickstart.

То есть не копируй в окно сотни строк подряд. Сначала дай ИИ доступ к папке и Контекст проекта: команду, лог и нужные файлы. Затем попроси его посмотреть конкретные файлы: package.json, конфигурацию сборщика, точку входа, клиентский запрос или серверный обработчик.

Claude Code может читать файлы и запускать команды из этой папки, если ты дал ему соответствующие разрешения. Наличие CLAUDE.md не означает, что каждая инструкция будет выполнена.

При запуске claude из каталога Claude Code может получить доступ к проектным инструкциям CLAUDE.md, если файл доступен в соответствующем контексте и разрешениях:

• проекту;
• терминалу;
• состоянию Git;
• файлу CLAUDE.md.

CLAUDE.md хранит инструкции проекта. Например, в нём можно указать существующую команду проверки и запрет на изменения без согласования. Но текстовый файл не заменяет фактический запуск команды: правило может быть загружено, а отдельная инструкция не выполнена.

Как передать ИИ проект и сообщение об ошибке?

1. Открой корень проекта.

   Перейди в каталог, где лежат package.json, исходники и CLAUDE.md, если файл инструкций есть.

   Проверь, что команда выполняется именно там:

   bash

   Скопировать

   pwd
   ls

   В Windows вместо pwd можно использовать:

   powershell

   Скопировать

   Get-Location

2. Запиши точную команду.

   Не пересказывай запуск своими словами. Сохрани команду буквально: например, npm run dev, npm run build или другую команду из проекта.

   Универсальной команды для всех проектов нет. Она зависит от package manager, фреймворка и среды.

3. Сохрани полный вывод.

   Запусти проверку и одновременно запиши лог в файл:

   bash

   Скопировать

   npm run build 2>&1 | tee build.log

   В Windows PowerShell можно сохранить вывод так:

   powershell

   Скопировать

   npm run build 2>&1 | Tee-Object build.log

   Отметь первое настоящее сообщение об ошибке. Не удаляй строки выше него.

4. Передай контекст ИИ.

   Внутри Claude Code напиши, что произошло, и попроси изучить проект до правки.

   Найти первопричину ошибки запускаСкопировать промпт

   Изучи текущий проект и файл CLAUDE.md, если он есть.
   Найди package.json, точку входа и команду запуска.
   Сопоставь команду с полным выводом build.log.
   Отдели первый настоящий сбой от последующих симптомов.
   Ничего не меняй.
   Сначала покажи:
   1. найденную первопричину;
   2. файл и строку, связанные с ошибкой;
   3. команду, которой ты проверишь гипотезу;
   4. минимальную правку после моего согласования.

5. Передай лог через stdin.

   Если хочешь отправить сохранённый файл в одноразовый запрос, используй pipe:

   bash

   Скопировать

   cat build.log | claude -p "Find the first real error, explain its root cause, and propose the smallest fix."

   Anthropic документирует режим claude -p для одноразового запроса и передачу содержимого через стандартный ввод. Не отправляй в лог секретные ключи и значения переменных окружения.

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

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

Как читать результат проверки проекта с помощью ИИ?

Я раскладываю ответ ИИ на четыре части: наблюдение, гипотезу, проверку и действие.

1. Наблюдение. Что буквально произошло в терминале или браузере.
2. Гипотеза. Почему это могло произойти.
3. Проверка. Какая команда или чтение файла отличит причину от догадки.
4. Действие. Какую одну правку ИИ предлагает внести.

Если ответ начинается с большого списка возможных причин, останови ИИ. Попроси выбрать первую гипотезу и показать доказательство. Например, ошибка missing script: start должна проверяться содержимым package.json, а не заменой нескольких файлов.

До исправления попроси изучить структуру проекта:

what does this project do?
what technologies does this project use?
where is the main entry point?

Эти команды помогают найти точку входа и не менять случайный файл.

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

curl -i http://localhost:<API_PORT>/api/health
curl -i -X POST http://localhost:<API_PORT>/api/login

Затем выведи реальное тело ответа в клиенте:

const response = await fetch("/api/login")
const body = await response.json()
console.log(body)

Сравни фактическое имя поля с тем, которое ищет клиентский код. ИИ мог собрать сервер, возвращающий token, а клиент мог искать accessToken. Внешне это похоже на поломку API, хотя сервер уже отвечает.

Как попросить ИИ исправить ошибку запуска?

Безопасный запрос должен ограничивать четыре вещи:

• причину;
• объём изменения;
• момент применения;
• проверку после правки.

Изучи текущую структуру проекта, package.json, CLAUDE.md и полный вывод последней команды.
Определи одну первопричину, которая объясняет первый настоящий сбой.
Предложи минимальную правку.
Не меняй файлы и не переписывай архитектуру до моего согласования.
Укажи точный файл, строки и ожидаемый эффект.
После согласования внеси только эту правку.
Затем выполни существующую команду проверки проекта и покажи полный вывод.
Не называй задачу исправленной без фактического результата команды.

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

В Claude Code есть hooks: их можно настроить для автоматического запуска форматирования, линтера или тестов; результат hook нужно интерпретировать по конфигурации проекта. Сначала узнай, какая проверка уже есть в проекте.

В документации Anthropic hooks описаны как способ автоматически запускать shell-команды при изменении файлов, завершении задач или ожидании ввода, например для форматирования и проверок: Automate actions with hooks.

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

/export diagnosis-YYYY-MM-DD.txt

Она сохраняет текущую беседу, запросы ИИ и выводы инструментов в обычный текстовый файл.

Что делать, если после исправления проект всё ещё не запускается?

ИИ игнорирует CLAUDE.md

Коротко: Наличие CLAUDE.md не доказывает выполнение его правил, поэтому проверь расположение файла и результат каждой обязательной команды.

Загрузка файла не гарантирует выполнение каждой инструкции. В issue Anthropic описан симптом:

Issue #18454 приведён как пример обсуждения поведения инструкций CLAUDE.md и пользовательских skill-файлов, а не как доказательство общего правила: Issue #18454.

Проверь три вещи:

cd path/to/project
claude

В этом примере проектный CLAUDE.md лежит в корне проекта:

project/
  CLAUDE.md
  package.json
  src/

Внутри сессии проверь доступные memory-файлы:

/memory

Правила делай короткими и проверяемыми:

Before changing code:
1. Read package.json.
2. Run the existing test or build command.
3. Show the exact command and its result.
4. Do not claim success without running the command.

Фраза «запомни это» слабее файла и фактической проверки. Важное правило должно находиться в проекте или проверяться командой.

Клиент и сервер перепутаны

Коротко: Запускай клиент и сервер как отдельные слои и проверяй сервер через API до подключения браузерного интерфейса.

Раздели их на два слоя:

client/
  package.json
  src/

server/
  package.json
  index.js

Для каждого слоя отдельно выполни доступные команды:

npm install
npm run build
npm run start

Сначала проверь сервер через curl, потом подключай клиент. Так ты увидишь, где именно возникает сбой: при запуске сервера, при запросе или при чтении ответа в браузере.

Новый сеанс потерял историю

Коротко: Верни прежний сеанс через claude --continue или claude --resume, а если это невозможно, передай сохранённый отчёт явно.

Новый сеанс начинается без истории предыдущей диагностики. Верни прежнюю сессию:

claude --continue

Или:

claude --resume

Документация Anthropic уточняет:

Документация Anthropic уточняет, что claude --continue и claude --resume возвращают прежнюю сессию и продолжают разговор.

• Anthropic, How Claude Code works

Если старую сессию продолжить нельзя, передай отчёт явно:

cat diagnosis-2026-08-19.txt | claude -p \
  "Continue the diagnosis. Re-check the original root cause against the current project files."

Auto memory может сохранить команду сборки, найденную причину или особенность окружения. Но Claude сам выбирает, что туда записать. Полный журнал лучше сохранять через /export.

Вопросы и ответы