# 13. 트러블슈팅 ← [[openspec-12-migration-guide|12. 마이그레이션 가이드]] | 다음 → [[openspec-14-references|14. 참고 자료]] --- ## 13.1 일반 문제 > [!bug] 문제: `openspec: command not found` > ```bash > # 글로벌 설치 확인 > npm list -g @fission-ai/openspec > > # PATH 확인 > echo $PATH > > # 재설치 > npm install -g @fission-ai/openspec@latest > ``` > [!bug] 문제: Node.js 버전 오류 > ```bash > # 현재 버전 확인 > node --version > > # nvm으로 버전 변경 > nvm install 20 > nvm use 20 > ``` > Node.js 20.19.0 이상이 필요하다. → [[openspec-02-installation-and-setup|2장 설치 가이드]] 참고 > [!bug] 문제: `openspec init` 후 슬래시 명령어가 작동하지 않음 > ```bash > # 생성된 파일 확인 > ls .claude/skills/ > ls .claude/commands/opsx/ > > # 도구 재설정 > openspec update --force > ``` > AI 도구를 재시작해야 새로운 스킬을 인식한다. 스킬은 AI 도구 시작 시점에 로드된다. > [!bug] 문제: 스펙 검증 실패 > ```bash > # 상세 오류 확인 > openspec validate --all --strict > > # 특정 변경사항만 검증 > openspec validate --changes > > # 스키마 검증 > openspec schema validate spec-driven --verbose > ``` > [!bug] 문제: "Change not found" 오류 > 변경명을 명시적으로 지정한다. > ```bash > /opsx:apply add-dark-mode # 변경명 명시 > openspec list # 현재 변경사항 목록 확인 > ``` > [!bug] 문제: "No artifacts ready" 오류 > 의존성이 충족되지 않은 아티팩트가 있다. > ```bash > openspec status --change <변경명> # 어떤 아티팩트가 blocked인지 확인 > ``` > 먼저 필요한 의존 아티팩트를 생성한 후 진행한다. > [!bug] 문제: "Schema not found" 오류 > ```bash > openspec schemas # 사용 가능한 스키마 목록 > openspec schema which # 현재 스키마 출처 확인 > ``` > [!bug] 문제: 아티팩트가 제대로 생성되지 않음 > - `openspec/config.yaml`에 프로젝트 컨텍스트를 추가한다 > - 아티팩트별 `rules:`를 추가해 AI에게 구체적인 지침을 제공한다 > - `/opsx:ff` 대신 `/opsx:continue`를 사용해 단계별로 검토한다 > [!bug] 문제: `config.yaml` 설정이 반영되지 않음 > - 파일명이 정확히 `openspec/config.yaml`인지 확인 (`.yml` 확장자 불가) > - YAML 문법 오류 여부 확인 > - 설정 변경은 재시작 없이 즉시 적용된다 > [!bug] 문제: `rules:`의 "Unknown artifact ID" 오류 > ```bash > openspec schemas --json # 유효한 아티팩트 ID 확인 > ``` > `spec-driven` 스키마의 유효 ID: `proposal`, `specs`, `design`, `tasks` ## 13.2 CI/CD 환경 문제 > [!bug] 문제: CI에서 대화형 프롬프트가 막힘 > ```bash > # 비대화형 플래그 사용 > openspec init --tools claude --profile core --no-interactive > openspec validate --no-interactive > openspec archive --yes --no-validate > ``` > [!bug] 문제: 텔레메트리 관련 네트워크 오류 > ```bash > export OPENSPEC_TELEMETRY=0 > ``` ## 13.3 워크스페이스 문제 > [!bug] 문제: 워크스페이스 링크 오류 > ```bash > openspec workspace doctor ← 상태 진단 > openspec workspace relink ← 로컬 경로 재연결 > ``` > 자세한 내용은 [[openspec-10-advanced-usage-patterns#10.3 멀티 저장소 워크스페이스|10장 멀티 저장소 워크스페이스]] 참고 --- ← [[openspec-12-migration-guide|12. 마이그레이션 가이드]] | 다음 → [[openspec-14-references|14. 참고 자료]]