명령어 작동 방식

한 가지 핵심: OpenSpec에는 두 종류의 명령어가 있으며, 두 가지 다른 곳에서 실행됩니다.

• openspec ... 명령어는 터미널에서 실행됩니다. (예: openspec init.)
• /opsx:... 명령어는 AI 어시스턴트의 채팅에서 실행됩니다. (예: /opsx:propose.)

만약 터미널에 /opsx:propose를 입력했는데 아무 일도 일어나지 않는다면, 이 페이지가 그 이유입니다. 여러분은 OpenSpec의 잘못된 부분과 대화하고 있는 것입니다. 슬래시 명령어는 터미널 명령어가 아닙니다. 여러분이 평소에 "로그인 폼 추가"라고 입력하는 것과 같은 채팅 상자에서 AI 코딩 어시스턴트에게 주는 지침입니다.

이 단 하나의 구분이 새로운 사용자들이 가장 자주 겪는 걸림돌이므로, 완벽하게 명확하게 해두겠습니다.

두 부분

CLI (터미널 부분). 셸에서 설치하고 실행하는 openspec이라는 프로그램입니다. 프로젝트를 설정하고, 변경 사항을 나열하고 검증하고, 대시보드를 표시하고, 완료된 작업을 보관합니다. iTerm, VS Code 터미널, PowerShell, git이나 npm을 실행하는 어디서든 입력할 수 있습니다.

openspec init        # 이 프로젝트에 OpenSpec 설정
openspec list        # 활성 변경 사항 확인
openspec view        # 대화형 대시보드 열기

슬래시 명령어 (채팅 부분). /opsx:propose나 /opsx:apply 같은 짧은 명령어로, AI 어시스턴트에 입력합니다. 이 명령어는 AI에게 OpenSpec 워크플로우를 따르도록 지시합니다: 제안서 작성, 스펙 작성, 작업 목록에서 구축, 완료 시 보관. Claude Code, Cursor, Devin Desktop, Copilot 또는 사용 중인 어시스턴트에 입력합니다.

/opsx:propose add-dark-mode    (AI 채팅에 입력)
/opsx:apply                    (AI 채팅에 입력)
/opsx:archive                  (AI 채팅에 입력)

한 장의 그림으로 정리한 개념 모델은 다음과 같습니다:

        당신의 터미널                        당신의 AI 어시스턴트 채팅
   ┌──────────────────────┐               ┌──────────────────────────────┐
   │  $ openspec init     │   설치       │  /opsx:propose add-dark-mode  │
   │  $ openspec list     │  ──────────►  │  /opsx:apply                  │
   │  $ openspec view     │   명령어 &    │  /opsx:archive                │
   └──────────────────────┘    스킬      └──────────────────────────────┘
        여기에서 openspec 실행                       여기에서 /opsx:* 실행

화살표에 주목하세요. 터미널에서 openspec init을 실행하는 것이 AI 도구에 슬래시 명령어를 설치하는 것입니다. 터미널 부분이 채팅 부분을 설정합니다. 그 후에는 일상적인 사용은 대부분 채팅에서 이루어집니다.

"대화형 모드는 어떻게 시작하나요?"

시작할 별도의 대화형 모드는 없습니다. 이 질문은 자주 나오므로 명확한 답변이 필요합니다.

특별한 OpenSpec 모드에 진입할 필요가 없습니다. 평소처럼 AI 코딩 어시스턴트를 열고 채팅에 슬래시 명령어를 입력하면 됩니다. 슬래시 명령어가 바로 OpenSpec에 '진입'하는 방법입니다. 어시스턴트가 이를 인식하고 해당 OpenSpec 스킬을 로드한 후 워크플로우를 따르기 시작합니다.

실제 지침은 다음과 같습니다:

1. 프로젝트에서 AI 코딩 어시스턴트(Claude Code, Cursor, Devin Desktop 등)를 엽니다.
2. 다른 요청을 입력하는 동일한 채팅에 /opsx:propose를 입력합니다.
3. 자동 완성을 확인하세요: OpenSpec이 설치되어 있다면 슬래시를 입력할 때 /opsx:propose, /opsx:apply 등이 나타납니다.

그게 전부입니다. 전환할 모드도, 실행할 데몬도, 별도의 창도 없습니다.

터미널에서 실제로 대화형인 것이 하나 있습니다: openspec view입니다. 이는 스펙과 변경 사항을 탐색하기 위한 대시보드를 엽니다. 하지만 이는 뷰어일 뿐, 제안하고 구축하는 도구는 아닙니다. 구축은 채팅의 슬래시 명령어를 통해 이루어집니다.

왜 이렇게 나뉘어 있는가

이해할 가치가 있습니다. OpenSpec이 30개 이상의 다양한 AI 도구와 함께 작동하는 이유를 설명하기 때문입니다.

CLI는 엔진입니다. 규칙을 알고 있습니다: 변경 폴더의 모양, 어떤 아티팩트가 어떤 것에 의존하는지, 델타 스펙을 소스 오브 트루스에 병합하는 방법 등. 이는 어디서나 동일합니다.

슬래시 명령어는 운전대이며, 각 AI 도구마다 조금씩 다릅니다. Claude Code는 이를 명령어라고 부릅니다. Cursor와 Devin Desktop은 자체 형식을 가지고 있습니다. 일부 도구는 스킬이라고 부릅니다. openspec init을 실행하면 OpenSpec이 선택한 각 도구에 적합한 파일을 생성하므로, 선호하는 어시스턴트가 무엇이든 동일한 /opsx:propose 의도가 작동합니다.

이 설계의 강점: 워크플로우를 한 번 배우면 여러 도구에서 사용할 수 있습니다. 단점: 명령어의 정확한 구문은 도구마다 약간 다를 수 있으며, 이는 다음 섹션에서 다룹니다.

도구별 슬래시 명령어 구문

의도는 어디서나 동일합니다. 철자는 도구가 로드하는 파일을 따릅니다.

도구의 명령어 파일	입력 방법	예시 도구
.../commands/opsx/<id>.*	/opsx:propose	Claude Code, Gemini CLI, Crush
.../opsx-<id>.*	/opsx-propose	Cursor, GitHub Copilot (IDE), Devin Desktop, Trae, Oh My Pi
.amazonq/prompts/opsx-<id>.md	@opsx-propose	Amazon Q Developer
없음 — 스킬만	/openspec-propose	CodeArts, ForgeCode, Hermes, Mistral Vibe, Zed Agent, shared .agents
없음 — Kimi Code	/skill:openspec-propose	Kimi Code
없음 — Codex CLI	$openspec-propose	Codex

Devin은 두 행에 걸쳐 있는 유일한 도구입니다. Devin Desktop은 .devin/workflows/를 읽으므로 /opsx-propose가 작동합니다. Devin Local은 그렇지 않으며, 해당 에이전트에서는 대신 /openspec-propose 스킬을 사용하세요. OpenSpec이 .devin/skills/에 작성하는 스킬은 둘 다에서 작동하며, 그래서 스킬 이름으로 서로를 참조하는 것입니다.

모든 도구는 How To Invoke에 나열되어 있습니다 — 해당 표가 공식적인 참조입니다. 두 행은 전혀 슬래시 명령어가 아닙니다: Amazon Q는 파일을 프롬프트 라이브러리에 로드하여 @로 호출하고, 마지막 세 행은 스킬 이름을 사용하는데, 이는 명령어 ID가 아닙니다 (/opsx:apply는 openspec-apply-change 스킬입니다).

의심스러우면 openspec init이 출력한 'Getting started' 줄을 읽어보세요: 이미 도구가 등록한 형식을 사용합니다. 슬래시를 입력하고 자동 완성을 확인하는 방법도, 슬래시 명령어를 표시하는 도구에서 작동합니다.

명령어가 어떻게 거기에 있는지: 스킬과 명령어

openspec init(또는 openspec update)을 실행하면 OpenSpec이 프로젝트에 작은 파일을 작성하여 AI 도구가 워크플로우를 찾을 수 있게 합니다. 도구와 설정에 따라 이는 스킬, 명령어, 또는 둘 다일 수 있습니다.

• 스킬은 .claude/skills/openspec-*/SKILL.md와 같은 위치에 있습니다. 이는 새로운 크로스 도구 표준입니다: 어시스턴트가 자동으로 감지하는 지침 폴더입니다.
• 명령어는 .cursor/commands/opsx-<id>.md 또는 .claude/commands/opsx/<id>.md와 같은 위치에 있습니다 — 레이아웃은 도구의 것이며, 명령어를 입력하는 방법을 결정합니다. 이는 기존의 도구별 슬래시 명령어 파일입니다. Codex는 생성된 명령어 파일을 얻지 못합니다; .agents/skills/openspec-*를 사용하세요.

도구가 어떤 것을 사용하는지 신경 쓸 필요가 없습니다. 슬래시 명령어를 입력하면 작동합니다. 하지만 문제가 발생했을 때 이러한 파일이 존재한다는 것을 알면 도움이 됩니다: 명령어가 사라진 경우, 일반적으로 이 파일들이 없거나 오래된 것이며, openspec update가 다시 생성합니다.

각 도구의 정확한 경로는 지원 도구를 참조하고, 스킬이 기존의 명령어 전용 접근 방식을 어떻게 대체했는지는 마이그레이션 가이드를 참조하세요.

설치 확인

빠른 확인 방법, 가장 빠른 것부터:

1. AI 채팅에 슬래시를 입력하세요. /opsx 입력을 시작하고 자동 완성 제안을 확인하세요. 나타나면 준비된 것입니다. 스킬 전용 도구(Codex, Kimi Code, CodeArts, ForgeCode, Hermes, Mistral Vibe, Zed Agent 또는 공유 .agents 대상)에서는 정상 설치 상태에서도 /opsx가 완성되지 않습니다 — 대신 위 표의 스킬 이름을 시도하세요.
2. 파일을 확인하세요. Claude Code의 경우 .claude/skills/에 openspec-* 폴더가 포함되어 있는지 확인하세요. 다른 도구는 자체 디렉터리를 사용합니다 (지원 도구에 나열되어 있습니다).
3. 설정을 다시 실행하세요. 프로젝트 루트에서 openspec update를 실행하세요. 구성한 도구에 대한 스킬 및 명령어 파일을 다시 생성합니다.
4. 어시스턴트를 다시 시작하세요. 많은 도구가 시작 시 스킬과 명령어를 스캔하므로, 새 창이 누락된 단계일 수 있습니다.

어떤 명령어가 있나요?

기본적으로 OpenSpec은 핵심 슬래시 명령어 세트를 설치합니다:

• /opsx:explore: 변경을 확정하기 전에 AI와 아이디어를 생각해 봅니다 (확신이 없을 때 좋은 첫 단계입니다)
• /opsx:propose: 변경을 생성하고 모든 계획 아티팩트를 한 단계로 작성합니다
• /opsx:apply: 작업 목록을 진행하여 변경을 구축합니다
• /opsx:update: 변경의 계획 아티팩트를 수정하고 일관성을 유지합니다
• /opsx:sync: 변경의 스펙 업데이트를 메인 스펙에 병합합니다 (보통 자동)
• /opsx:archive: 변경을 완료하고 보관합니다

좋은 기본 리듬: 무엇을 할지 파악할 때 explore, 그 다음 propose, apply, archive. Explore First 가이드가 그 시작 단계가 왜 효과적인지 설명합니다.

더 세밀한 제어를 원하는 사용자를 위한 확장 세트도 있습니다 (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard). openspec config profile로 켜고, openspec update로 적용할 수 있습니다.

이 모든 것이 처음이신가요? /opsx:onboard(확장 세트에 포함)는 자신의 코드베이스에서 완전한 변경 과정을 단계별로 안내합니다. 가장 친절한 소개가 될 것입니다.

각 명령어의 자세한 내용은 명령어를 참조하세요. 어떤 상황에서 어떤 것을 사용할지에 대해서는 워크플로우를 참조하세요.

깔끔한 첫 실행

종합하면, 각 단계가 발생하는 위치로 라벨된 전체 순서는 다음과 같습니다.

터미널   $ npm install -g @fission-ai/openspec@latest
터미널   $ cd your-project
터미널   $ openspec init
              (AI 도구에 슬래시 명령어 설치)

AI 채팅      /opsx:explore
              (선택 사항: 먼저 AI와 아이디어를 검토)

AI 채팅      /opsx:propose add-dark-mode
              (AI가 제안서, 스펙, 설계, 작업 작성)

AI 채팅      /opsx:apply
              (AI가 구축하고 작업 확인)

AI 채팅      /opsx:archive
              (변경이 스펙에 병합되고 보관됨)

설정을 위한 두 가지 터미널 단계. 그 후에는 채팅에서 생활합니다. 그것이 리듬입니다.

관련 문서

• Getting Started: 전체 첫 변경 과정 안내
• Commands: 모든 슬래시 명령어 자세히
• CLI: 모든 터미널 명령어 자세히
• Supported Tools: 도구별 구문 및 파일 위치
• FAQ: 더 많은 빠른 답변
• Troubleshooting: 명령어가 표시되지 않을 때 해결 방법