OpenSpec

시작하기 ​

이 가이드는 OpenSpec을 설치하고 초기화한 후 작동 방식을 설명합니다. 설치 방법은 메인 README 또는 설치 가이드를 참조하세요. 전체 문서 집합이 처음이신가요? 문서 홈에서 모든 내용을 파악할 수 있습니다.

어디서 이 명령어를 입력하나요? 두 가지 장소가 있으며, 이를 혼동하는 것이 초보자가 가장 흔히 겪는 실수입니다.

  • openspec ... 명령어(예: openspec init)는 터미널에서 실행됩니다.
  • /opsx:... 명령어(예: /opsx:propose)는 AI 어시스턴트의 채팅에서 실행됩니다. 코드를 작성해 달라고 요청하는 것과 동일한 창입니다.

별도의 "대화형 모드"를 시작할 필요가 없습니다. 채팅창에 슬래시 명령어를 입력하면 어시스턴트가 알아서 처리합니다. 자세한 설명은 명령어 작동 방식을 참조하세요.

첫 5분 ​

전체 루프와 각 단계가 수행되는 위치:

text
TERMINAL   $ npm install -g @fission-ai/openspec@latest
TERMINAL   $ cd your-project && openspec init
AI CHAT      /opsx:explore                    (선택 사항: 먼저 고민해 보세요)
AI CHAT      /opsx:propose add-dark-mode      (AI가 계획을 초안 작성; 사용자가 검토)
AI CHAT      /opsx:apply                      (AI가 구현)
AI CHAT      /opsx:archive                    (사양 업데이트, 변경 사항 보관)

터미널에서 설정 단계를 두 번 거친 후, 나머지 작업은 채팅에서 진행합니다. 이 가이드의 나머지 부분에서는 각 단계의 동작과 표시되는 내용을 자세히 설명합니다.

터미널 작업을 직접 하고 싶지 않으신가요? 설정 프롬프트를 어시스턴트에 붙여넣기만 하면 두 줄의 명령어를 모두 처리하고 생성된 내용을 보고합니다.

아직 무엇을 만들지 결정하지 못하셨나요? /opsx:explore로 시작하세요. 이는 부담 없이 생각할 수 있는 파트너로, 코드베이스를 읽고 옵션을 평가하며, 어떤 아티팩트나 코드가 존재하기 전에 모호한 아이디어를 구체적인 계획으로 다듬어 줍니다. 그림이 선명해지면 /opsx:propose로 넘깁니다. 이는 AI가 다른 방식으로 확신에 차 있어 잘못된 것을 구축할 경우 대비하여 가장 좋은 습관입니다. 탐색 가이드를 참조하세요.

작동 방식 ​

OpenSpec은 코드가 작성되기 전에 사용자와 AI 코딩 어시스턴트가 무엇을 구축할지 합의하도록 도와줍니다.

기본 빠른 경로(코어 프로필):

text
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
   (선택 사항)

무엇을 해야 할지 고민 중이라면 /opsx:explore로 시작하거나, 이미 알고 있다면 바로 /opsx:propose로 이동하세요. 탐색은 기본 프로필에 포함되어 있으므로 필요할 때 항상 사용할 수 있습니다.

확장 경로(사용자 정의 워크플로우 선택):

text
/opsx:new ──► /opsx:ff or /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

기본 전역 프로필은 core이며, 여기에는 propose, explore, apply, update, sync, archive가 포함됩니다. 확장 워크플로우 명령어를 활성화하려면 openspec config profile 및 openspec update를 사용하세요.

OpenSpec이 생성하는 것 ​

openspec init 실행 후 프로젝트에는 다음과 같은 구조가 생성됩니다:

openspec/
├── specs/              # 진실의 원천(시스템의 동작)
│   └── <domain>/
│       └── spec.md
├── changes/            # 제안된 업데이트(변경 사항당 하나의 폴더)
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # 델타 사양(변경 내용)
│           └── <domain>/
│               └── spec.md
└── config.yaml         # 프로젝트 구성(선택 사항)

두 가지 주요 디렉토리:

  • specs/ - 진실의 원천입니다. 이 사양들은 현재 시스템이 어떻게 동작하는지 설명합니다. 도메인별로 조직화됩니다(예: specs/auth/, specs/payments/).

  • changes/ - 제안된 수정 사항입니다. 각 변경 사항에는 관련 아티팩트가 포함된 고유한 폴더가 부여됩니다. 변경 사항이 완료되면 해당 사양이 메인 specs/ 디렉토리에 병합됩니다.

아티팩트 이해하기 ​

각 변경 폴더에는 작업을 안내하는 아티팩트가 포함되어 있습니다:

아티팩트목적
proposal.md"왜"와 "무엇" - 의도, 범위 및 접근 방식 기록
specs/추가/수정/삭제된 요구 사항을 보여주는 델타 사양
design.md"어떻게" - 기술적 접근 방식 및 아키텍처 결정
tasks.md체크박스가 있는 구현 체크리스트

아티팩트는 서로 의존합니다:

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            학습하면서 업데이트

구현 과정에서 더 많은 정보를 알게 되면 이전 아티팩트로 돌아가서 정교하게 다듬을 수 있습니다.

델타 사양 작동 방식 ​

델타 사양은 OpenSpec의 핵심 개념입니다. 현재 사양에 비해 변경되는 내용을 보여줍니다.

형식 ​

델타 사양은 섹션을 사용하여 변경 유형을 나타냅니다:

markdown
# Auth에 대한 델타

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented

## MODIFIED Requirements

### Requirement: Session Timeout
The system SHALL expire sessions after 30 minutes of inactivity.
(Previously: 60 minutes)

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated

## REMOVED Requirements

### Requirement: Remember Me
(Deprecated in favor of 2FA)

보관(Archive) 시 발생하는 일 ​

변경 사항을 보관할 때:

  1. ADDED 요구 사항은 메인 사양에 추가됩니다.
  2. MODIFIED 요구 사항은 기존 버전을 대체합니다.
  3. REMOVED 요구 사항은 메인 사양에서 삭제됩니다.

변경 폴더는 감사 기록을 위해 openspec/changes/archive/로 이동합니다.

예제: 첫 번째 변경 사항 ​

애플리케이션에 다크 모드를 추가하는 과정을 살펴보겠습니다.

1. 변경 시작(기본값) ​

text
You: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — why we're doing this, what's changing
     ✓ specs/       — requirements and scenarios
     ✓ design.md    — technical approach
     ✓ tasks.md     — implementation checklist
     Ready for implementation!

확장 워크플로우 프로필을 활성화했다면 /opsx:new 다음에 /opsx:ff(또는 점진적으로 /opsx:continue)로 두 단계로 수행할 수도 있습니다.

2. 생성되는 내용 ​

proposal.md - 의도를 캡처합니다:

markdown
# Proposal: Add Dark Mode

## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage.

## Scope
- Add theme toggle in settings
- Support system preference detection
- Persist preference in localStorage

## Approach
Use CSS custom properties for theming with a React context
for state management.

specs/ui/spec.md - 새로운 요구 사항을 보여주는 델타:

markdown
# Delta for UI

## ADDED Requirements

### Requirement: Theme Selection
The system SHALL allow users to choose between light and dark themes.

#### Scenario: Manual toggle
- GIVEN a user on any page
- WHEN the user clicks the theme toggle
- THEN the theme switches immediately
- AND the preference persists across sessions

#### Scenario: System preference
- GIVEN a user with no saved preference
- WHEN the application loads
- THEN the system's preferred color scheme is used

tasks.md - 구현 체크리스트:

markdown
# Tasks

## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence

## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle

## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables

3. 구현 ​

You: /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Created ThemeContext with light/dark state
     ✓ 1.2 Added CSS custom properties to globals.css
     ✓ 1.3 Implemented localStorage persistence
     ✓ 2.1 Created ThemeToggle component
     ...
     All tasks complete!

구현 중에 설계 조정이 필요하다는 것을 발견하면 아티팩트를 업데이트하고 계속 진행하면 됩니다.

4. 보관 ​

You: /opsx:archive

AI:  Archiving add-dark-mode...
     ✓ Merged specs into openspec/specs/ui/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
     Done! Ready for the next feature.

이제 델타 사양이 메인 사양의 일부가 되어 시스템이 어떻게 작동하는지 문서를 작성합니다.

검증 및 검토 ​

CLI를 사용하여 변경 사항을 확인하세요:

bash
# 활성 변경 사항 목록
openspec list

# 변경 사항 세부 정보 보기
openspec show add-dark-mode

# 사양 형식 유효성 검사
openspec validate add-dark-mode

# 대화형 대시보드
openspec view

다음 단계 ​