시작하기
이 가이드는 OpenSpec을 설치하고 초기화한 후 작동 방식을 설명합니다. 설치 지침은 메인 README를 참조하세요.
작동 방식
OpenSpec은 코드가 작성되기 전에 무엇을 만들 것인지 당신과 AI 코딩 어시스턴트가 합의할 수 있도록 도와줍니다.
기본 빠른 경로 (코어 프로필):
text
/opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive확장 경로 (사용자 정의 워크플로 선택):
text
/opsx:new ──► /opsx:ff 또는 /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive기본 글로벌 프로필은 core이며, propose, explore, apply, 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 델타
## 추가된 요구사항
### 요구사항: 이중 인증
시스템은 로그인 시 두 번째 인증 요소를 요구해야 합니다.
#### 시나리오: OTP 필요
- 2FA가 활성화된 사용자가 있을 때
- 사용자가 유효한 자격 증명을 제출하면
- OTP 인증이 제시됨
## 수정된 요구사항
### 요구사항: 세션 타임아웃
시스템은 30분 동안 비활성 상태일 경우 세션을 만료시켜야 합니다.
(이전: 60분)
#### 시나리오: 유휴 타임아웃
- 인증된 세션이 있을 때
- 30분 동안 활동이 없으면
- 세션이 무효화됨
## 삭제된 요구사항
### 요구사항: 로그인 상태 유지
(2FA를 위해 더 이상 사용되지 않음)아카이브 시 발생하는 일
변경사항을 아카이브할 때:
- 추가된 요구사항은 메인 스펙에 추가됩니다
- 수정된 요구사항은 기존 버전을 대체합니다
- 삭제된 요구사항은 메인 스펙에서 삭제됩니다
변경 폴더는 감사 기록을 위해 openspec/changes/archive/로 이동합니다.
예시: 첫 번째 변경사항
어플리케이션에 다크 모드를 추가하는 과정을 살펴보겠습니다.
1. 변경사항 시작 (기본)
text
You: /opsx:propose add-dark-mode
AI: Created openspec/changes/add-dark-mode/
✓ proposal.md — 왜 이것을 하는지, 무엇이 변경되는지
✓ specs/ — 요구사항과 시나리오
✓ design.md — 기술적 접근 방식
✓ tasks.md — 구현 체크리스트
구현 준비 완료!확장 워크플로 프로필을 활성화한 경우, 두 단계로 나눌 수도 있습니다: /opsx:new 다음 /opsx:ff (또는 점진적으로 /opsx:continue).
2. 생성되는 것
proposal.md - 의도를 기록:
markdown
# 제안: 다크 모드 추가
## 의도
사용자들이 야간 사용 시 눈의 피로를 줄이기 위해
다크 모드 옵션을 요청했습니다.
## 범위
- 설정에 테마 토글 추가
- 시스템 환경 설정 감지 지원
- localStorage에 환경 설정 저장
## 접근 방식
상태 관리를 위해 React 컨텍스트와 함께
CSS 사용자 정의 속성을 사용하여 테마 구현.specs/ui/spec.md - 새로운 요구사항을 보여주는 델타:
markdown
# UI 델타
## 추가된 요구사항
### 요구사항: 테마 선택
시스템은 사용자가 라이트 및 다크 테마 중 선택할 수 있도록 허용해야 합니다.
#### 시나리오: 수동 토글
- 어떤 페이지에든 있는 사용자가 있을 때
- 사용자가 테마 토글을 클릭하면
- 테마가 즉시 전환됨
- 그리고 환경 설정이 세션 간에 유지됨
#### 시나리오: 시스템 환경 설정
- 저장된 환경 설정이 없는 사용자가 있을 때
- 어플리케이션이 로드되면
- 시스템의 선호하는 색 구성표가 사용됨tasks.md - 구현 체크리스트:
markdown
# 작업
## 1. 테마 인프라
- [ ] 1.1 라이트/다크 상태를 가진 ThemeContext 생성
- [ ] 1.2 색상을 위한 CSS 사용자 정의 속성 추가
- [ ] 1.3 localStorage 지속성 구현
## 2. UI 컴포넌트
- [ ] 2.1 ThemeToggle 컴포넌트 생성
- [ ] 2.2 설정 페이지에 토글 추가
- [ ] 2.3 빠른 토글을 포함하도록 Header 업데이트
## 3. 스타일링
- [ ] 3.1 다크 테마 색상 팔레트 정의
- [ ] 3.2 CSS 변수를 사용하도록 컴포넌트 업데이트3. 구현
You: /opsx:apply
AI: 작업 진행 중...
✓ 1.1 라이트/다크 상태를 가진 ThemeContext 생성
✓ 1.2 globals.css에 CSS 사용자 정의 속성 추가
✓ 1.3 localStorage 지속성 구현
✓ 2.1 ThemeToggle 컴포넌트 생성
...
모든 작업 완료!구현 중에 디자인 조정이 필요하다는 것을 발견하면, 아티팩트를 업데이트하고 계속 진행하면 됩니다.
4. 아카이브
You: /opsx:archive
AI: add-dark-mode 아카이브 중...
✓ 스펙을 openspec/specs/ui/spec.md에 병합
✓ openspec/changes/archive/2025-01-24-add-dark-mode/로 이동
완료! 다음 기능을 위한 준비 완료.델타 스펙이 이제 시스템의 작동 방식을 문서화하는 메인 스펙의 일부가 됩니다.
검증 및 검토
CLI를 사용하여 변경사항을 확인하세요:
bash
# 활성 변경사항 목록
openspec list
# 변경사항 세부 정보 보기
openspec show add-dark-mode
# 스펙 형식 검증
openspec validate add-dark-mode
# 인터랙티브 대시보드
openspec view