# 5. 핵심 워크플로우 ← [[openspec-04-project-structure|4. 프로젝트 구조]] | 다음 → [[openspec-06-slash-commands-reference|6. 슬래시 명령어 레퍼런스]] --- > [!info] 액션 기반 접근 > OpenSpec은 "단계 기반(phase-gate)"이 아닌 **"액션 기반(action-based)"** 워크플로우를 채택한다. 정해진 순서를 강제하지 않으며, 필요한 작업부터 유연하게 진행할 수 있다. ## 5.1 Core 프로필 워크플로우 (권장 시작점) ``` /opsx:propose → /opsx:apply → /opsx:sync → /opsx:archive ``` ### 1단계: Propose (제안) ``` /opsx:propose add-dark-mode ``` 또는 설명형: ``` /opsx:propose 사용자가 다크모드와 라이트모드를 전환할 수 있는 기능 ``` AI가 자동으로 생성하는 파일: - `proposal.md` — 의도, 범위, 접근 방식 - `specs/ui-theme.md` — Delta Specs (ADDED/MODIFIED/REMOVED) - `design.md` — 기술적 구현 방법 - `tasks.md` — 구현 체크리스트 > [!warning] 반드시 검토할 것 > - proposal.md의 범위가 의도와 일치하는가? > - specs의 요구사항이 누락되거나 과도하지 않은가? > - design.md의 기술 접근법이 프로젝트 컨벤션과 일치하는가? > - tasks.md의 순서가 합리적인가? ### 2단계: Apply (구현) ``` /opsx:apply add-dark-mode ``` AI가 `tasks.md`의 체크리스트를 순회하며 코드를 작성한다. 각 태스크 완료 시 `- [x]`로 표시된다. > [!tip] 구현 중 주의사항 > - AI가 tasks.md 범위를 벗어난 코드를 작성하려 하면 중단시킬 것 > - 각 태스크 완료 후 코드 리뷰 권장 > - apply 전 새 AI 대화 창을 열어 **컨텍스트 위생** 유지 (탐색 대화가 구현 단계에 혼선을 줄 수 있음) ### 3단계: Sync (동기화) ``` /opsx:sync add-dark-mode ``` 변경사항의 Delta Specs를 `openspec/specs/`의 해당 파일에 병합한다. > [!note] > `/opsx:archive`가 자동으로 sync 여부를 확인하므로, 직접 호출은 선택사항이다. ### 4단계: Archive (완료) ``` /opsx:archive add-dark-mode ``` 완료 처리 후: - 스펙 동기화 여부 자동 확인 - `openspec/changes/archive/2026-05-08-add-dark-mode/`로 이동 --- ## 5.2 슬래시 명령어 ↔ CLI 명령어 매핑 같은 작업을 슬래시 명령어(AI 채팅)와 CLI(터미널) 양쪽에서 수행할 수 있다. | 작업 | 슬래시 명령어 | CLI 명령어 | 권장 사용 환경 | |------|-------------|-----------|--------------| | 변경 제안 생성 | `/opsx:propose` | — | AI 채팅 | | 코드 구현 | `/opsx:apply` | — | AI 채팅 | | 스펙 병합 | `/opsx:sync` | — | AI 채팅 | | 완료 처리 | `/opsx:archive` | `openspec archive` | 둘 다 가능 | | 상태 확인 | — | `openspec status` | 터미널 | | 검증 | — | `openspec validate` | 터미널 / CI | | 목록 조회 | — | `openspec list` | 터미널 | | 상세 조회 | — | `openspec show` | 터미널 | > [!tip] > 슬래시 명령어는 AI가 컨텍스트를 갖고 아티팩트를 생성·구현할 때 사용하고, CLI는 상태 확인·검증·CI 자동화에 활용한다. --- ## 5.3 확장 워크플로우 패턴 > [!info] 활성화 방법 > `openspec config profile`로 확장 명령어를 활성화한 후 사용한다. ### 패턴 A: 빠른 기능 개발 (요구사항 명확 시) ``` /opsx:new add-payment → /opsx:ff → /opsx:apply → /opsx:verify → /opsx:archive ``` | 명령어 | 소요 시간 | 결과 | |--------|-----------|------| | `/opsx:new` | 즉시 | 빈 변경 폴더 생성 | | `/opsx:ff` | 1~2분 | 모든 계획 아티팩트 일괄 생성 | | `/opsx:apply` | 5~30분 | 코드 구현 | | `/opsx:verify` | 1~2분 | 완성도·정확성·일관성 검증 | | `/opsx:archive` | 30초 | 완료 처리 | ### 패턴 B: 탐색 기반 개발 (요구사항 불명확 시) ``` /opsx:explore → /opsx:new → /opsx:continue → ... → /opsx:apply ``` 실제 시나리오 예시: ``` # 1. 문제 탐색 (파일 생성 없이 분석만) /opsx:explore 페이지 로딩이 느린 이유가 뭔지 분석해줘 # 2. 변경 시작 (이미지 최적화부터) /opsx:new optimize-images # 3. 단계별 아티팩트 생성 (각 단계 검토 후 진행) /opsx:continue optimize-images ← proposal 생성 /opsx:continue optimize-images ← specs 생성 /opsx:continue optimize-images ← design 생성 /opsx:continue optimize-images ← tasks 생성 # 4. 구현 /opsx:apply optimize-images ``` ### 패턴 C: 병렬 개발 각 변경사항이 독립 폴더에 격리되므로 동시 진행이 가능하다. > [!warning] 컨텍스트 전환 주의 > 변경 A → 변경 B로 전환 시, 새 AI 대화를 열고 해당 변경의 아티팩트를 참조하도록 안내한다. 이전 대화의 컨텍스트가 혼입되지 않도록 주의한다. ```bash # 변경 A 진행 중 /opsx:propose add-dark-mode # 진행 중 (50%) # 긴급 버그 발생 → 새 AI 대화에서 작업 /opsx:propose fix-login-crash # 새 변경 시작 /opsx:apply fix-login-crash # 즉시 구현 /opsx:archive fix-login-crash # 완료 # 다시 변경 A로 복귀 → 새 AI 대화에서 작업 /opsx:apply add-dark-mode # 중단 지점부터 재개 # 여러 변경 동시 완료 (스펙 충돌 자동 감지) /opsx:bulk-archive add-dark-mode update-api-docs ``` ### 패턴 D: 완료 흐름 (검증 포함) ``` /opsx:apply → /opsx:verify → /opsx:archive ``` `/opsx:verify`가 검증하는 3가지 차원: | 차원 | 검증 내용 | |------|-----------| | **완성도 (Completeness)** | 모든 tasks.md 항목 완료 여부, 모든 스펙 요구사항 구현 여부 | | **정확성 (Correctness)** | 구현이 스펙 의도에 부합하는지, 엣지 케이스 처리 여부 | | **일관성 (Coherence)** | design.md 결정이 코드에 반영되었는지, 네이밍/패턴 일관성 | 예시 verify 출력: ``` Critical issues: 0 Warnings: - 세션 타임아웃 시나리오에 대한 테스트 없음 - design.md의 이벤트 드리븐 방식이 아닌 폴링 방식으로 구현됨 Ready to archive: Yes (경고와 함께) ``` --- ← [[openspec-04-project-structure|4. 프로젝트 구조]] | 다음 → [[openspec-06-slash-commands-reference|6. 슬래시 명령어 레퍼런스]]