Вирішення проблем

Симптом

Сесія зависає / немає відповіді

Перевірте: Чи крутиться спінер? Натисніть Ctrl+C для переривання.

Ймовірна причина: Тривалий виклик інструмента перевищив таймаут, або збій мережі призупинив з'єднання.

Рішення:

Ctrl+C        # перервати поточний хід
/clear        # скинути стан сесії

Якщо все ще зависає, закрийте термінал повністю і запустіть claude у новому вікні.

Ознака успіху: Claude відповідає на ваш наступний промпт протягом кількох секунд.

Симптом

Відмова в доступі на кожну команду

Перевірте: В якому режимі дозволів ви працюєте?

Ймовірна причина: Режим за замовчуванням вимагає підтвердження для кожного виклику інструмента.

Рішення: Натисніть Shift+Tab для переключення режимів дозволів, або запустіть з більш дозвільним режимом:

claude --permission-mode acceptEdits

Також можна натиснути a під час промпта, щоб дозволити інструмент на решту сесії.

Ознака успіху: Команди виконуються без повторних запитів підтвердження.

Симптом

CLAUDE.md не завантажується

Перевірте: Запустіть /memory всередині сесії, щоб побачити, які файли завантажені.

Ймовірна причина: Файл у неправильній директорії або має зламане посилання @path.

Рішення: Переконайтесь, що файл знаходиться за шляхом ./CLAUDE.md або ./.claude/CLAUDE.md відносно місця запуску Claude. Виправте будь-які посилання @path, щоб вони коректно розв'язувались.

Ознака успіху: /memory показує вміст вашого CLAUDE.md.

Симптом

Навички не відображаються

Перевірте: Переконайтесь, що файл навички існує за очікуваним шляхом.

Ймовірна причина: Файл SKILL.md розміщений неправильно або структура директорій хибна.

Рішення: Навички повинні знаходитись за одним із цих шляхів:

Project: .claude/skills/<skill-name>/SKILL.md
User:    ~/.claude/skills/<skill-name>/SKILL.md

Після виправлення запустіть нову сесію — навички завантажуються при старті.

Ознака успіху: Навичка з'являється, коли Claude перелічує доступні можливості.

Симптом

Авто-пам'ять не працює

Перевірте: Підтвердіть вашу версію та налаштування.

Ймовірна причина: Застаріла версія Claude Code або функція вимкнена в налаштуваннях.

Рішення:

claude --version   # потрібна v2.1.59+
claude update

Потім переконайтесь, що ~/.claude/settings.json містить:

{ "autoMemoryEnabled": true }

Ознака успіху: Claude проактивно зберігає факти між сесіями.

Симптом

Контекст стає занадто довгим

Перевірте: Чи забуває Claude попередні інструкції або повторюється?

Ймовірна причина: Розмова перевищила ефективне вікно контексту.

Рішення: Стискайте розмову проактивно — не чекайте, поки Claude почне забувати.

/compact

Ознака успіху: Claude відповідає зв'язно, пам'ятаючи попередній контекст.

Симптом

MCP-сервер не підключається

Перевірте: Чи конфігурація у правильному файлі? Рівень проєкту: .mcp.json. Рівень користувача: ~/.claude.json.

Ймовірна причина: Відсутні змінні середовища, неправильний шлях до команди сервера, або серверний бінарник не встановлений.

Рішення: Перевірте, що команда сервера існує, встановіть необхідні змінні середовища (напр. GITHUB_TOKEN), потім перезапустіть сесію Claude — MCP-конфігурація зчитується тільки при старті.

Ознака успіху: Claude показує MCP-інструменти у своїх можливостях при старті сесії.

Симптом

MCP-інструменти не з'являються

Перевірте: Натисніть Ctrl+O для увімкнення verbose-режиму та шукайте повідомлення MCP handshake.

Ймовірна причина: Сервер запустився, але реєстрація інструментів не вдалась — зазвичай невідповідність схеми або збій сервера під час ініціалізації.

Рішення: Запустіть команду MCP-сервера вручну в терміналі, щоб побачити вивід помилок. Виправте проблеми, потім перезапустіть сесію Claude.

Ознака успіху: Інструменти з цього MCP-сервера з'являються і доступні для виклику.

Симптом

Хуки не спрацьовують

Перевірте: Увімкніть verbose-режим через Ctrl+O, щоб побачити виконання хуків.

Ймовірна причина: Неправильний регістр назви події, matcher не збігається, або скрипт не виконуваний.

Рішення:

# Валідувати JSON налаштувань
claude -p "validate the JSON in .claude/settings.json"

# Переконатись, що скрипт хука виконуваний
chmod +x .claude/hooks/your-hook.sh

Ознака успіху: Verbose-режим показує виконання хука на очікуваній події.

Симптом

Хук блокує неочікувано

Перевірте: Який виклик інструмента блокується? Verbose-режим (Ctrl+O) показує назву хука та код виходу.

Ймовірна причина: Matcher занадто широкий або скрипт хука повертає код виходу 2 для шляху, який ви не мали наміру блокувати.

Рішення: Звузьте патерн matcher в .claude/settings.json, щоб він цілив тільки на потрібний інструмент. Протестуйте, запустивши скрипт хука вручну з тестовим вводом.

Ознака успіху: Виклик інструмента проходить без блокування.

Симптом

Не вдається підключитись до дроплета через SSH

Перевірте: Запустіть SSH з verbose-виводом, щоб побачити, де відбувається збій.

Ймовірна причина: Неправильна IP-адреса, SSH-ключ не додано при створенні дроплета, або файрвол блокує порт 22.

Рішення:

ssh -v root@<droplet-ip>

Перевірте IP у консолі DigitalOcean. Якщо ключ відсутній, додайте його через панель DO та перестворіть дроплет.

Ознака успіху: Ви отримуєте root shell на дроплеті.

Симптом

k3s не запускається

Перевірте: Подивіться статус сервісу та логи.

Ймовірна причина: Недостатньо RAM (потрібно мінімум 2 ГБ), порт 6443 вже зайнятий, або правила файрвола блокують потрібні порти.

Рішення:

sudo systemctl status k3s
sudo journalctl -u k3s -f

Ознака успіху: systemctl status k3s показує active (running).

Симптом

kubectl — відмовлено у з'єднанні

Перевірте: Чи використовуєте ви правильний kubeconfig?

Ймовірна причина: k3s використовує власний шлях kubeconfig, а не стандартний ~/.kube/config.

Рішення:

# На дроплеті
sudo kubectl --kubeconfig /etc/rancher/k3s/k3s.yaml get nodes

Для локального доступу скопіюйте kubeconfig та замініть 127.0.0.1 на публічну IP-адресу вашого дроплета.

Ознака успіху: kubectl get nodes повертає ваш вузол у стані Ready.

Симптом

Поди застрягли в ImagePullBackOff

Перевірте: Опишіть под, щоб побачити помилку завантаження.

Ймовірна причина: Образ не існує, тег неправильний, або Docker Hub обмежує швидкість запитів.

Рішення:

kubectl describe pod <pod-name> -n ai-coderrank

Перевірте назву образу та тег. У разі обмеження швидкості перейдіть на ghcr.io.

Ознака успіху: Под переходить у стан Running.

Симптом

Поди застрягли в CrashLoopBackOff

Перевірте: Прочитайте логи з попереднього зламаного контейнера.

Ймовірна причина: Застосунок падає при старті — відсутня змінна середовища, відсутній ConfigMap/Secret, або невідповідність порту.

Рішення:

kubectl logs <pod-name> -n ai-coderrank --previous

Ознака успіху: Под залишається у стані Running після виправлення конфігурації.

Симптом

Застосунок недоступний за публічною IP (NodePort 30080)

Перевірте: Підтвердіть тип сервісу та доступність порту.

Ймовірна причина: Сервіс не є NodePort, порт не 30080, або файрвол DigitalOcean його блокує.

Рішення:

# Перевірте, що сервіс є NodePort на 30080
kubectl get svc -n ai-coderrank

# Спочатку протестуйте локально на дроплеті
curl http://localhost:30080

Якщо локальний curl працює, а зовнішній ні, відкрийте порт 30080 у файрволі DigitalOcean: DO Console > Networking > Firewalls.

Ознака успіху: curl http://<droplet-ip>:30080 повертає відповідь вашого застосунку.

Симптом

UI ArgoCD недоступний

Перевірте: Чи працює port-forward?

Ймовірна причина: Немає активного port-forward, або под ArgoCD-сервера не запущений.

Рішення:

kubectl port-forward svc/argocd-server -n argocd 8080:443

Отримайте пароль адміністратора:

kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d

Ознака успіху: Браузер завантажує панель ArgoCD за адресою https://localhost:8080.

Симптом

ArgoCD не синхронізується

Перевірте: Подивіться статус застосунку.

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

Рішення:

kubectl get app -n argocd

Примусова синхронізація, якщо застосунок існує, але застряг:

kubectl patch app ai-coderrank -n argocd \
  --type merge -p '{"operation":{"sync":{}}}'

Ознака успіху: Статус застосунку показує Synced та Healthy.

Симптом

ArgoCD показує Degraded health

Перевірте: Визначте, який ресурс нездоровий.

Ймовірна причина: Под, керований ArgoCD, не працює — зазвичай це CrashLoopBackOff під капотом.

Рішення:

kubectl get app ai-coderrank -n argocd -o yaml | grep -A 20 health
kubectl logs -n ai-coderrank -l app=ai-coderrank --tail=50

Виправте основну проблему пода (див. Проблеми з інфраструктурою) і ArgoCD автоматично виявить відновлення.

Ознака успіху: Здоров'я застосунку повертається до Healthy.

Симптом

Claude Action не запускається

Перевірте: Чи файл workflow присутній і тригер правильний?

Ймовірна причина: Файл workflow не в .github/workflows/, подія тригера не збігається, умова if фільтрує його, або секрет ANTHROPIC_API_KEY відсутній.

Рішення: Перевірте всі п'ять пунктів:

1. Файл workflow знаходиться в .github/workflows/
2. Подія тригера збігається (issue_comment, pull_request_review_comment)
3. Умова if відповідає вашому патерну коментаря
4. ANTHROPIC_API_KEY встановлено в Settings > Secrets репозиторію
5. Дозволи GitHub App налаштовані

Ознака успіху: Вкладка Actions показує новий запуск після публікації відповідного коментаря.

Симптом

Action запускається, але немає виводу

Перевірте: Відкрийте лог запуску у вкладці GitHub Actions.

Ймовірна причина: API ключ недійсний/прострочений, обмеження швидкості, max_turns встановлено занадто низько, або CLAUDE.md має занадто обмежувальні інструкції.

Рішення:

• Перевірте статус API ключа та помилки обмеження швидкості на панелі Anthropic
• Збільште max_turns, якщо workflow завершується занадто рано
• Перегляньте лог workflow для підтвердження, що Claude дійсно отримав payload тригера
• Тимчасово спростіть обмежувальні інструкції CLAUDE.md, якщо агент блокується політикою

Ознака успіху: Лог запуску action показує відповідь Claude, і вона публікується в PR/issue.