문제 해결

구체적인 문제에 대한 구체적인 해결책입니다. 각 항목은 증상을 명시하고, 가능한 원인을 한 문장으로 설명하며, 해결 방법을 제공합니다. 여기에 없는 문제는 FAQ에서 도움을 받을 수 있으며, Discord에서 확실히 도움을 받을 수 있습니다.

설치 및 설정

openspec: command not found

CLI가 설치되지 않았거나 셸에서 찾을 수 없습니다. 전역으로 설치하고 확인하세요:

npm install -g @fission-ai/openspec@latest
openspec --version

설치되었지만 여전히 찾을 수 없다면, npm 전역 bin 디렉터리가 PATH에 포함되어 있지 않을 가능성이 높습니다. npm prefix -g를 실행하여 전역 패키지가 설치된 위치를 확인하세요: macOS와 Linux에서는 해당 디렉터리의 bin/에 바이너리가 있고, Windows에서는 바로 그 디렉터리에 있습니다. 해당 경로가 PATH에 포함되어 있는지 확인하세요. (npm bin -g는 npm 9에서 제거되었습니다.)

AI 지원 설치를 사용하셨다면, 이것이 예상된 핸드오프 지점입니다: 해당 프롬프트는 셸 시작 파일을 직접 편집하지 않고 PATH 변경 사항을 표시하도록 도우미에게 지시합니다.

"Requires Node.js 20.19.0 or higher"

OpenSpec은 Node 20.19.0+에서 실행됩니다. 버전을 확인하고 필요한 경우 업그레이드하세요:

node --version

bun을 사용하여 OpenSpec을 설치한 경우, OpenSpec은 여전히 Node에서 실행되므로 PATH에 Node 20.19.0+가 있어야 합니다. 설치를 참조하세요.

openspec init이 AI 도구를 설정하지 않음

Init은 설정할 도구를 묻습니다. 도구를 건너뛰었거나 다른 도구를 추가하려면 다시 실행하거나 비대화형 형식을 사용하세요:

openspec init --tools claude,cursor

전체 도구 ID 목록은 지원되는 도구에 있습니다. 모든 도구를 설정하려면 --tools all을, 도구 설정을 건너뛰려면 --tools none을 사용하세요.

명령이 표시되지 않음

/opsx:propose(또는 도구에 해당하는 명령)가 나타나지 않거나 아무 작업도 수행하지 않으면 다음 목록을 확인하세요. 빠른 확인 순서로 정렬되어 있습니다.

1. 잘못된 위치일 수 있습니다. 슬래시 명령은 AI 도우미의 채팅에서 사용하는 것이지 터미널에서 사용하는 것이 아닙니다. 셸에 /opsx:propose를 입력했다면 그것이 원인입니다. 명령 작동 방식을 참조하세요.

2. 파일을 다시 생성하세요. 프로젝트 루트에서:

   openspec update

   이 명령은 구성된 각 도구에 대한 스킬 및 명령 파일을 다시 작성합니다.

   지시 파일은 설치된 CLI에서 제공되므로, 오래된 CLI는 최신 워크플로를 작성하지 않고 모든 것이 최신 상태라고 보고합니다. openspec update는 이제 이를 감지하고 업그레이드를 제안합니다 — 제안이 나타나면 수락하세요.

3. 도우미를 다시 시작하세요. 대부분의 도구는 시작 시 스킬과 명령을 스캔합니다. 새 창을 열면 대개 해결됩니다.

4. 파일이 존재하는지 확인하세요. Claude Code의 경우 .claude/skills/에 openspec-* 폴더가 있는지 확인하세요. 다른 도구는 고유한 디렉터리를 사용하며, 모든 목록은 지원되는 도구에 있습니다.

5. 프로젝트가 초기화되었는지 확인하세요. 스킬은 프로젝트별로 작성됩니다. 리포지토리를 복제했거나 폴더를 전환한 경우 해당 위치에서 openspec init(또는 openspec update)을 실행하세요.

6. 도구가 명령 파일을 지원하는지 확인하세요. Codex, CodeArts, ForgeCode, Hermes, Kimi Code, Mistral Vibe, Zed Agent 및 공유 .agents 대상에는 opsx-* 명령 파일이 생성되지 않으며 스킬 기반 호출을 사용하므로 /opsx는 해당 도구에서 자동 완성되지 않습니다. Codex에는 $openspec-propose를, Kimi Code에는 /skill:openspec-propose를, 나머지에는 /openspec-propose를 입력하세요. 공유 .agents 대상은 벤더 중립적이므로 /openspec-propose가 보장된 형식이 아니라 일반적인 형식입니다 — 도우미가 응답하지 않으면 스킬 호출 방법에 대한 자체 문서를 확인하세요. Amazon Q는 명령 파일을 받지만 슬래시 메뉴가 아닌 프롬프트 라이브러리에 로드합니다 — 해당 도구에서는 /opsx-propose가 아닌 @opsx-propose를 입력하세요. 각 도구의 호출 형식은 호출 방법에 나열되어 있습니다.

변경 사항 작업

"Change not found"

명령이 어떤 변경 사항을 의미하는지 확인할 수 없습니다. 명시적으로 이름을 지정하거나 존재하는 것을 확인하세요:

openspec list                    # 활성 변경 사항 확인
/opsx:apply add-dark-mode        # 채팅에서 변경 이름 지정

또한 올바른 프로젝트 디렉터리에 있는지 확인하세요.

"No artifacts ready"

모든 아티팩트는 이미 생성되었거나 종속성을 기다리며 차단되었습니다. 무엇이 차단 중인지 확인하세요:

openspec status --change <name>

그런 다음 누락된 종속성을 먼저 생성하세요. 순서를 기억하세요: 제안이 스펙과 디자인을 활성화하고, 스펙과 디자인이 함께 작업을 활성화합니다.

openspec validate가 경고 또는 오류를 보고함

검증은 스펙과 변경 사항의 구조적 문제를 확인합니다. 메시지를 읽으면 파일과 문제가 명시됩니다.

openspec validate <name>           # 하나의 항목 검증
openspec validate --all            # 모든 항목 검증
openspec validate --all --strict   # 더 엄격한 검사, CI에 적합
openspec validate --archived       # 보관된 변경 사항에 확인되지 않은 작업이 있으면 실패

일반적인 원인은 필수 섹션 누락(예: 시나리오가 없는 스펙) 또는 잘못된 델타 헤더입니다. 파일을 수정하고 다시 실행하세요. CLI 참조에 출력 형식이 문서화되어 있습니다.

한 가지 메시지는 자체적으로 설명할 가치가 있습니다:

MODIFIED "<requirement>" omits scenario(s) the current spec still has: "<scenario>"

MODIFIED 요구 사항은 전체 요구 사항 블록을 대체하므로 변경 후에도 유지되는 모든 시나리오를 포함해야 하며, 편집한 시나리오만 포함해서는 안 됩니다. openspec/specs/<capability-path>/spec.md에서 명명된 시나리오를 델타로 복사하고 경로에 있는 도메인 디렉터리를 유지하세요. 이 메시지는 다른 사람의 변경 사항이 동일한 요구 사항에 시나리오를 추가한 후 오래된 변경 사항에서 자주 나타납니다 — 보관은 해당 변경 사항을 어느 쪽이든 거부하며, 이제 구현 전에 검증이 이를 알려줍니다.

AI가 불완전하거나 잘못된 아티팩트를 생성함

AI가 충분한 맥락을 갖지 못했습니다. 몇 가지 방법이 도움이 됩니다:

• openspec/config.yaml에 프로젝트 맥락을 추가하여 스택과 규칙이 모든 요청에 주입되도록 하세요. 사용자 정의를 참조하세요.
• 특정 아티팩트에만 적용되는 지침을 위해 아티팩트별 rules:를 추가하세요.
• 제안할 때 더 자세한 설명을 제공하세요.
• /opsx:ff가 한 번에 모두 처리하는 대신 확장된 /opsx:continue를 사용하여 한 번에 하나의 아티팩트를 생성하고 각각 검토하세요.

보관이 완료되지 않거나 불완전한 작업에 대해 경고함

보관은 불완전한 작업을 차단하지 않지만 경고합니다. 보관은 일반적으로 작업이 완료되었음을 의미하기 때문입니다. 의도적으로 작업을 남겨둔 경우(부분 변경을 제출하는 경우) 계속 진행하세요. 그렇지 않으면 먼저 작업을 완료하세요. 보관은 또한 델타 스펙을 아직 동기화하지 않은 경우 메인 스펙에 동기화할 것을 제안합니다. 이유가 없으면 수락하세요.

"User force closed the prompt with 0 null"

openspec archive가 질문에 답할 수 없는 상황에서 실행되었습니다 — AI 에이전트가 도구에서 호출하거나, CI 작업 또는 stdin이 닫힌 셸에서 실행된 경우입니다. 보관은 최대 세 번의 확인을 요청하며, 답할 수 없는 경우 원시 메시지로 실패하곤 했습니다.

--yes 플래그를 전달하여 미리 답하세요:

openspec archive <change-name> --yes

이미 전달 중이던 다른 플래그를 유지하세요 — --skip-specs 및 --no-validate는 보관이 수행하는 작업을 변경하므로 단순히 --yes만 다시 실행하는 것은 같은 명령이 아닙니다. 현재 버전에서는 플래그를 직접 명시하며 붙여넣을 수 있는 Fix: 줄을 출력합니다. 목록에서 선택하려는 경우 변경 이름을 명시적으로 전달하세요: 선택기도 답변이 필요합니다.

대신 보관 명령의 출력을 파일로 리디렉션하거나 도구로 캡처하고 실제로 답변을 파이프했다면(printf 'y\n' | openspec archive …), 이전 버전은 프롬프트를 그리는 동안 터미널 이스케이프 코드를 캡처에 기록했습니다 — 일부 환경에서는 파일을 심각하게 bloating할 수 있습니다. 현재 버전은 stdout이 터미널이 아닐 때 확인 프롬프트를 일반 텍스트로 읽으며, 인수 없이 실행한 openspec archive(대화형 변경 선택기를 그리게 되는 경우)는 캡처에 메뉴를 렌더링하는 대신 변경 이름을 전달하도록 요청합니다. 어느 경우든 리디렉션 및 에이전트 실행은 깨끗하게 유지됩니다. --yes(변경 이름 포함)를 전달하면 프롬프트가 완전히 건너뜁니다.

구성

config.yaml이 적용되지 않음

일반적인 세 가지 원인이 있습니다:

1. 파일 이름이 잘못되었습니다. openspec/config.yaml이어야 하며 .yml이 아닙니다.
2. 잘못된 YAML. YAML 검증기를 통해 확인하세요. CLI도 줄 번호와 함께 구문 오류를 보고합니다.
3. 재시작을 기대했습니다. 재시작할 필요가 없습니다. 구성 변경은 즉시 적용됩니다.

"Unknown artifact ID in rules: X"

rules: 아래의 키가 스키마의 어떤 아티팩트와도 일치하지 않습니다. 기본 spec-driven 스키마의 유효한 ID는 proposal, specs, design, tasks입니다. 어떤 스키마의 ID를 보려면:

openspec schemas --json

"Context too large"

context: 필드는 의도적으로 50KB로 제한됩니다. 모든 요청에 주입되기 때문입니다. 요약하거나 긴 문서를 붙여넣는 대신 링크로 연결하세요. 간결한 맥락은 더 나은 결과와 더 빠른 결과를 생성합니다.

"Schema not found"

참조한 스키마 이름이 존재하지 않습니다. 사용 가능한 목록을 확인하고 철자를 확인하세요:

openspec schemas                    # 사용 가능한 스키마 목록
openspec schema which <name>        # 스키마가 어디서 해석되는지 확인
openspec schema init <name>         # 사용자 정의 스키마 생성

사용자 정의를 참조하세요.

레거시 워크플로에서 마이그레이션

"Legacy files detected in non-interactive mode"

CI 또는 비대화형 셸에 있고 OpenSpec이 정리할 오래된 파일을 발견했지만 프롬프트를 표시할 수 없는 경우입니다. 자동으로 승인하세요:

openspec init --force

Codex의 경우 OpenSpec은 $CODEX_HOME/prompts 또는 ~/.codex/prompts에서 오래된 관리 프롬프트 파일을 감지할 수 있습니다. 해당 정리는 OpenSpec의 허용 목록에 있는 레거시 Codex 프롬프트 파일 이름으로 제한되며, 비대화형 openspec init은 대체 .agents/skills/openspec-* 스킬이 존재하는 파일만 제거합니다. 비대화형 openspec update는 --force를 전달하지 않는 한 모든 레거시 정리를 건드리지 않습니다.

마이그레이션 후 명령이 나타나지 않음

IDE를 다시 시작하세요. 스킬은 시작 시 감지됩니다. 여전히 나타나지 않으면 openspec update를 실행하고 지원되는 도구의 파일 위치를 확인하세요.

내 기존 project.md가 마이그레이션되지 않음

의도된 동작입니다. OpenSpec은 project.md를 자동으로 삭제하지 않습니다. 직접 작성한 맥락이 포함될 수 있기 때문입니다. 유용한 부분을 config.yaml의 context: 섹션으로 이동한 다음 직접 삭제하세요. 마이그레이션 가이드에서 이 과정을 안내하며, AI가 요약하도록 전달할 수 있는 프롬프트도 포함되어 있습니다.

여전히 막혀 있나요?

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• 터미널에서: openspec feedback "문제가 무엇인지"를 실행하면 이슈가 생성됩니다.

문제를 보고할 때는 OpenSpec 버전(openspec --version), Node 버전(node --version), AI 도구, 그리고 정확한 명령과 출력을 포함하세요. 그러면 훨씬 빠르게 도움을 받을 수 있습니다.