시작하기
이 가이드는 OpenSpec을 설치하고 초기화한 후 작동 방식을 설명합니다. 설치 방법은 메인 README를 참조하세요.
작동 방식
OpenSpec은 코드를 작성하기 전에 AI 코딩 어시스턴트와 구축할 내용에 대해 합의하는 데 도움을 줍니다.
기본 빠른 경로(코어 프로필):
text
/opsx:propose ──► /opsx:apply ──► /opsx:archive확장 경로(사용자 지정 워크플로우 선택):
text
/opsx:new ──► /opsx:ff 또는 /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive기본 전역 프로필은 core이며, propose, explore, apply, archive를 포함합니다. openspec config profile 명령으로 확장 워크플로우 명령을 활성화한 후 openspec update를 실행할 수 있습니다.
OpenSpec이 생성하는 것
openspec init을 실행한 후 프로젝트는 다음과 같은 구조를 갖게 됩니다:
openspec/
├── specs/ # 진실의 원천(시스템의 동작)
│ └── <도메인>/
│ └── spec.md
├── changes/ # 제안된 변경 사항(변경당 하나의 폴더)
│ └── <변경-이름>/
│ ├── proposal.md
│ ├── design.md
│ ├── tasks.md
│ └── specs/ # 델타 스펙(변경되는 내용)
│ └── <도메인>/
│ └── 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의 델타
## 추가된 요구 사항
### 요구 사항: 2단계 인증
시스템은 로그인 시 두 번째 인증 단계를 요구해야 합니다.
#### 시나리오: OTP 필요
- GIVEN 2FA가 활성화된 사용자
- WHEN 사용자가 유효한 자격 증명을 제출하면
- THEN OTP 인증 요청이 표시됨
## 수정된 요구 사항
### 요구 사항: 세션 타임아웃
시스템은 비활성 상태 30분 후 세션을 만료해야 합니다.
(이전: 60분)
#### 시나리오: 유휴 타임아웃
- GIVEN 인증된 세션
- WHEN 활동 없이 30분이 경과하면
- THEN 세션이 무효화됨
## 삭제된 요구 사항
### 요구 사항: 로그인 상태 유지
(2FA를 위해 폐기됨)보관 시 발생하는 일
변경을 보관하면:
- 추가된 요구 사항이 메인 스펙에 추가됩니다
- 수정된 요구 사항이 기존 버전을 대체합니다
- 삭제된 요구 사항이 메인 스펙에서 제거됩니다
변경 폴더는 감사 기록을 위해 openspec/changes/archive/로 이동됩니다.
예시: 첫 번째 변경
어\application에 다크 모드를 추가하는 과정을 살펴보겠습니다.
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의 델타
## 추가된 요구 사항
### 요구 사항: 테마 선택
시스템은 사용자가 라이트 및 다크 테마 중 선택할 수 있도록 허용해야 합니다.
#### 시나리오: 수동 토글
- GIVEN 어떤 페이지에 있는 사용자
- WHEN 사용자가 테마 토글을 클릭하면
- THEN 테마가 즉시 전환됨
- AND 선호도가 세션 간에 유지됨
#### 시나리오: 시스템 선호도
- GIVEN 저장된 선호도가 없는 사용자
- WHEN 애플리케이션이 로드되면
- THEN 시스템의 선호 색상 체계가 사용됨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