Діагностика середовища

Діагностика починається з фактів

Проблему запуску не варто одразу лікувати змінами коду. Спочатку зберіть ОС, shell, поточну директорію, стан Git, версії інструментів, точну команду та перший змістовний фрагмент логу.

Ціль діагностики — перетворити нечіткий симптом на сценарій, який інша людина може повторити з чистого або описаного середовища.

pwd
git status --short
./gradlew --version
node -v
docker --version
docker compose ps
docker compose logs backend --tail=40
grep -n "SPRING_PROFILES_ACTIVE" .env.example

Відтворюване середовище

• зафіксуйте версії runtime та build tools;
• використовуйте lock-файли й wrapper, якщо вони передбачені проєктом;
• запишіть package manager, profile, ports і стандартну команду запуску;
• перевірте, чи потрібні Docker-сервіси справді запущені;
• визначте smoke-сигнал: health endpoint, CLI output або інший observable result.

Git і файлова система як baseline

Якщо симптом схожий на проблему permissions, окремо перевірте доступ до потрібних файлів, каталогів або Docker-сокета. Не маскуйте permission failure зміною прав навмання.

1. Переконайтеся, що ви в правильній робочій копії через pwd.
2. Перевірте наявність README, wrapper, lock-файлів, compose-файлів і .env.example.
3. Запустіть git status --short до початку розслідування.
4. Відокремте власні локальні зміни від нового симптому.
5. Порівняйте команду запуску з документацією та scripts.

Змінні середовища без витоку секретів

.env.example має описувати імена та безпечні приклади значень, але не містити реальних ключів. Передавайте Claude лише замасковані значення або назви змінних, якщо значення не потрібне для діагнозу.

Порівняйте .env.example, README, Compose і код. Невідома обовʼязкова змінна часто пояснює failure раніше, ніж помилка бізнес-логіки.

PAYMENT_PROVIDER_MODE=sandbox
PAYMENT_API_KEY=<set-locally-never-commit>

Гіпотеза, одна перевірка, найменша зміна

1. Сформулюйте найімовірнішу причину та докази на її підтримку.
2. Попросіть Claude лише про read-only аналіз і команди перевірки.
3. Перевірте одну гіпотезу однією командою або малою зміною.
4. Якщо гіпотеза не підтвердилася, зафіксуйте це й поверніться до фактів.
5. Після підтвердження внесіть найменше необхідне виправлення та повторіть baseline.