# 12. 마이그레이션 가이드
← [[openspec-11-best-practices|11. 베스트 프랙티스]] | 다음 → [[openspec-13-troubleshooting|13. 트러블슈팅]]
---
## 12.1 구버전(레거시) → 최신 OPSX
> [!info]
> 구버전 OpenSpec(명령어가 `/openspec:proposal` 형태)에서 마이그레이션하는 경우.
### 변경사항 요약
| 항목 | 구버전 | 최신 |
|------|--------|------|
| 제안 명령어 | `/openspec:proposal` | `/opsx:propose` |
| 적용 명령어 | `/openspec:apply` | `/opsx:apply` |
| 설정 파일 | `CLAUDE.md` 마커 + `project.md` | `openspec/config.yaml` |
| 도구 파일 위치 | `.claude/commands/openspec/` | `.claude/skills/openspec-*/` |
| 워크플로우 | 고정 선형 단계 | 유동적 액션 기반 |
### 마이그레이션 절차
> [!success] 방법 1: 전체 재설정 (권장)
> ```bash
> openspec init --force --tools claude
> ```
> [!note] 방법 2: 점진적 업데이트
> ```bash
> openspec update
> ```
### project.md → config.yaml 변환
`project.md`는 자동으로 삭제되지 않는다. 직접 내용을 검토하여 `config.yaml`로 이전 후 삭제한다.
**기존 project.md (자유형 마크다운):**
```markdown
# Project Context
This is a TypeScript monorepo using React and Node.js.
We use Jest for testing and follow strict ESLint rules.
Our API is RESTful and documented in docs/api.md.
## Conventions
- All public APIs must maintain backwards compatibility
- New features should include tests
- Use Given/When/Then format for specifications
```
**변환된 config.yaml (구조화된 YAML):**
```yaml
schema: spec-driven
context: |
Tech stack: TypeScript, React 18, Node.js 20
Testing: Jest with React Testing Library
API: RESTful, documented in docs/api.md
We maintain backwards compatibility for all public APIs
rules:
proposal:
- Include rollback plan for breaking changes
specs:
- Use Given/When/Then format for scenarios
- Reference existing patterns before inventing new ones
design:
- Include sequence diagrams for complex flows
```
**포함할 내용 vs 제외할 내용:**
| 항목 | 위치 |
|------|------|
| 기술 스택, 핵심 아키텍처 패턴, 비자명적 제약사항 | `context:` |
| 아티팩트별 형식 규칙, 리뷰 기준 | `rules:` (해당 아티팩트 키 아래) |
| AI가 이미 아는 일반 모범 사례, 장황한 설명 | **제외** |
> [!tip] AI로 변환 돕기
> `project.md` 내용을 붙여넣고 "OpenSpec의 `config.yaml` 형식으로 변환해줘. `context:`는 간결하게, 아티팩트별 지침은 `rules:`로 분리해줘"라고 요청하면 된다.
### 파일 보존/제거 목록
> [!success] 보존되는 파일 (변경 없음)
> - `openspec/changes/` — 진행 중인 모든 변경사항
> - `openspec/changes/archive/` — 완료된 변경사항 이력
> - `openspec/specs/` — 메인 스펙 (단일 진실 공급원)
> - `CLAUDE.md`, `AGENTS.md` — OpenSpec 마커만 제거, 사용자 작성 내용 보존
> [!warning] 제거되는 파일 (OpenSpec이 생성한 파일만)
> - `.claude/commands/openspec/` → `.claude/skills/`로 교체
> - `openspec/AGENTS.md` (레거시 워크플로우 트리거)
> - `CLAUDE.md`, `AGENTS.md` 내 OpenSpec 마커 블록
> [!danger] 수동 처리 필요
> - `openspec/project.md` — 자동 삭제되지 않음. 내용을 `config.yaml`로 이전 후 직접 삭제
**마이그레이션 후 파일 구조:**
```
project/
├── openspec/
│ ├── specs/ # 미변경
│ ├── changes/ # 미변경
│ └── config.yaml # 신규: 프로젝트 설정
├── .claude/
│ └── skills/ # 신규: OPSX 스킬
│ ├── openspec-propose/
│ ├── openspec-explore/
│ ├── openspec-apply-change/
│ └── openspec-sync-specs/
├── CLAUDE.md # OpenSpec 마커 제거, 사용자 내용 보존
└── AGENTS.md # OpenSpec 마커 제거, 사용자 내용 보존
```
### 기존 변경사항 재개
```bash
/opsx:apply add-my-feature ← 기존 변경 계속
/opsx:continue add-my-feature ← 다음 아티팩트 생성
openspec status --change add-my-feature ← 상태 확인
```
---
← [[openspec-11-best-practices|11. 베스트 프랙티스]] | 다음 → [[openspec-13-troubleshooting|13. 트러블슈팅]]