설치

사전 요구 사항

• Node.js 20.19.0 이상 — 버전 확인: node --version

AI 어시스턴트로 설치

직접 하지 않으시겠어요? 아래 프롬프트를 셸 명령을 실행할 수 있는 모든 코딩 어시스턴트(Claude Code, Codex, Cursor, Gemini CLI, Copilot 및 기타 지원 도구)에 붙여넣으세요. 그러면 CLI를 설치하고, 이 프로젝트를 초기화하고, 실제로 발생한 일을 보고합니다.

아래 수동 단계가 진실의 원천입니다 — 프롬프트는 그 단계들을 실행해 줄 뿐입니다. 어시스턴트가 멈추고 무언가를 돌려주면, 그것은 설계상의 동작입니다: 권한이 필요한 작업 전에 묻고, 셸 시작 파일을 절대 편집하지 않습니다. 그 부분들은 패키지 관리자 및 문제 해결 섹션에서 직접 완료하세요.

이 프로젝트에 OpenSpec을 설치하고 설정해 주세요. 다음 단계를 순서대로 따르고, 단계가 멈추라고 하면 멈추세요.

1. 런타임. `node --version`을 실행하세요. OpenSpec은 Node.js 20.19.0 이상이 필요합니다. Node가 없거나 더 오래된 버전이면 말하고 멈추세요 — Node를 설치하거나, 버전을 전환하거나, 제 버전 관리자를 재구성하지 마세요.

2. 설치. 이미 내 PATH에 있는 패키지 관리자를 사용하되, npm을 우선합니다:
     npm install -g @fission-ai/openspec@latest
     pnpm add -g @fission-ai/openspec@latest
     bun add -g @fission-ai/openspec@latest
     yarn global add @fission-ai/openspec@latest   (Yarn 1.x만)
   이 프로젝트의 잠금 파일을 기준으로 선택하지 마세요 — 글로벌 설치는 이 저장소의 자체 종속성 설치 방식과 관련이 없습니다. 네 가지 중 어떤 것도 사용할 수 없으면 멈추고 알려 주세요 — 즉흥적으로 설치하지 마세요. (Nix를 사용 중이라면 OpenSpec 설치 문서의 Nix 섹션을 안내해 주세요.) 정확한 명령을 보여 주고 실행 전 제가 확인하게 해 주세요; 이는 프로젝트 외부에 소프트웨어를 설치하므로, 다른 패키지 관리자가 이를 관리하길 원할 수도 있습니다. 설치에 sudo 또는 관리자 권한이 필요하거나, 권한 오류로 실패하거나, 글로벌 bin 디렉토리가 없거나 구성되지 않았다고 보고하면 멈추고 다시 물어보세요. 셸 시작 파일(.bashrc, .zshrc, .profile, fish, PowerShell profile)을 절대 편집하지 말고, 그것들을 편집하는 설정 명령을 실행하지 마세요 — 변경 사항을 보여 주고 제가 직접 하게 하세요.

3. PATH. `openspec --version`을 실행하세요. 명령을 찾을 수 없다면, 이 셸에 경로가 없을 뿐일 수 있습니다: 패키지 관리자가 설치한 위치와 해당 디렉토리를 내 셸과 OS의 PATH에 추가하는 방법을 알려 주고, 제가 확인할 때까지 멈추세요. 방금 설치가 보고한 버전보다 더 오래된 버전이 출력된다면, 이전 복사본이 PATH에서 가리고 있는 것입니다 — 계속하지 말고 두 버전을 모두 알려 주세요. 버전 관리자를 사용한다면, PATH를 편집하지 말고 그렇게 말하세요: nvm 또는 fnm을 사용하면 CLI는 설치 당시 활성화된 Node 버전에 묶여 있고, asdf 또는 volta를 사용하면 shim을 다시 생성해야 할 수 있습니다.

4. 초기화. 어떤 AI 코딩 도구(들)를 사용하는지 물어보고, 각각을 `openspec init --help`의 ID에 매핑하세요 (Copilot는 `github-copilot`, Zoo Code는 `roocode`). `--tools`는 쉼표로 구분된 목록을 받으므로 모두 나열하세요. `openspec init --tools <ids>`는 이전 OpenSpec 버전의 잔여물을 자동으로 삭제합니다 — 묻지 않고, 내 홈 디렉토리의 `opsx-*.md` 프롬프트 파일(Codex는 ~/.codex/prompts에 보관)을 포함합니다. 실행하기 전에 그것들을 찾으세요: `.../commands/openspec/` 폴더, CLAUDE.md 또는 AGENTS.md와 같은 파일의 OpenSpec 마커 블록, 그리고 홈 디렉토리의 `opsx-*.md` 프롬프트. 발견한 것을 나열하고 제 승인을 기다리세요; 아무것도 없으면 말하고 묻지 않고 계속 진행하세요. 기존 `openspec/` 폴더는 문제가 아닙니다 — init가 그것을 새로 고치고 내 스펙과 변경 사항은 그대로 둡니다. 올바른 폴더에 있는지도 확인하세요: init는 실행된 위치(모노레포 패키지 내부 포함)에 `openspec/`를 생성합니다. 그런 다음 실행: openspec init --tools <ids>

5. 보고. 무엇이 있어야 한다고 가정하지 말고 — init가 실제로 출력한 내용을 알려 주세요: 생성된 스킬 및/또는 명령의 수와 위치, 구성 파일 줄, 'Setup required' 메모, 재시작 또는 다시 로드할 항목. 일부 도구는 스킬 전용이며 명령 파일을 0개 생성하는 것이 정상이므로, 명령이 없다고 해서 그 자체로 실패는 아닙니다. init가 아무것도 생성되지 않았다고 하면, 다시 시도하지 말고 제안된 수정 사항을 전달하세요. 마지막으로 내 도구에서 OpenSpec을 호출하는 방법을 알려 주고, init가 생성한 파일에서 정확한 철자를 가져와야 합니다(요약 줄에서가 아니라): 도구마다 구두점이 다릅니다(/opsx:propose, /opsx-propose, Amazon Q의 @opsx-propose), 명령 대신 스킬을 받는 도구는 스킬 이름으로 호출합니다(/openspec-propose, Codex에서 $openspec-propose, Kimi Code에서 /skill:openspec-propose).

프롬프트에는 특정 공급업체만의 것이 없습니다: 일반 지침과 이 페이지에 문서화된 동일한 명령일 뿐입니다. macOS, Linux, Windows에서 작동하며, 단계에 권한이 필요할 때 즉흥적으로 하지 않고 의도적으로 멈춥니다. 어시스턴트가 셸 명령을 실행할 수 있어야 합니다 — 일부 IDE 통합은 그럴 수 없습니다.

패키지 관리자

npm

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

pnpm

pnpm add -g @fission-ai/openspec@latest

yarn

yarn global add @fission-ai/openspec@latest

Yarn 2 이상(Berry)은 global 명령을 제거했습니다. 해당 버전에서는 대신 npm, pnpm 또는 bun으로 OpenSpec을 설치하세요 — 글로벌 CLI는 프로젝트의 패키지 관리자를 공유할 필요가 없습니다.

deno

Deno는 때때로 @latest 태그를 구문 분석하는 데 문제가 있습니다. 처음 설치할 때 버전을 지정할 수 있습니다. 그런 경우, @latest 태그를 버전으로 변경해 볼 수 있습니다(예: @^1.3.1).

deno install --global \
  --allow-read --allow-write --allow-env --allow-sys=cpus,homedir --allow-net=edge.openspec.dev \
  npm:@fission-ai/openspec@latest
# 또는
deno install --global \
  --allow-read --allow-write --allow-env --allow-sys=cpus,homedir --allow-net=edge.openspec.dev \
  npm:@fission-ai/openspec@^1.3.1

참고: 하위 명령이 config edit, feedback, workspace open과 같은 외부 도구를 실행하는 경우, 범위가 지정된 --allow-run=<program>이 필요할 수 있습니다.

bun

Bun은 OpenSpec을 전역으로 설치할 수 있지만, OpenSpec은 현재 Node.js에서 실행됩니다. 여전히 PATH에 Node.js 20.19.0 이상이 필요합니다.

bun add -g @fission-ai/openspec@latest

Nix

설치 없이 OpenSpec을 직접 실행:

nix run github:Fission-AI/OpenSpec -- init

또는 프로필에 설치:

nix profile install github:Fission-AI/OpenSpec

또는 flake.nix에서 개발 환경에 추가:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    openspec.url = "github:Fission-AI/OpenSpec";
  };

  outputs = { nixpkgs, openspec, ... }: {
    devShells.x86_64-linux.default = nixpkgs.legacyPackages.x86_64-linux.mkShell {
      buildInputs = [ openspec.packages.x86_64-linux.default ];
    };
  };
}

설치 확인

openspec --version

업데이트

패키지를 업그레이드한 후 각 프로젝트의 생성된 파일을 새로 고치세요:

npm install -g @fission-ai/openspec@latest   # 또는 pnpm/yarn/bun 동일
openspec update                              # 각 프로젝트 내에서 실행

openspec update는 구성된 도구에 대한 스킬 및 명령 파일을 다시 생성하므로, 슬래시 명령이 설치된 버전과 최신 상태를 유지합니다. 또한 더 새로운 CLI가 게시되었는지 확인하고 업그레이드를 제안합니다. 업그레이드가 새로운 워크플로우를 이용할 수 있게 만드는 첫 번째 단계이기 때문입니다 — CLI 참조를 참조하세요.

제거

openspec uninstall 명령은 없습니다. OpenSpec은 글로벌 패키지와 프로젝트에 있는 일부 파일일 뿐이기 때문입니다. 제거는 몇 가지 수동 단계로 이루어지며, 여기의 어떤 것도 소스 코드를 건드리지 않습니다.

1. 글로벌 패키지 제거:

npm uninstall -g @fission-ai/openspec   # 또는: pnpm rm -g / yarn global remove / bun rm -g

2. 프로젝트에서 OpenSpec 제거 (선택 사항). 더 이상 스펙과 변경 사항이 필요 없다면 openspec/ 디렉토리를 삭제하세요:

rm -rf openspec/

이 작업을 수행하기 전에 생각해 보세요: openspec/specs/와 openspec/changes/archive/는 시스템이 어떻게 동작하고 왜 변경되었는지에 대한 기록입니다. 그 기록이 필요할 수 있다면, 제거 후에도 폴더를 유지하거나 git에 보관하세요.

3. 생성된 AI 도구 파일 제거 (선택 사항). OpenSpec은 도구별 디렉토리(예: .claude/skills/openspec-*/, .cursor/commands/opsx-* 등)에 스킬 및 명령 파일을 작성합니다. 구성한 도구에 대해 openspec-* 스킬과 opsx-* 명령을 삭제하세요. 도구별 정확한 경로는 지원 도구에 나열되어 있습니다.

또한 CLAUDE.md 또는 AGENTS.md와 같은 파일에 OpenSpec 마커 블록이 있다면, 수동으로 제거하세요; 해당 파일의 본인 콘텐츠는 유지하세요.

다음 단계

설치 후, 프로젝트에서 OpenSpec을 초기화하세요:

cd your-project
openspec init

전체 안내는 시작하기를 참조하세요.