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

> Проект не запускается, а ИИ предлагает переписать половину файлов? Покажи ему точную команду, полный лог и структуру проекта. Так ты найдёшь первопричину и проверишь исправление без лишних правок.

Источник: https://vibeceh.ru/guides/ii-kod-najti-prichinu-pochemu-proekt-ne-zapuskaetsya
Автор: Сергей Мазур · опубликовано 2026-08-19

Не запускается проект? Я начинаю с четырёх вещей: каталога проекта, точной команды, полного вывода терминала и первого настоящего сообщения об ошибке. Так ИИ для диагностики кода сможет найти причину, предложить одну небольшую правку, проверить запуск и сохранить отчёт, к которому легко вернуться при следующем сбое.

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

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

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

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

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

В Error reference Anthropic предлагает сопоставлять сообщение из терминала с разделом диагностики собственных runtime-ошибок Claude Code.
> "Match the message you see in your terminal to a section below." Anthropic, [Error reference](https://code.claude.com/docs/en/errors)

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

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

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

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

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

Частые причины незапуска связаны не только с кодом. Команда может выполняться не в той папке, в `package.json` может отсутствовать нужный скрипт, зависимости могут быть не установлены, сервер может не работать, порт может быть занят, а браузерный запрос блокирует CORS. Переменные окружения тоже зависят от сборщика и способа запуска.

![Кот в шоке рассматривает карточки с причинами сбоя запуска проекта.](https://s3.regru.cloud/crossmark/statejnik/images/guides/ii-kod-najti-prichinu-pochemu-proekt-ne-zapuskaetsya/kadr-1.webp)

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

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

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

```text
npm ERR! Missing script: "start"
```

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

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

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

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

```text
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`:

```env
VITE_API_URL=http://localhost:3001
```

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

```js
const apiUrl = import.meta.env.VITE_API_URL
```

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

```js
const apiUrl = process.env.API_KEY
```

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

### Порт занят

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

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

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

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

macOS или Linux:

```bash
lsof -i :3000
kill PROCESS_ID
```

Windows:

```powershell
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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS)

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

```js
import cors from "cors"

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

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

```js
fetch("/api/users")
```

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

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

Claude Code запускается из каталога проекта и читает файлы по мере необходимости. Вручную вставлять весь код в чат не требуется. При запуске из папки Claude Code может читать доступные файлы и выполнять разрешённые команды, включая проверку состояния Git и чтение `CLAUDE.md`, поэтому сопоставляет ошибку со структурой проекта только в пределах выданных разрешений.

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

```bash
cd /path/to/your/project
claude
```

В Quickstart Anthropic описывает открытие терминала в каталоге проекта и запуск Claude Code: [Quickstart](https://code.claude.com/docs/en/quickstart).

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

В Quickstart Anthropic указывает, что Claude Code читает файлы проекта по мере необходимости, поэтому весь код не обязательно вставлять в чат: [Quickstart](https://code.claude.com/docs/en/quickstart).

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

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

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

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

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

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

Открой терминал в корне проекта, зафиксируй точную команду запуска, сохрани полный вывод и отметь первое сообщение, которое объясняет сбой. См. [журнал решений Claude Code](/guides/claude-code-zhurnal-resheniy-dlya-proekta). Затем передай ИИ каталог, лог, `package.json`, инструкции `CLAUDE.md` и изменения перед ошибкой. Не сокращай вывод до последней строки: в ней часто остаётся только следствие.

![Собака с поднятой лапой стоит рядом с цепочкой шагов передачи проекта и полного лога ИИ.](https://s3.regru.cloud/crossmark/statejnik/images/guides/ii-kod-najti-prichinu-pochemu-proekt-ne-zapuskaetsya/kadr-2.webp)

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

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

   ```bash
   pwd
   ls
   ```

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

   ```powershell
   Get-Location
   ```

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

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

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

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

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

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

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

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

   

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

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

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

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

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

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

Отделяй симптом от причины и проверяй каждую гипотезу строкой ошибки или выводом команды. Для проверки diff см. [разбор Claude Code](/guides/claude-code-prosit-agenta-pokazat-diff-do-pravki). Уверенное объяснение ИИ не доказывает, что проект исправен. Перед правкой изучи структуру и точку входа, а для связки клиента с сервером сравни реальный ответ API с полем, которое ищет клиентский код.

![Кот одобрительно поднимает лапу возле схемы проверки ответа API и полей token и accessToken.](https://s3.regru.cloud/crossmark/statejnik/images/guides/ii-kod-najti-prichinu-pochemu-proekt-ne-zapuskaetsya/kadr-3.webp)

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

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

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

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

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

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

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

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

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

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

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

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

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

Попроси ИИ найти одну первопричину, предложить минимальную правку и не трогать остальные файлы. Сначала согласуй изменение, затем примени его и запусти команду проверки. Формулировка вроде `fix the build error` подходит для конкретной задачи. ИИ для редактирования кода должен получить критерий успеха: реальный вывод сборки, линтера, теста или запуска. Такой запрос подходит для сценария «ИИ для редактирования кода» при явно указанном критерии успеха.

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

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

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

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

В документации Anthropic hooks описаны как способ автоматически запускать shell-команды при изменении файлов, завершении задач или ожидании ввода, например для форматирования и проверок: [Automate actions with hooks](https://code.claude.com/docs/en/hooks-guide).

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

```text
/export diagnosis-YYYY-MM-DD.txt
```

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

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

Если запуск снова падает, не разрешай ИИ переписывать проект целиком. Контекст между сессиями разобран в [инструкции по Git](/guides/claude-code-peredacha-zadachi-mezhdu-sessiyami-bez-poteri-konteksta). Проверь загрузку `CLAUDE.md`, раздели клиент и сервер, сравни реальный ответ API с ожиданием клиента и восстанови прежний контекст через `claude --continue` или `claude --resume`. Отдельный отчёт надёжнее auto memory, потому что память сохраняет сведения выборочно.

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

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

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

Issue #18454 приведён как пример обсуждения поведения инструкций `CLAUDE.md` и пользовательских skill-файлов, а не как доказательство общего правила: [Issue #18454](https://github.com/anthropics/claude-code/issues/18454).

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

```bash
cd path/to/project
claude
```

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

```text
project/
  CLAUDE.md
  package.json
  src/
```

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

```text
/memory
```

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

```md
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 до подключения браузерного интерфейса.

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

```text
client/
  package.json
  src/

server/
  package.json
  index.js
```

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

```bash
npm install
npm run build
npm run start
```

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

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

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

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

```bash
claude --continue
```

Или:

```bash
claude --resume
```

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

Документация Anthropic уточняет, что `claude --continue` и `claude --resume` возвращают прежнюю сессию и продолжают разговор.
> - Anthropic, [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works)

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

```bash
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`.

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

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

Причину ищи в точном выводе терминала. Проверь текущую папку, `package.json`, зависимости, сервер, порт, переменные окружения и CORS. Не ограничивайся описанием «ничего не работает»: передай ИИ полную команду и полный лог, включая строки до последней ошибки.

Повтори запуск и сохрани вывод в файл. Затем открой Claude Code из корня проекта, передай ему лог и попроси найти первый настоящий сбой без изменений. После согласования одной правки снова выполни ту же команду и сохрани результат в диагностический отчёт.

Claude Code читает доступные файлы проекта из каталога, где запущен, и может выступать как ИИ, работающий с кодом. Вставлять весь код вручную не требуется. Для диагностики дай доступ к проекту, терминалу, Git и `CLAUDE.md`, затем попроси найти `package.json`, точку входа и файл, связанный с сообщением ошибки.

В сценарии «ии для описания кода» попроси ИИ описать только участок, связанный с ошибкой. Сначала укажи команду, полный вывод и файл, который нужно изучить. Затем попроси объяснить назначение участка, входные данные, результат и место, где фактическое поведение расходится с ожидаемым.

Передай ИИ точную строку ошибки и контекст файла. Попроси отделить наблюдение от гипотезы и показать команду проверки. Объяснение без запуска команды остаётся предположением, поэтому после разбора сверяй вывод терминала с тем, что предсказал ИИ.

Сформулируй ограниченную задачу: найти одну первопричину, предложить минимальную правку, не менять лишние файлы, дождаться согласования и выполнить проверочную команду. Не проси сразу «починить всё»: такая формулировка не задаёт границы изменения.

Передай ИИ структуру проекта, `package.json`, точную команду, полный лог и инструкции `CLAUDE.md`. Попроси найти причину по первому настоящему сообщению. После анализа запусти сборку, линтер, тест или команду запуска самостоятельно и сохрани фактический результат.

Для диагностики нужны конкретные команды проекта, а не универсальный список: ИИ оценивает результаты кода только по фактическому выводу команды. Примеры из рабочего процесса: `npm run build`, `npm run start`, `curl -i http://localhost:3001/api/health`, `cat build.log | claude -p "..."`, `claude --continue`, `claude --resume` и `/export diagnosis.txt`. Команда запуска зависит от самого проекта.

- [Quickstart - Claude Code Docs](https://code.claude.com/docs/en/quickstart)
- [How Claude Code works - Claude Code Docs](https://code.claude.com/docs/en/how-claude-code-works)
- [CLI reference - Claude Code Docs](https://code.claude.com/docs/en/cli-usage)
- [Error reference - Claude Code Docs](https://code.claude.com/docs/en/errors)
- [Automate actions with hooks - Claude Code Docs](https://code.claude.com/docs/en/hooks-guide)
- [Manage sessions - Claude Code Docs](https://code.claude.com/docs/en/sessions)
- [How Claude remembers your project - Claude Code Docs](https://code.claude.com/docs/en/memory)
- [Env Variables and Modes - Vite](https://vite.dev/guide/env-and-mode)
- [Cross-Origin Resource Sharing - MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS)
- [Cross-Origin Resource Sharing configuration - MDN](https://developer.mozilla.org/en-US/docs/Web/Security/Practical_implementation_guides/CORS)
- [Issue #18454 - anthropics/claude-code](https://github.com/anthropics/claude-code/issues/18454)
- [Issue #21376 - anthropics/claude-code](https://github.com/anthropics/claude-code/issues/21376)