Решение проблем

Симптом

Сессия зависает / нет ответа

Проверка: Вращается ли индикатор? Нажмите 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 для включения подробного режима и найдите сообщения о рукопожатии MCP.

Вероятная причина: Сервер запустился, но регистрация инструментов не удалась — обычно несовпадение схемы или падение сервера при инициализации.

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

Признак успеха: Инструменты этого MCP-сервера появляются и доступны для вызова.

Симптом

Хуки не срабатывают

Проверка: Включите подробный режим через Ctrl+O, чтобы видеть выполнение хуков.

Вероятная причина: Неправильный регистр имени события, матчер не совпадает или скрипт не имеет прав на выполнение.

Решение:

# Проверить JSON настроек
claude -p "validate the JSON in .claude/settings.json"

# Убедиться, что скрипт хука исполняемый
chmod +x .claude/hooks/your-hook.sh

Признак успеха: Подробный режим показывает выполнение хука на ожидаемом событии.

Симптом

Хук блокирует неожиданно

Проверка: Какой вызов инструмента блокируется? Подробный режим (Ctrl+O) показывает имя хука и код выхода.

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

Решение: Сузьте шаблон матчера в .claude/settings.json, чтобы он был нацелен только на нужный инструмент. Протестируйте, запустив скрипт хука вручную с тестовыми данными.

Признак успеха: Вызов инструмента проходит без блокировки.

Симптом

Не удаётся подключиться к дроплету по SSH

Проверка: Запустите SSH с подробным выводом, чтобы увидеть, где происходит сбой.

Вероятная причина: Неверный IP, SSH-ключ не добавлен при создании дроплета или файрвол блокирует порт 22.

Решение:

ssh -v root@<droplet-ip>

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

Признак успеха: Вы получаете root-шелл на дроплете.

Симптом

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 > Networking > Firewalls.

Признак успеха: curl http://<droplet-ip>:30080 возвращает ответ вашего приложения.

Симптом

Интерфейс 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

Проверка: Определите, какой ресурс нездоров.

Вероятная причина: Под, управляемый 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 получил триггер
• Временно упростите строгие инструкции CLAUDE.md, если агент блокируется политикой

Признак успеха: Лог запуска action показывает ответ Claude и он публикует результат в PR/issue.