# 디버깅 {#debugging}

오픈 소스라는 점은 실용적인 장점입니다. 코드를 직접 확인할 수 있고, 로컬에서 실행할 수 있으며, 코딩 에이전트를 활용해 질문을 더 빠르게 해결하고 코드베이스의 잠재적 버그를 디버깅할 수 있습니다.

디버깅 중에 문서가 누락되었거나 불완전한 부분을 발견하면 `docs/` 아래의 영어 문서를 업데이트하고 PR을 열어 주세요.

## CI에서 스레드 덤프 캡처하기 {#thread-dump-ci}

CLI가 간헐적으로 멈출 때 프로세스를 중지하지 않고 스레드 덤프를 캡처할 수 있습니다. 시그널 핸들러를 활성화하고 실행 중인 `tuist` 프로세스에 `SIGUSR1`를 보내세요.

```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, 서버, 캐시, 문서 또는 핸드북)를 집중하도록 안내하세요. 범위가 좁을수록 디버깅 과정이 더 빠르고 정확해집니다.

### 자주 필요한 프롬프트(FNP) {#frequently-needed-prompts}

#### 예상치 못한 프로젝트 생성 {#unexpected-project-generation}

프로젝트 생성 결과가 예상과 다릅니다. 이 현상의 원인을 파악하기 위해 `/path/to/project`에 있는 내 프로젝트를 대상으로 Tuist CLI를 실행하세요. 생성기 파이프라인을 추적하고 출력 결과와 관련된 코드 경로를 찾아보세요.

#### 생성된 프로젝트에서 재현 가능한 버그 {#reproducible-bug-in-generated-projects}

생성된 프로젝트에 버그가 있는 것 같습니다. 기존 예제를 참고하여 `examples/` 아래에 재현 가능한 프로젝트를 생성하세요. 실패하는 인수 테스트를 추가하고, 해당 테스트만 선택한 상태로 `xcodebuild`를 통해 실행한 후, 문제를 수정하고 테스트를 다시 실행하여 통과하는지 확인한 다음 PR을 열어 주세요.