오픈스펙 설치

오픈스펙 설치

OpenSpec은 제안, 사양 및 변경 기록을 관리합니다. 이 페이지의 목표는 하나입니다. 즉, 기존 작업 흐름에 연결할 수 있도록 설치 경로를 명확하게 설명하는 것입니다.

오픈스펙이란 무엇인가요?

OpenSpec은 소프트웨어 작업의 제안 및 사양을 관리하기 위한 명령줄 도구입니다. 핵심 워크플로에는 다음이 포함됩니다.

• 제안 관리: 기능 제안 생성, 검토 및 추적
• 사양 검증: 코드 변경 사항이 사전 정의된 사양을 준수하는지 확인
• 변경 사항 추적: 검토된 모든 변경 기록을 기록합니다.
• 팀 공동작업: 여러 사람의 공동 개발 지원

HagiCode 프로젝트에 적용

HagiCode 프로젝트에서 OpenSpec은 다음 용도로 사용됩니다.

1. 기능 개발 관리: 모든 새로운 기능은 OpenSpec 제안 프로세스를 거쳐야 합니다.
2. 코드 검토: 변경 사항이 프로젝트 사양을 준수하는지 확인
3. 문서 동기화: 문서와 코드 구현 간의 일관성 유지
4. 버전 제어 통합: 버전 제어 워크플로와의 원활한 통합

전제조건

OpenSpec을 설치하기 전에 시스템이 다음 요구 사항을 충족하는지 확인하십시오.

Node.js와 npm

OpenSpec은 npm을 통해 배포되며 Node.js 환경이 필요합니다. OpenSpec에는 Node.js 18.0 이상이 필요합니다.

Node.js 설치를 확인합니다.

node --version

npm 설치 확인:

npm --version

설치되지 않았거나 버전이 너무 오래된 경우에는 관련 소프트웨어 설치 지침을 참조하십시오. 설치 가이드.

OpenSpec 설치

버전 요구사항

이 프로젝트에는 OpenSpec 1.0.0 이상 버전 범위를 사용해야 합니다. 프로젝트 워크플로와의 호환성을 보장하기 위해 모든 1.x 버전이 지원됩니다.

OpenSpec은 npm을 통해 전역적으로 설치되므로 시스템 어디에서나 사용할 수 있습니다.

npm을 사용하여 전역적으로 설치

Windows

PowerShell 또는 명령 프롬프트에서 실행:

npm install -g @fission-ai/openspec@1

Windows 권한 문제

설치 중에 권한 오류가 발생하면 관리자 권한으로 PowerShell 또는 명령 프롬프트를 실행하세요.

macOS

터미널에서 실행:

npm install -g @fission-ai/openspec@1

:::참고[macOS 권한 문제] 당신이 만난다면 EACCES 권한 오류가 발생했습니다. 다음을 시도해 보세요.

sudo npm install -g @fission-ai/openspec@1

또는 사용 NVM Node.js 버전을 관리하고 권한 문제를 방지합니다. :::

Linux

터미널에서 실행:

npm install -g @fission-ai/openspec@1

Linux 권한 문제

당신이 만난다면 EACCES 권한 오류가 있는 경우 다음을 수행할 수 있습니다.

1. 사용 sudo: sudo npm install -g @fission-ai/openspec@1
2. 사용자 디렉터리를 사용하도록 npm을 구성합니다.

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

설치 확인

설치 후 OpenSpec이 올바르게 설치되었고 버전이 요구 사항을 충족하는지 확인하십시오.

openspec --version

성공적으로 설치되면 다음과 같은 버전 번호 출력이 표시됩니다.

openspec/1.1.1 linux-x64 node-v18.17.0

:::참고[버전 범위] 설치된 OpenSpec 버전이 1.0.0 이상인지 확인하세요. 프로젝트는 버전 1.1.1과의 호환성을 확인했습니다. 새로운 기능을 얻으려면 최신 호환 버전을 사용하는 것이 좋습니다. :::

일반적인 문제 및 문제 해결

권한 오류

문제: EACCES 권한이 거부되었습니다

OpenSpec을 설치하거나 실행할 때 권한 오류가 발생합니다.

해결책:

Windows

PowerShell 또는 명령 프롬프트를 관리자로 실행합니다.

1. PowerShell 또는 명령 프롬프트를 마우스 오른쪽 버튼으로 클릭합니다.
2. “관리자 권한으로 실행”을 선택하세요.
3. 설치 명령을 다시 실행하십시오.

macOS

다음을 사용하여 설치 sudo:

sudo npm install -g @fission-ai/openspec@1

또는 사용 NVM Node.js를 관리하고 전역 설치 권한 문제를 방지합니다.

Linux

해결 방법 1: sudo 사용

sudo npm install -g @fission-ai/openspec@1

해결 방법 2: 사용자 디렉터리를 사용하도록 npm 구성

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @fission-ai/openspec@1

네트워크 문제

문제: npm 설치가 실패하거나 매우 느림

네트워크 문제로 인해 npm 레지스트리에서 OpenSpec을 다운로드할 수 없습니다.

해결책:

1. 국내 npm 미러 사용:

# Use Taobao mirror
npm config set registry https://registry.npmmirror.com

# Then reinstall
npm install -g @fission-ai/openspec@1

2. 공식 소스 복원(필요한 경우):

npm config set registry https://registry.npmjs.org

3. cnpm 사용(선택 사항):

npm install -g cnpm --registry=https://registry.npmmirror.com
cnpm install -g @fission-ai/openspec@1

:::팁 중국 본토 사용자는 다운로드 속도를 크게 향상시킬 수 있는 Taobao 미러를 사용하는 것이 좋습니다. :::

버전 호환성 문제

문제: OpenSpec 명령이 비정상적으로 실행되거나 오류를 보고함

설치된 OpenSpec 버전이 현재 환경과 호환되지 않습니다.

해결책:

1. Node.js 버전 확인:

node --version

버전이 18.0 이상인지 확인하세요. 버전이 너무 낮으면 Node.js를 업그레이드하세요.

2. OpenSpec 버전 확인:

openspec --version

3. 특정 버전 재설치:

npm install -g @fission-ai/openspec@1

4. npm 캐시 지우기(문제가 지속되는 경우):

npm cache clean --force
npm install -g @fission-ai/openspec@1

명령을 찾을 수 없음

문제: 입력 중 openspec 명령에 “명령을 찾을 수 없음”이 표시됩니다.

OpenSpec이 설치되었지만 시스템이 명령을 찾을 수 없습니다.

해결책:

Windows

1. npm 전역 설치 경로를 확인하세요.

npm config get prefix

2. 시스템 PATH에 경로 추가:
   • “시스템 속성” → “고급” → “환경 변수”를 엽니다.
   • 찾기 Path “시스템 변수”에서
   • npm 전역 경로 추가(일반적으로 C:\Users\<username>\AppData\Roaming\npm)
   • 명령줄 창 다시 시작

macOS

1. npm 전역 설치 경로를 확인하세요.

npm config get prefix

2. PATH에 경로 추가( ~/.zshrc 또는 ~/.bash_profile):

export PATH="$(npm config get prefix)/bin:$PATH"

3. 구성 다시 로드:

source ~/.zshrc

Linux

1. npm 전역 설치 경로를 확인하세요.

npm config get prefix

2. PATH에 경로 추가( ~/.bashrc):

export PATH="$(npm config get prefix)/bin:$PATH"

3. 구성 다시 로드:

source ~/.bashrc

OpenSpec 업그레이드

:::참고[버전 범위] 이 프로젝트에는 OpenSpec 1.0.0 이상의 버전 범위를 사용해야 합니다. 버전 업데이트 요구 사항이 있는 경우 프로젝트 설명서를 참조하세요. :::

특정 버전을 다시 설치해야 하는 경우:

npm install -g @fission-ai/openspec@1

OpenSpec 제거

OpenSpec을 제거해야 하는 경우:

Windows

npm uninstall -g @fission-ai/openspec

macOS

npm uninstall -g @fission-ai/openspec

또는 sudo를 사용하십시오:

sudo npm uninstall -g @fission-ai/openspec

Linux

npm uninstall -g @fission-ai/openspec

또는 sudo를 사용하십시오:

sudo npm uninstall -g @fission-ai/openspec

다음 단계

OpenSpec 설치가 완료된 후 다음 단계를 계속할 수 있습니다.

Wizard Setup See how first launch checks OpenSpec and related dependencies, then completes project creation inside the wizard.

Create Proposal Session Learn about the proposal-driven development workflow and transform abstract ideas into structured implementation plans.

:::팁 더 자세한 OpenSpec 사용 가이드는 다음을 참조하세요. OpenSpec 공식 문서. :::

도움이 더 필요하신가요?

여기서 다루지 않은 문제가 발생하는 경우:

1. 확인 OpenSpec GitHub 문제 비슷한 문제에 대해
2. 방문 OpenSpec 공식 문서 자세한 내용은
3. 관련 가이드를 참고하세요. HagiCode 문서 사이트 추가 도움이 필요한 경우