Environment diagnostics

1. «Всё сломалось, помоги» — это не задача

Когда проект не стартует, особенно вечером, особенно после третьей кружки кофе, очень хочется написать что-нибудь в духе: «Claude, всё сломалось, помоги». Фраза сообщает о вашем настроении, но почти ничего — о состоянии проекта. Claude не экстрасенс. Он не видит ваш shell, не угадывает версию Java по вибрациям терминала и не читает лог силой воли. Ему нужны наблюдаемые сигналы.

В delivery-контуре это и есть контракт: явный вход, узкая задача, проверяемый ответ. Ломается он там, где вместо данных вы отдаёте чистую эмоцию.

Сравните:

Плохо:
«Проект не запускается. Почини».

Сильно:
«Commerce OS не стартует локально.
OS: macOS 15, shell: zsh.
Java и Node версии ниже.
Команда запуска: docker compose up.
Ниже — последние 40 строк лога backend.
Код пока не меняй: сначала назови вероятную причину и команду для проверки гипотезы».

Во втором варианте вы мыслите как инженер: отделяете симптом от догадки, ставите границу — сначала диагноз, потом правки. Факты вместо тумана — и Claude резко полезнее. Почти магия, только без магии.

2. Воспроизводимое окружение: «тот же результат», а не «примерно»

У воспроизводимого локального окружения очень простой смысл: другой человек берёт чистую копию репозитория, запускает те же команды и получает тот же результат. Не «примерно так же». Не «ну у меня-то работает». Не «если сначала перезагрузить Docker, потом выключить VPN, потом открыть IDE с левой ноги». Именно тот же — на той же последовательности шагов.

Для Commerce OS это особенно важно, потому что стек у проекта не игрушечный — Java 25, Spring Boot, Next.js, Node.js, PostgreSQL, Gradle плюс контейнерный baseline. Опишите хоть один слой размыто — и получите не setup, а домашнее животное «работает только у автора».

Ниже полезно держать простую карту того, что вообще должно совпадать.

docker compose up

Очень полезно начинать не с размышлений, а с короткого набора команд, который фиксирует среду на бумаге:

pwd                         # /projects/commerce-os
git status --short          # рабочее дерево чистое
./gradlew --version         # Gradle 9.5.1, Java 25
node -v                     # v24.x.x
docker compose ps           # видны сервисы postgres / backend / frontend

Если у вас Windows и PowerShell, конкретные команды могут отличаться. Но суть та же: зафиксировать среду так, чтобы её обсуждали без «ну у меня вроде всё нормально».

3. Соберите evidence до запроса — коротко и по делу

Хорошая диагностика почти всегда начинается не с правок, а со сбора evidence. И этого evidence не должно быть слишком много: не нужно кидать в Claude три тысячи строк лога в надежде, что он с любовью всё перечитает. Лучше короткий, но качественный набор сигналов. Обычно для локальной диагностики хватает вот такой карты:

На практике это выглядит примерно так:

java -version
node -v
docker --version
docker compose logs backend --tail=40
grep -n "SPRING_PROFILES_ACTIVE" .env.example

Большой лог без контекста — тяжёлый способ сказать «посмотри сам». А последние 40 строк вокруг падения — реальный диагностический артефакт.

4. EVIDENCE_LOG.md — один журнал вместо хаоса

Когда setup капризничает, evidence расползается: один лог в терминале, второй в скриншоте, третья мысль в голове, четвёртая в сообщении Claude, потерянном после /clear. Спасает старый добрый EVIDENCE_LOG.md, который вы начали вести раньше в курсе. Сегодня он нужен не для debugging runtime-логики, а для setup-evidence.

Хорошая практика — не заводить новый файл с красивым названием вроде SETUP_EVIDENCE.md, а добавить блок в уже знакомый журнал. Тогда у вас сохраняется один источник правды, и свежую сессию Claude можно открыть без танцев с пересказом прошлой жизни:

## Setup / доказательства воспроизводимости
- ОС и shell: macOS 15 / zsh
- Git state: clean working tree
- Версии: Java 25, Node 24, Docker 28
- Команда запуска: docker compose up
- Наблюдаемая ошибка: backend exits with code 1
- Фрагмент лога: Missing required property PAYMENT_PROVIDER_MODE
- README и `.env.example` проверены: да

Такой блок решает сразу несколько проблем: он дисциплинирует вас — вы не перепрыгиваете к правкам раньше времени, — а Claude получает структурированный контекст вместо потока сознания. А вернётесь завтра или передадите задачу — останется не «кажется, что-то было с Docker», а нормальный след расследования.

5. Diagnostic request: сначала диагноз, потом решение

Одна из лучших привычек в работе с AI — вслух называть, какая сейчас фаза. Нужен диагноз — так и просите диагноз, а не решение. Иначе Claude кинется «спасать» проект, переписывая конфиг, README и пол-скрипта запуска, хотя дело может быть в одной пропущенной переменной или версии Node.

Полезный шаблон запроса:

Проанализируй проблему локального запуска Commerce OS.
Код пока не меняй.
Используй только факты из логов, README, `.env.example` и версий среды.

Верни:
1. вероятную первопричину;
2. какие файлы или команды это подтверждают;
3. минимальные команды для проверки гипотезы.

Запрос оставляет решение за вами. Claude не играет в шамана, а работает как аккуратный диагност.

Сам цикл в этом месте очень полезно держать в голове как последовательность, а не как один «магический» prompt:

flowchart TD
A[Собрали сигналы] --> B[Записали setup-evidence в EVIDENCE_LOG.md]
B --> C[Попросили Claude объяснить причину]
C --> D[Проверили одну гипотезу]
D --> E{Подтвердилась?}
E -- да --> F[Исправили минимальным diff]
E -- нет --> C

Заметьте, что в этой схеме нет шага «сразу попросили Claude починить всё»: его нет не потому, что нельзя, а потому, что это слишком дорогой путь к случайным изменениям.

6. Три источника правды о запуске

Многие setup-проблемы рождаются не в коде, а в рассинхронизации документов и конфигурации: README обещает одно, package.json делает другое, docker-compose.yml живёт своей жизнью. Вы честно выполняете инструкцию, получаете ошибку — и подозреваете Spring, Next.js, Gradle, ретроградный Меркурий и всё остальное.

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

Команды продублированы ещё и в CLAUDE.md? Это не четвёртый источник правды, а повод проверить согласованность: CLAUDE.md не должен спорить с README и scripts — иначе сначала путается Claude, потом остальные.

Для такой проверки можно дать Claude очень конкретную задачу:

Сравни README, package scripts и Docker/compose.
Найди расхождения в командах запуска, портах, переменных окружения
и ожидаемых версиях Java и Node.
Верни короткую таблицу: источник | что обещано | что реально используется.

Это как раз тот случай, когда Claude полезен не как «исправлятор», а как помощник по сверке: он видит несовпадения между файлами, которые вы легко пропустите, устав и читая README так, будто там всё написано правильно.

7. .env.example вместо секрета в чат

Переменные окружения — классический источник setup-боли и случайных утечек, когда в порыве откровенности вы вставляете в чат половину своего .env. Так делать не надо. Вообще. Никогда. Даже если очень хочется «быстренько разобраться».

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

Хороший безопасный пример:

SPRING_PROFILES_ACTIVE=dev
NEXT_PUBLIC_API_BASE_URL=http://localhost:8080
PAYMENT_PROVIDER_MODE=sandbox
# PAYMENT_PROVIDER_API_KEY=заполняется локально, не коммитится

Если лог случайно напечатал секрет, перед передачей его нужно отредактировать: оставьте структуру, замените значение на ***. И ещё: .env.example — часть reproducible setup. Обязательной переменной там нет — проблема не только у вас, а у всего проекта, просто пока не все об этом знают.

8. Commerce OS не поднимается локально

Давайте соберём всё вместе на одном реалистичном эпизоде. Представим, что вы клонировали Commerce OS и запускаете baseline-команду docker compose up. База стартует, frontend ждёт backend, а backend падает. Самое вредное сейчас — попросить Claude «починить Spring Boot». Самое полезное — собрать минимальное evidence:

docker compose up
docker compose logs backend --tail=40   # Missing required property 'PAYMENT_PROVIDER_MODE'
grep -n "PAYMENT_PROVIDER_MODE" README.md .env.example   # совпадений нет
git status --short                      # рабочее дерево чистое

После этого вы фиксируете setup-evidence в EVIDENCE_LOG.md, а затем отправляете Claude diagnostic request. Он увидит: проблема не в Java-коде и не в контейнере, а в config drift — приложение требует PAYMENT_PROVIDER_MODE, но она не документирована и не попадает в локальную среду.

Дальше важен следующий шаг: не бежать сразу коммитить всё подряд, а проверить гипотезу минимальной командой — добавьте локально безопасное dev-значение и повторите запуск:

docker compose down
echo "PAYMENT_PROVIDER_MODE=sandbox" >> .env
docker compose up -d
curl -s http://localhost:8080/actuator/health   # {"status":"UP"}

Если smoke-проверка проходит, у вас не «кажется, помогло», а цепочка доказательств. Теперь уместен минимальный diff: обновить .env.example, поправить README.md, при необходимости синхронизировать CLAUDE.md. Небольшим читаемым изменением, а не генеральной уборкой всего репозитория под музыку героизма.

9. Признаки завершённой диагностики

Очень важно уметь остановиться в правильный момент. Диагностика завершена не когда вы устали и не когда Claude написал «root cause found». Она завершена, когда вы можете назвать первопричину, показать evidence, дать команду проверки и объяснить, как другой человек воспроизведёт исправленный setup без устных заклинаний.

По сути, хороший финал такой задачи выглядит так: в EVIDENCE_LOG.md есть блок setup-evidence, README и пример env-конфига синхронизированы, baseline-команда отрабатывает одинаково, smoke-сигнал подтверждает, что сервис жив. Тут Claude перестаёт играть в угадайку, а вы — жить в режиме «только ничего не трогайте, оно заведено».

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

1

Задача

Claude code, 21 уровень, 1 лекция

Недоступна

Сбор setup-evidence через команды терминала

Сбор setup-evidence через команды терминала

Открыть

1

Задача

Claude code, 21 уровень, 1 лекция

Недоступна

Диагностика setup-проблемы внутри Claude CLI

Диагностика setup-проблемы внутри Claude CLI

Открыть