OPSX 워크플로
Discord에서 피드백을 환영합니다.
OPSX란 무엇인가요?
OPSX는 이제 OpenSpec의 표준 워크플로입니다.
OpenSpec 변경을 위한 유연하고 반복적인 워크플로입니다. 더 이상 엄격한 단계는 없습니다. 언제든 수행할 수 있는 작업만 존재합니다.
왜 이것을 만들었는가
기존 OpenSpec 워크플로우는 작동하지만, 제한적입니다:
- 지침이 하드코딩됨 — TypeScript에 묻혀 있어 변경할 수 없음
- 전부 아니면 전무 — 하나의 큰 명령이 모든 것을 생성하여 개별 부분을 테스트할 수 없음
- 고정된 구조 — 모두에게 동일한 워크플로우, 맞춤 설정 불가
- 블랙박스 — AI 출력이 좋지 않을 때 프롬프트를 미세 조정할 수 없음
OPSX는 이를 개방합니다. 이제 누구나:
- 지침을 실험할 수 있음 — 템플릿을 편집하여 AI가 더 잘 작동하는지 확인
- 세분화된 테스트 가능 — 각 산출물의 지침을 독립적으로 검증
- 워크플로우를 맞춤 설정 — 자체 산출물 및 종속성 정의
- 빠르게 반복 — 템플릿을 변경하고 즉시 테스트, 재빌드 불필요
기존 워크플로우: OPSX:
┌────────────────────────┐ ┌────────────────────────┐
│ 패키지에 하드코딩됨 │ │ schema.yaml │◄── 여기를 편집
│ (변경 불가) │ │ templates/*.md │◄── 또는 여기
│ ↓ │ │ ↓ │
│ 새 릴리스 대기 │ │ 즉시 적용 │
│ ↓ │ │ ↓ │
│ 개선되길 바람 │ │ 직접 테스트 │
└────────────────────────┘ └────────────────────────┘이것은 모두를 위한 것입니다:
- 팀 — 실제로 작동하는 방식에 맞는 워크플로우 생성
- 파워 유저 — 코드베이스에 더 나은 AI 출력을 위해 프롬프트 미세 조정
- OpenSpec 기여자 — 릴리스 없이 새로운 접근 방식 실험
우리는 모두 아직 무엇이 가장 효과적인지 배우고 있습니다. OPSX는 함께 배울 수 있게 해줍니다.
사용자 경험
선형 워크플로우의 문제점: "계획 단계"에 있다가 "구현 단계"로, 그리고 "완료"로 진행합니다. 하지만 실제 작업은 그렇게 작동하지 않습니다. 무언가를 구현하다가 설계가 잘못되었음을 깨닫고, 사양을 업데이트해야 하며, 구현을 계속합니다. 선형 단계는 실제 작업 방식과 충돌합니다.
OPSX 접근 방식:
- 단계가 아닌 액션 — 생성, 구현, 업데이트, 보관 — 언제든 아무거나 수행
- 종속성은 촉진제 — 다음에 필요한 것이 아니라 가능한 것을 보여줌
제안 ──→ 사양 ──→ 설계 ──→ 작업 ──→ 구현설정
bash
# openspec가 설치되어 있는지 확인하세요 — 스킬은 자동으로 생성됩니다
openspec init이 명령은 .claude/skills/(또는 동등한 위치)에 AI 코딩 어시스턴트가 자동 감지하는 스킬을 생성합니다.
기본적으로 OpenSpec은 core 워크플로우 프로필(propose, explore, apply, archive)을 사용합니다. 확장된 워크플로우 명령(new, continue, ff, verify, sync, bulk-archive, onboard)을 원하면 openspec config profile로 구성하고 openspec update로 적용합니다.
설정 중에 프로젝트 구성(openspec/config.yaml)을 만들라는 메시지가 표시됩니다. 이는 선택 사항이지만 권장됩니다.
프로젝트 구성
프로젝트 구성은 기본값을 설정하고 모든 산출물에 프로젝트별 컨텍스트를 주입할 수 있게 합니다.
구성 생성
구성은 openspec init 중에 생성되거나 수동으로 생성할 수 있습니다:
yaml
# openspec/config.yaml
schema: spec-driven
context: |
기술 스택: TypeScript, React, Node.js
API 규칙: RESTful, JSON 응답
테스트: Vitest로 단위 테스트, Playwright로 e2e 테스트
스타일: ESLint와 Prettier, 엄격한 TypeScript
rules:
proposal:
- 롤백 계획 포함
- 영향받는 팀 식별
specs:
- 시나리오에 Given/When/Then 형식 사용
design:
- 복잡한 흐름에 대한 시퀀스 다이어그램 포함구성 필드
| 필드 | 타입 | 설명 |
|---|---|---|
schema | 문자열 | 새 변경에 대한 기본 스키마 (예: spec-driven) |
context | 문자열 | 모든 산출물 지침에 주입되는 프로젝트 컨텍스트 |
rules | 객체 | 산출물 ID별 규칙 |
작동 방식
스키마 우선순위 (높은 것에서 낮은 것 순):
- CLI 플래그 (
--schema <name>) - 변경 메타데이터 (변경 디렉토리의
.openspec.yaml) - 프로젝트 구성 (
openspec/config.yaml) - 기본값 (
spec-driven)
컨텍스트 주입:
- 컨텍스트는 모든 산출물 지침 앞에 추가됨
<context>...</context>태그로 감싸짐- AI가 프로젝트 규칙을 이해하는 데 도움
규칙 주입:
- 규칙은 일치하는 산출물에만 주입됨
<rules>...</rules>태그로 감싸짐- 컨텍스트 뒤, 템플릿 앞에 나타남
스키마별 산출물 ID
spec-driven (기본값):
proposal— 변경 제안specs— 사양design— 기술 설계tasks— 구현 작업
구성 검증
rules의 알 수 없는 산출물 ID는 경고 생성- 스키마 이름은 사용 가능한 스키마와 대조하여 검증
- 컨텍스트는 50KB 크기 제한
- 잘못된 YAML은 줄 번호와 함께 보고됨
문제 해결
"rules에서 알 수 없는 산출물 ID: X"
- 산출물 ID가 스키마와 일치하는지 확인 (위 목록 참조)
openspec schemas --json을 실행하여 각 스키마의 산출물 ID 확인
구성이 적용되지 않음:
- 파일이
openspec/config.yaml에 있는지 확인 (.yml이 아님) - YAML 구문을 검증기로 확인
- 구성 변경은 즉시 적용 (재시작 불필요)
컨텍스트가 너무 큼:
- 컨텍스트는 50KB로 제한됨
- 요약하거나 외부 문서에 링크
명령어
| 명령어 | 기능 |
|---|---|
/opsx:propose | 변경을 생성하고 계획 산출물을 한 단계로 생성 (기본 빠른 경로) |
/opsx:explore | 아이디어를 생각하고, 문제를 조사하고, 요구사항을 명확히 함 |
/opsx:new | 새 변경 스캐폴드 시작 (확장된 워크플로우) |
/opsx:continue | 다음 산출물 생성 (확장된 워크플로우) |
/opsx:ff | 계획 산출물을 빠르게 전개 (확장된 워크플로우) |
/opsx:apply | 작업을 구현하고 필요에 따라 산출물 업데이트 |
/opsx:verify | 산출물에 따라 구현 검증 (확장된 워크플로우) |
/opsx:sync | 델타 사양을 메인으로 동기화 (확장된 워크플로우, 선택 사항) |
/opsx:archive | 완료 시 보관 |
/opsx:bulk-archive | 여러 완료된 변경 보관 (확장된 워크플로우) |
/opsx:onboard | 종단간 변경의 안내된 워크스루 (확장된 워크플로우) |
사용법
아이디어 탐색
/opsx:explore아이디어를 생각하고, 문제를 조사하고, 옵션을 비교합니다. 구조 불필요 - 단순히 사고 파트너 역할. 통찰이 결정화되면 /opsx:propose(기본) 또는 /opsx:new//opsx:ff(확장)로 전환합니다.
새 변경 시작
/opsx:propose변경을 생성하고 구현 전에 필요한 계획 산출물을 생성합니다.
확장된 워크플로우를 활성화한 경우 대신 다음을 사용할 수 있습니다:
text
/opsx:new # 스캐폴드만
/opsx:continue # 한 번에 하나의 산출물 생성
/opsx:ff # 모든 계획 산출물을 한 번에 생성산출물 생성
/opsx:continue종속성에 따라 생성할 준비가 된 것을 표시한 다음 하나의 산출물을 생성합니다. 변경을 점진적으로 구축하려면 반복적으로 사용합니다.
/opsx:ff add-dark-mode모든 계획 산출물을 한 번에 생성합니다. 구축할 것이 명확할 때 사용합니다.
구현 (유동적인 부분)
/opsx:apply작업을 진행하면서 체크합니다. 여러 변경을 동시에 처리하는 경우 /opsx:apply <name>을 실행할 수 있습니다. 그렇지 않으면 대화에서 추론하며, 판단할 수 없는 경우 선택하라는 메시지를 표시합니다.
마무리
/opsx:archive # 완료 시 보관으로 이동 (필요 시 사양 동기화 메시지 표시)업데이트 대신 새로 시작할 때
구현 전에 항상 제안이나 사양을 편집할 수 있습니다. 하지만 언제 개선이 "다른 작업"이 되는가?
제안이 포착하는 것
제안은 세 가지를 정의합니다:
- 의도 — 어떤 문제를 해결하고 있는가?
- 범위 — 범위 내/외는 무엇인가?
- 접근 방식 — 어떻게 해결할 것인가?
질문은: 무엇이 얼마나 변경되었는가?
기존 변경을 업데이트할 때:
동일한 의도, 개선된 실행
- 고려하지 않은 가장자리 사례를 발견
- 접근 방식을 미세 조정해야 하지만 목표는 변경되지 않음
- 구현 과정에서 설계가 약간 잘못됨을 발견
범위 축소
- 전체 범위가 너무 크다는 것을 깨닫고, 먼저 MVP를 출시하고 싶음
- "다크 모드 추가" → "다크 모드 토글 추가 (시스템 기본값은 v2에서)"
학습 기반 수정
- 코드베이스가 생각한 것과 다르게 구조화됨
- 종속성이 예상대로 작동하지 않음
- "CSS 변수 사용" → "대신 Tailwind의 dark: 접두사 사용"
새 변경을 시작할 때:
의도가 근본적으로 변경됨
- 문제 자체가 이제 다름
- "다크 모드 추가" → "사용자 정의 색상, 글꼴, 간격을 포함한 포괄적인 테마 시스템 추가"
범위 폭발
- 변경이 너무 커져 본질적으로 다른 작업이 됨
- 업데이트 후 원래 제안은 인식 불가능
- "로그인 버그 수정" → "인증 시스템 재작성"
원래 변경 완료 가능
- 원래 변경은 "완료"로 표시할 수 있음
- 새 작업은 독립적이며, 개선이 아님
- "다크 모드 MVP 추가" 완료 → 보관 → 새 변경 "다크 모드 개선"
휴리스틱
┌─────────────────────────────────────┐
│ 이것이 동일한 작업인가? │
└──────────────┬──────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
동일한 의도? >50% 겹침? 원래 변경을
동일한 문제? 동일한 범위? 이러한 변경 없이
│ │ "완료"할 수 있는가?
│ │ │
┌────────┴────────┐ ┌──────┴──────┐ ┌───────┴───────┐
│ │ │ │ │ │
예 아니오 예 아니오 아니오 예
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
업데이트 새 변경 업데이트 새 변경 업데이트 새 변경| 테스트 | 업데이트 | 새 변경 |
|---|---|---|
| 정체성 | "동일한 것, 개선됨" | "다른 작업" |
| 범위 겹침 | >50% 겹침 | <50% 겹침 |
| 완료 | 변경 없이는 "완료" 불가 | 원래 변경 완료 가능, 새 작업 독립적 |
| 이야기 | 업데이트 체인이 일관된 이야기 전달 | 패치는 혼란을 더함 |
원칙
업데이트는 컨텍스트를 보존합니다. 새 변경은 명확성을 제공합니다.
사고의 이력이 가치 있을 때 업데이트를 선택합니다. 패치보다 새로 시작하는 것이 더 명확할 때 새 변경을 선택합니다.
git 분기와 비유할 수 있습니다:
- 동일한 기능을 작업하는 동안 계속 커밋
- 진정으로 새로운 작업일 때 새 분기 시작
- 때로는 부분적인 기능을 병합하고 2단계를 위해 새로 시작
어떤 점이 다른가요?
레거시 (/openspec:proposal) | OPSX (/opsx:*) | |
|---|---|---|
| 구조 | 하나의 큰 제안 문서 | 의존성이 있는 개별 아티팩트 |
| 워크플로우 | 선형 단계: 계획 → 구현 → 보관 | 유연한 작업 — 언제든 아무거나 수행 |
| 반복 작업 | 되돌아가기 어려움 | 학습한 내용에 따라 아티팩트 업데이트 |
| 커스터마이징 | 고정된 구조 | 스키마 기반 (자신만의 아티팩트 정의) |
핵심 통찰: 작업은 선형적이지 않습니다. OPSX는 그렇게 가장하는 것을 멈춥니다.
아키텍처 심층 분석
이 섹션에서는 OPSX가 내부적으로 어떻게 작동하는지, 그리고 기존 워크플로우와 어떻게 비교되는지 설명합니다. 이 섹션의 예시는 확장된 명령 세트(new, continue 등)를 사용합니다. 기본 core 사용자는 동일한 흐름을 propose → apply → archive로 매핑할 수 있습니다.
철학: 단계 vs 액션
┌─────────────────────────────────────────────────────────────────────────────┐
│ 기존 워크플로우 │
│ (단계 고정, 전부 아니면 전무) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 계획 단계 │ ───► │ 구현 단계 │ ───► │ 보관 단계 │ │
│ │ │ │ │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ /openspec:proposal /openspec:apply /openspec:archive │
│ │
│ • 모든 산출물을 한 번에 생성 │
│ • 구현 중 스펙을 업데이트할 수 없음 │
│ • 단계 게이트가 선형 진행을 강제 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ OPSX 워크플로우 │
│ (유연한 액션, 반복적) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ 액션 (단계가 아님) │ │
│ │ │ │
│ │ new ◄──► continue ◄──► apply ◄──► archive │ │
│ │ │ │ │ │ │ │
│ │ └──────────┴───────────┴───────────┘ │ │
│ │ 임의 순서 │ │
│ └────────────────────────────────────────────┘ │
│ │
│ • 산출물을 하나씩 생성하거나 빨리 감기 │
│ • 구현 중 스펙/설계/작업 업데이트 │
│ • 의존성이 진행을 가능하게 하며, 단계는 존재하지 않음 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘구성 요소 아키텍처
기존 워크플로우는 TypeScript에서 하드코딩된 템플릿을 사용합니다:
┌─────────────────────────────────────────────────────────────────────────────┐
│ 기존 워크플로우 구성 요소 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 하드코딩된 템플릿 (TypeScript 문자열) │
│ │ │
│ ▼ │
│ 도구별 구성요소/어댑터 │
│ │ │
│ ▼ │
│ 생성된 명령 파일 (.claude/commands/openspec/*.md) │
│ │
│ • 고정된 구조, 산출물 인식 없음 │
│ • 변경 시 코드 수정 + 재구축 필요 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘OPSX는 외부 스키마와 의존성 그래프 엔진을 사용합니다:
┌─────────────────────────────────────────────────────────────────────────────┐
│ OPSX 구성 요소 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 스키마 정의 (YAML) │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ name: spec-driven │ │
│ │ artifacts: │ │
│ │ - id: proposal │ │
│ │ generates: proposal.md │ │
│ │ requires: [] ◄── 의존성 │ │
│ │ - id: specs │ │
│ │ generates: specs/**/*.md ◄── 글롭 패턴 │ │
│ │ requires: [proposal] ◄── proposal 후 활성화 │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 산출물 그래프 엔진 │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ • 위상 정렬 (의존성 순서) │ │
│ │ • 상태 감지 (파일시스템 존재 여부) │ │
│ │ • 풍부한 지시문 생성 (템플릿 + 컨텍스트) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 스킬 파일 (.claude/skills/openspec-*/SKILL.md) │
│ │
│ • 크로스 에디터 호환 (Claude Code, Cursor, Windsurf) │
│ • 스킬이 구조화된 데이터를 위해 CLI를 쿼리 │
│ • 스키마 파일을 통해 완전히 사용자 정의 가능 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘의존성 그래프 모델
산출물은 방향 비순환 그래프(DAG)를 형성합니다. 의존성은 게이트가 아닌 활성화 요소입니다:
proposal
(루트 노드)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(requires: (requires:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(requires:
specs, design)
│
▼
┌──────────────┐
│ APPLY 단계 │
│ (requires: │
│ tasks) │
└──────────────┘상태 전이:
차단됨 ────────────────► 준비됨 ────────────────► 완료됨
│ │ │
의존성 누락 모든 의존성 파일시스템에
완료됨 파일 존재정보 흐름
기존 워크플로우 — 에이전트가 정적 지시문을 수신:
사용자: "/openspec:proposal"
│
▼
┌─────────────────────────────────────────┐
│ 정적 지시문: │
│ • proposal.md 생성 │
│ • tasks.md 생성 │
│ • design.md 생성 │
│ • specs/<capability>/spec.md 생성 │
│ │
│ 어떤 것이 존재하는지 또는 산출물 간 │
│ 의존성에 대한 인식 없음 │
└─────────────────────────────────────────┘
│
▼
에이전트가 모든 산출물을 한 번에 생성OPSX — 에이전트가 풍부한 컨텍스트를 쿼리:
사용자: "/opsx:continue"
│
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ 1단계: 현재 상태 쿼리 │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ $ openspec status --change "add-auth" --json │ │
│ │ │ │
│ │ { │ │
│ │ "artifacts": [ │ │
│ │ {"id": "proposal", "status": "done"}, │ │
│ │ {"id": "specs", "status": "ready"}, ◄── 첫 번째 준비됨 │ │
│ │ {"id": "design", "status": "ready"}, │ │
│ │ {"id": "tasks", "status": "blocked", "missingDeps": ["specs"]}│ │
│ │ ] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ 2단계: 준비된 산출물에 대한 풍부한 지시문 가져오기 │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ $ openspec instructions specs --change "add-auth" --json │ │
│ │ │ │
│ │ { │ │
│ │ "template": "# Specification\n\n## ADDED Requirements...", │ │
│ │ "dependencies": [{"id": "proposal", "path": "...", "done": true}│ │
│ │ "unlocks": ["tasks"] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ 3단계: 의존성 읽기 → 하나의 산출물 생성 → 활성화된 내용 표시 │
└──────────────────────────────────────────────────────────────────────────┘반복 모델
기존 워크플로우 — 반복이 어색함:
┌─────────┐ ┌─────────┐ ┌─────────┐
│/proposal│ ──► │ /apply │ ──► │/archive │
└─────────┘ └─────────┘ └─────────┘
│ │
│ ├── "잠깐, 설계가 잘못됐어"
│ │
│ ├── 옵션:
│ │ • 파일을 수동으로 편집 (컨텍스트 깨짐)
│ │ • 포기하고 다시 시작
│ │ • 일단 진행하고 나중에 수정
│ │
│ └── 공식적인 "돌아가기" 메커니즘 없음
│
└── 모든 산출물을 한 번에 생성OPSX — 자연스러운 반복:
/opsx:new ───► /opsx:continue ───► /opsx:apply ───► /opsx:archive
│ │ │
│ │ ├── "설계가 잘못됐어"
│ │ │
│ │ ▼
│ │ design.md를 편집하고
│ │ 계속 진행!
│ │ │
│ │ ▼
│ │ /opsx:apply가 중단된
│ │ 지점부터 이어감
│ │
│ └── 하나의 산출물을 생성하고, 활성화된 내용 표시
│
└── 변경을 스캐폴딩하고 지시를 기다림사용자 정의 스키마
스키마 관리 명령을 사용하여 사용자 정의 워크플로우를 만드세요:
bash
# 처음부터 새 스키마 만들기 (대화형)
openspec schema init my-workflow
# 또는 기존 스키마를 시작점으로 복제
openspec schema fork spec-driven my-workflow
# 스키마 구조 검증
openspec schema validate my-workflow
# 스키마가 어디서 해결되는지 확인 (디버깅에 유용)
openspec schema which my-workflow스키마는 openspec/schemas/ (프로젝트 로컬, 버전 관리) 또는 ~/.local/share/openspec/schemas/ (사용자 전역)에 저장됩니다.
스키마 구조:
openspec/schemas/research-first/
├── schema.yaml
└── templates/
├── research.md
├── proposal.md
└── tasks.md예시 schema.yaml:
yaml
name: research-first
artifacts:
- id: research # proposal 앞에 추가됨
generates: research.md
requires: []
- id: proposal
generates: proposal.md
requires: [research] # 이제 research에 의존
- id: tasks
generates: tasks.md
requires: [proposal]의존성 그래프:
research ──► proposal ──► tasks요약
| 측면 | 기존 | OPSX |
|---|---|---|
| 템플릿 | 하드코딩된 TypeScript | 외부 YAML + Markdown |
| 의존성 | 없음 (전부 한 번에) | 위상 정렬이 있는 DAG |
| 상태 | 단계 기반 정신 모델 | 파일시스템 존재 여부 |
| 사용자 정의 | 소스 편집, 재구축 | schema.yaml 생성 |
| 반복 | 단계 고정 | 유연, 아무 것이나 편집 |
| 에디터 지원 | 도구별 구성요소/어댑터 | 단일 스킬 디렉토리 |
스키마
스키마는 존재하는 산출물과 그 의존성을 정의합니다. 현재 사용 가능한 스키마는 다음과 같습니다:
- spec-driven (기본값): 제안 → 스펙 → 설계 → 작업
bash
# 사용 가능한 스키마 목록 보기
openspec schemas
# 모든 스키마와 해당 해석 소스 보기
openspec schema which --all
# 대화형으로 새 스키마 만들기
openspec schema init my-workflow
# 기존 스키마를 복제하여 사용자 정의하기
openspec schema fork spec-driven my-workflow
# 사용 전 스키마 구조 검증하기
openspec schema validate my-workflow팁
- 변경 사항을 확정하기 전에
/opsx:explore를 사용하여 아이디어를 구체화하세요. - 원하는 것이 명확할 때는
/opsx:ff를, 탐색 중일 때는/opsx:continue를 사용하세요. /opsx:apply중 문제가 발생하면, 해당 산출물을 수정한 후 계속 진행하세요.- 작업은
tasks.md파일의 체크박스를 통해 진행 상황을 추적합니다. - 언제든지 상태를 확인할 수 있습니다:
openspec status --change "name"
피드백
이것은 초기 버전입니다. 의도적인 것입니다 — 어떤 것이 효과적인지 학습하고 있습니다.