# Отладка {#debugging}

Открытость — это практическое преимущество: код доступен, его можно запустить локально, а также использовать агентов для написания кода, чтобы быстрее получать ответы и отлаживать потенциальные ошибки в кодовой базе.

Если во время отладки вы обнаружите недостающую или неполную документацию, обновите англоязычные документы в каталоге `docs/` и создайте PR.

## Снимок стека потоков в CI {#thread-dump-ci}

Когда CLI периодически зависает, можно сделать снимок стека потоков без остановки процесса. Включите обработчик сигналов и отправьте `SIGUSR1` работающему процессу `tuist`.

```bash
export TUIST_THREAD_DUMP_SIGNAL=1
export TUIST_THREAD_DUMP_SAMPLE=1 # macOS only, captures all threads via /usr/bin/sample
tuist generate &
TUIST_PID=$!
sleep 600
kill -USR1 "$TUIST_PID"
wait "$TUIST_PID"
```

Если `TUIST_THREAD_DUMP_SAMPLE` не установлен, обработчик выводит стек текущего потока. Вывод записывается в stderr, поэтому он отображается в логах CI.

## Использование агентов для написания кода {#use-coding-agents}

Агенты для написания кода полезны для:

- Поиска в кодовой базе мест, где реализовано определённое поведение.
- Воспроизведения проблем локально и быстрой итерации.
- Отслеживания того, как входные данные проходят через Tuist, чтобы найти первопричину.

Предоставляйте минимально возможный пример воспроизведения и направляйте агента на конкретный компонент (CLI, сервер, кэш, документация или handbook). Чем уже область исследования, тем быстрее и точнее проходит отладка.

### Часто используемые подсказки (FNP) {#frequently-needed-prompts}

#### Неожиданная генерация проекта {#unexpected-project-generation}

Генерация проекта выдаёт результат, который я не ожидаю. Запустите Tuist CLI для моего проекта по пути `/path/to/project`, чтобы понять, почему это происходит. Проследите конвейер генератора и укажите пути в коде, ответственные за вывод.

#### Воспроизводимая ошибка в сгенерированных проектах {#reproducible-bug-in-generated-projects}

Похоже, это ошибка в сгенерированных проектах. Создайте воспроизводимый проект в каталоге `examples/`, используя существующие примеры в качестве образца. Добавьте падающий приёмочный тест, запустите его через `xcodebuild`, выбрав только этот тест, исправьте проблему, повторно запустите тест для подтверждения успеха и откройте PR.