워크플로우
이 가이드에서는 OpenSpec의 일반적인 워크플로우 패턴과 각 패턴을 사용해야 하는 경우를 다룹니다. 기본 설정은 시작하기를 참조하세요. 명령어 참조는 명령어를 참조하세요.
철학: 단계가 아닌 행동
기존 워크플로우는 계획, 구현, 완료와 같은 단계를 강제합니다. 하지만 실제 작업은 깔끔하게 상자 안에 들어가지 않습니다.
OPSX는 다른 접근 방식을 취합니다:
text
기존 방식 (단계 고정):
계획 ────────► 구현 ────────► 완료
│ │
│ "되돌아갈 수 없음" │
└────────────────────┘
OPSX (유연한 행동):
제안 ──► 사양 ──► 설계 ──► 작업 ──► 구현핵심 원칙:
- 단계가 아닌 행동 - 명령어는 수행할 수 있는 행위이며, 고정된 단계가 아닙니다
- 의존성은 촉진제 - 의존성은 다음에 필요한 것이 아니라 가능한 것을 보여줍니다
사용자 정의: OPSX 워크플로우는 산출물 시퀀스를 정의하는 스키마에 의해 구동됩니다. 사용자 정의 스키마 생성에 대한 자세한 내용은 사용자 정의를 참조하세요.
두 가지 모드
기본 빠른 경로 (core 프로필)
새로 설치하면 기본적으로 core가 활성화되며, 다음 기능을 제공합니다:
/opsx:propose/opsx:explore/opsx:apply/opsx:archive
일반적인 흐름:
text
/opsx:propose ──► /opsx:apply ──► /opsx:archive확장/전체 워크플로 (사용자 지정 선택)
명시적인 스캐폴딩 및 빌드 명령어(/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:sync, /opsx:bulk-archive, /opsx:onboard)를 원하면, 다음 명령어로 활성화하세요:
bash
openspec config profile
openspec update워크플로 패턴 (확장 모드)
빠른 기능 구현
구축할 내용이 명확하고 바로 실행만 하면 될 때:
text
/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive대화 예시:
text
You: /opsx:new add-logout-button
AI: Created openspec/changes/add-logout-button/
Ready to create: proposal
You: /opsx:ff
AI: Creating all planning artifacts...
✓ proposal.md
✓ specs/
✓ design.md
✓ tasks.md
Ready for implementation!
You: /opsx:apply
AI: Working through tasks...
✓ Added logout button to header
✓ Implemented session clearing
✓ Added confirmation dialog
All tasks complete!
You: /opsx:archive
AI: ✓ Merged specs
✓ Archived change적합한 경우: 소규모~중규모 기능, 버그 수정, 간단한 변경 사항.
탐색형
요구 사항이 불분명하거나 먼저 조사가 필요할 때:
text
/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply대화 예시:
text
You: /opsx:explore
AI: What would you like to explore?
You: I want to improve page load performance but I'm not sure
where the bottlenecks are.
AI: Let me help investigate...
[Analyzes bundle sizes, identifies slow queries, reviews
component render patterns]
I found three main bottlenecks:
1. Large unoptimized images
2. Synchronous data fetching in ProductList
3. Re-renders from context changes
Which would you like to address first?
You: Let's tackle the data fetching issue.
You: /opsx:new optimize-product-list-fetching
AI: Created change. Ready to create: proposal
You: /opsx:continue
AI: Creating proposal based on our exploration...
[Writes proposal incorporating investigation insights]
Ready to create: specs, design
Which would you like next?
You: /opsx:continue
AI: Creating specs...적합한 경우: 성능 최적화, 디버깅, 아키텍처 결정, 불명확한 요구 사항.
병렬 변경 사항
여러 변경 사항을 동시에 작업할 때:
text
Change A: /opsx:new ──► /opsx:ff ──► /opsx:apply (in progress)
│
context switch
│
Change B: /opsx:new ──► /opsx:ff ──────► /opsx:apply대화 예시:
text
You: I'm working on add-dark-mode but got pulled into a bug fix
You: /opsx:new fix-login-redirect
AI: Created openspec/changes/fix-login-redirect/
You: /opsx:ff
AI: ✓ Created planning artifacts
You: /opsx:apply
AI: Working on fix-login-redirect...
[Implements the fix]
All tasks complete!
You: /opsx:archive
AI: ✓ Archived fix-login-redirect
You: Let's get back to dark mode
You: /opsx:apply add-dark-mode
AI: Resuming add-dark-mode...
Picking up at task 2.3: Update Header...적합한 경우: 병렬 작업 흐름, 긴급한 중단 상황, 팀 협업.
완료된 변경 사항이 여러 개 있을 때, /opsx:bulk-archive를 사용하세요:
text
You: /opsx:bulk-archive
AI: Found 3 completed changes:
- add-dark-mode (all tasks done)
- fix-login-redirect (all tasks done)
- update-footer (all tasks done)
Checking for spec conflicts...
⚠ add-dark-mode and update-footer both touch specs/ui/
Inspecting codebase to resolve...
Both changes are implemented. Will apply in chronological order.
Archive all 3 changes?
You: Yes
AI: ✓ Archived add-dark-mode
✓ Archived fix-login-redirect
✓ Archived update-footer
Specs merged in order: add-dark-mode → update-footer대량 보관은 여러 변경 사항이 동일한 스펙에 영향을 줄 때 이를 감지하고, 실제로 구현된 내용을 확인하여 충돌을 해결합니다.
변경 사항 완료
권장되는 완료 흐름:
text
/opsx:apply ──► /opsx:verify ──► /opsx:archive
│ │
validates prompts to sync
implementation if needed검증: 작업 확인
/opsx:verify는 세 가지 차원에서 구현 결과를 아티팩트와 대조하여 검증합니다:
text
You: /opsx:verify
AI: Verifying add-auth...
COMPLETENESS
✓ All 12 tasks in tasks.md are checked
✓ All requirements in specs have corresponding code
⚠ Scenario "Session timeout after inactivity" not tested
CORRECTNESS
✓ Implementation matches spec intent
✓ Edge cases from scenarios are handled
✓ Error states match spec definitions
COHERENCE
✓ Design decisions reflected in code structure
✓ Naming conventions consistent with design.md
⚠ Design mentions "event-driven" but implementation uses polling
SUMMARY
─────────────────────────────
Critical issues: 0
Warnings: 2
Ready to archive: Yes (with warnings)
Recommendations:
1. Add test for session timeout scenario
2. Consider refactoring to event-driven as designed, or update design.md검증 항목:
| 차원 | 검증 내용 |
|---|---|
| 완전성 | 모든 작업 완료, 모든 요구 사항 구현, 시나리오 커버리지 |
| 정확성 | 구현이 스펙 의도와 일치, 엣지 케이스 처리 |
| 일관성 | 설계 결정이 코드에 반영, 패턴 일관성 |
검증은 보관을 차단하지 않지만, 먼저 해결할 수 있는 문제를 표시해 줍니다.
보관: 변경 사항 확정
/opsx:archive는 변경 사항을 완료하고 보관소로 이동합니다:
text
You: /opsx:archive
AI: Archiving add-auth...
Artifact status:
✓ proposal.md exists
✓ specs/ exists
✓ design.md exists
✓ tasks.md exists (12/12 tasks complete)
Delta specs: Not yet synced to main
→ Would you like to sync now?
You: Yes
AI: ✓ Synced specs to openspec/specs/auth/spec.md
✓ Moved to openspec/changes/archive/2025-01-24-add-auth/
Change archived successfully.보관 시 스펙이 동기화되지 않았으면 프롬프트가 표시됩니다. 미완료 작업으로 차단되지는 않지만 경고를 표시합니다.
언제 어떤 명령어를 사용할까
/opsx:ff vs /opsx:continue
| 상황 | 사용할 명령어 |
|---|---|
| 요구 사항 명확, 구축 준비 완료 | /opsx:ff |
| 탐색 중, 각 단계를 검토하고 싶을 때 | /opsx:continue |
| 스펙 전에 제안을 반복 검토하고 싶을 때 | /opsx:continue |
| 시간 압박, 빠르게 진행해야 할 때 | /opsx:ff |
| 복잡한 변경, 제어가 필요할 때 | /opsx:continue |
일반 원칙: 전체 범위를 처음부터 설명할 수 있다면 /opsx:ff를 사용하세요. 진행하면서 파악해 나간다면 /opsx:continue를 사용하세요.
기존 변경 사항 업데이트 vs 새로 시작
흔한 질문: 기존 변경 사항을 업데이트하는 것이 적절한 경우와 새로 시작해야 하는 경우는 언제인가요?
기존 변경 사항을 업데이트하는 경우:
- 동일한 의도, 실행 방식 개선
- 범위 축소 (MVP 먼저, 나중에 나머지)
- 학습 기반 수정 (코드베이스가 예상과 다를 때)
- 구현 과정에서 발견한 사항에 기반한 설계 조정
새로운 변경 사항을 시작하는 경우:
- 의도가 근본적으로 변경됨
- 범위가 완전히 다른 작업으로 확장됨
- 원래 변경 사항을 독립적으로 "완료"로 표시할 수 있을 때
- 패치가 혼란을 야기하는 경우
text
┌─────────────────────────────────────┐
│ Is this the same work? │
└──────────────┬──────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
Same intent? >50% overlap? Can original
Same problem? Same scope? be "done" without
│ │ these changes?
│ │ │
┌────────┴────────┐ ┌──────┴──────┐ ┌───────┴───────┐
│ │ │ │ │ │
YES NO YES NO NO YES
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
UPDATE NEW UPDATE NEW UPDATE NEW예시: "다크 모드 추가"
- "커스텀 테마도 지원해야 함" → 새 변경 사항 (범위 확장)
- "시스템 선호도 감지가 예상보다 어려움" → 업데이트 (동일한 의도)
- "토글 먼저 출시하고, 설정은 나중에 추가" → 업데이트 후 보관, 그 다음 새 변경 사항
모범 사례
변경 사항을 집중적으로 유지
변경 사항당 하나의 논리적 작업 단위. "기능 X 추가 및 동시에 Y 리팩토링"을 수행한다면 두 개의 별도 변경 사항을 고려하세요.
중요한 이유:
- 검토와 이해가 더 쉬움
- 깔끔한 보관 이력
- 독립적으로 출시 가능
- 필요 시 롤백이 더 간단
불명확한 요구 사항에는 /opsx:explore 사용
변경 사항을 확정하기 전에 문제 영역을 탐색하세요:
text
You: /opsx:explore
AI: What would you like to explore?
You: How should we handle rate limiting for our API?
AI: Let me investigate your current setup and options...
[Researches codebase, considers patterns]
I see three approaches we could take:
1. Middleware-based (simple, per-endpoint)
2. Redis-backed (scalable, shared state)
3. Token bucket per user (fair, complex)
Your current stack suggests #1 or #2. What's your scale?탐색은 아티팩트를 생성하기 전에 생각을 명확히 해 줍니다.
보관 전에 검증
/opsx:verify를 사용하여 구현 결과가 아티팩트와 일치하는지 확인하세요:
text
You: /opsx:verify
AI: Verifying add-dark-mode...
✓ All tasks in tasks.md are checked
✓ Requirements in specs have corresponding code
✓ Design decisions are reflected in implementation
Ready to archive!변경 사항을 마감하기 전에 불일치를 잡아냅니다.
변경 사항을 명확하게 명명
좋은 이름은 openspec list를 유용하게 만듭니다:
text
Good: Avoid:
add-dark-mode feature-1
fix-login-redirect update
optimize-product-query changes
implement-2fa wip명령어 빠른 참조
전체 명령어 세부 사항과 옵션은 명령어를 참조하세요.
| 명령어 | 용도 | 사용 시점 |
|---|---|---|
/opsx:propose | 변경 사항 + 계획 아티팩트 생성 | 빠른 기본 경로 (core 프로필) |
/opsx:explore | 아이디어 검토 | 불명확한 요구 사항, 조사 |
/opsx:new | 변경 사항 스캐폴드 시작 | 확장 모드, 명시적 아티팩트 제어 |
/opsx:continue | 다음 아티팩트 생성 | 확장 모드, 단계별 아티팩트 생성 |
/opsx:ff | 모든 계획 아티팩트 생성 | 확장 모드, 명확한 범위 |
/opsx:apply | 작업 구현 | 코드 작성 준비 완료 |
/opsx:verify | 구현 검증 | 확장 모드, 보관 전 |
/opsx:sync | 델타 스펙 병합 | 확장 모드, 선택 사항 |
/opsx:archive | 변경 사항 완료 | 모든 작업 완료 |
/opsx:bulk-archive | 여러 변경 사항 보관 | 확장 모드, 병렬 작업 |