OpenSpec

워크플로우 ​

이 가이드에서는 OpenSpec의 일반적인 워크플로우 패턴과 각 패턴을 사용해야 하는 시기에 대해 다룹니다. 기본 설정에 대해서는 시작하기를, 명령어 참조에 대해서는 명령어를 참조하십시오.

철학: 단계가 아닌 액션 ​

기존 워크플로우는 계획, 구현, 완료라는 단계를 강요합니다. 하지만 실제 업무는 이러한 상자에 깔끔하게 들어맞지 않습니다.

OPSX는 다른 접근 방식을 취합니다.

text
기존 (단계 고정):

  PLANNING ────────► IMPLEMENTING ────────► DONE
      │                    │
      │   "돌아갈 수 없음"  │
      └────────────────────┘

OPSX (유연한 액션):

  proposal ──► specs ──► design ──► tasks ──► implement

핵심 원칙:

  • 단계가 아닌 액션 - 명령어는 갇혀 있는 단계가 아니라 수행할 수 있는 작업입니다.
  • 종속성은 활성화 요소 - 종속성은 다음에 반드시 해야 할 일이 아니라 가능한 작업을 나타냅니다.

사용자 정의: OPSX 워크플로우는 아티팩트 순서를 정의하는 스키마에 의해 구동됩니다. 사용자 정의 스키마 생성에 대한 자세한 내용은 사용자 정의를 참조하십시오.

워크플로 개요 ​

기본 워크플로는 유연하게 유지됩니다. 탐색과 검증은 선택 사항이며, 구현 중 새로운 사실이 드러날 때마다 계획 산출물을 업데이트할 수 있습니다.

mermaid
flowchart TD
    Idea["Idea or problem"] --> Explore["/opsx:explore<br/>(optional)"]
    Idea --> Propose["/opsx:propose"]
    Explore --> Propose
    Propose --> Review{"Planning artifacts<br/>ready?"}
    Review -->|"Refine"| Update["/opsx:update"]
    Update --> Review
    Review -->|"Implement"| Apply["/opsx:apply"]
    Apply -->|"Plan changed"| Update
    Apply --> Archive["/opsx:archive"]
    Apply --> Verify["/opsx:verify<br/>(optional, custom selection)"]
    Apply --> Sync["/opsx:sync<br/>(optional before archive)"]
    Verify --> Verified{"Ready to archive?"}
    Verified -->|"Fix implementation"| Apply
    Verified -->|"Revise plan"| Update
    Verified -->|"Ready"| Sync
    Verified -->|"Ready"| Archive
    Sync --> Archive

AI 어시스턴트가 워크플로를 주도하며, CLI는 결정적 스캐폴딩, 상태 및 산출물 지침을 제공합니다:

mermaid
sequenceDiagram
    actor Human
    participant Assistant as AI assistant
    participant CLI as OpenSpec CLI
    participant Files as Planning and implementation files

    Human->>Assistant: /opsx:propose "change"
    Assistant->>CLI: openspec new change
    CLI->>Files: Scaffold change metadata
    Assistant->>CLI: Request status and artifact instructions
    CLI-->>Assistant: Build order, paths, and templates
    Assistant->>Files: Write schema-defined planning artifacts
    Assistant-->>Human: Present artifacts for review

    Human->>Assistant: /opsx:apply
    Assistant->>CLI: Request apply instructions
    CLI-->>Assistant: Context files and task state
    Assistant->>Files: Implement tasks and update checkboxes
    Assistant-->>Human: Report implementation status

    Human->>Assistant: /opsx:archive
    Assistant->>CLI: Request archive inputs and artifact status
    CLI-->>Assistant: Planning paths and artifact completion
    Assistant->>Files: Read task state and compare delta specs
    opt Delta specs exist
        Assistant-->>Human: Offer to sync before archiving
        alt Sync accepted
            Human->>Assistant: Confirm sync
            Assistant->>Files: Merge delta specs into main specs
        else Sync skipped
            Human->>Assistant: Archive without syncing
        end
    end
    Assistant->>Files: Move the change into the archive
    Assistant-->>Human: Report archive location and sync result

    Note over Human,CLI: CLI alternative: openspec archive change-name --yes skips confirmation prompts. It still validates, then applies any delta specs and archives

두 가지 모드 ​

기본 빠른 경로(core 프로필) ​

새 설치는 기본적으로 core 프로필을 사용하며, 다음을 제공합니다:

  • /opsx:explore
  • /opsx:propose
  • /opsx:apply
  • /opsx:update
  • /opsx:sync
  • /opsx:archive

일반적인 흐름:

text
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
  (선택 사항)

탐색으로 시작하기(길러두면 좋은 습관) ​

/opsx:explore는 고급 부가 기능이 아닌 기본 프로필의 일부입니다. 이는 문제는 있지만 아직 계획이 없을 때 사용하는 동작이며, AI 어시스턴트와 함께라면 대부분의 경우가 그렇습니다.

text
사용자: /opsx:explore

AI:  무엇을 탐색하고 싶으신가요?

사용자: 검색 결과가 오래된 느낌이에요. 캐싱, 인덱싱, 아니면 쿼리 자체의 문제인지 확실하지 않아요.

AI:  살펴보겠습니다... [검색 서비스와 캐시 계층을 읽음]
     인덱스 문제입니다. 매일 밤에만 재구축되어 편집 내용이 다음 날까지 반영되지 않습니다.
     두 가지 옵션이 있습니다: 쓰기 시 재구축(간단하지만 부하 증가) 또는 짧은 TTL 캐시 무효화(복잡하지만 부하 감소).
     쓰기 볼륨이 낮으므로 쓰기 시 재구축이 더 깔끔한 해결책입니다. 범위를 지정할까요?

사용자: 네.

사용자: /opsx:propose rebuild-search-index-on-write

탐색은 산출물을 만들지 않고 코드를 작성하지 않습니다. 이는 막연한 걱정을 정확한 변경으로 전환시키는 부담 없는 대화이며, 이어지는 제안이 명확해집니다. 이미 원하는 것을 정확히 알고 있다면 건너뛰고 바로 /opsx:propose로 가세요. 전체 가이드: 탐색 우선.

확장/전체 워크플로(사용자 지정 선택) ​

명시적인 스캐폴드 및 빌드 명령(/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard)을 사용하려면 다음으로 활성화하세요:

bash
openspec config profile
openspec update

워크플로 패턴(확장 모드) ​

빠른 기능 ​

구축하려는 것이 무엇인지 알고 있고 실행만 하면 될 때:

text
/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

예시 대화:

text
사용자: /opsx:new add-logout-button

AI:  openspec/changes/add-logout-button/ 생성됨
     제안서 생성 준비 완료

사용자: /opsx:ff

AI:  모든 계획 산출물 생성 중...
     ✓ proposal.md
     ✓ specs/
     ✓ design.md
     ✓ tasks.md
     구현 준비 완료!

사용자: /opsx:apply

AI:  작업 진행 중...
     ✓ 헤더에 로그아웃 버튼 추가
     ✓ 세션 정리 구현
     ✓ 확인 대화상자 추가
     모든 작업 완료!

사용자: /opsx:archive

AI:  ✓ 스펙 병합 완료
     ✓ 변경 사항 보관 완료

적합한 경우: 중소 규모 기능, 버그 수정, 단순 변경.

탐색형 ​

요구 사항이 불명확하거나 먼저 조사가 필요할 때:

text
/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply

예시 대화:

text
사용자: /opsx:explore

AI:  무엇을 탐색하고 싶으신가요?

사용자: 페이지 로드 성능을 개선하고 싶은데 병목 지점이 어디인지 잘 모르겠어요.

AI:  조사를 도와드리겠습니다...
     [번들 크기 분석, 느린 쿼리 식별, 컴포넌트 렌더링 패턴 검토]

     세 가지 주요 병목 지점을 찾았습니다:
     1. 최적화되지 않은 대형 이미지
     2. ProductList의 동기식 데이터 가져오기
     3. 컨텍스트 변경으로 인한 재렌더링

     먼저 어떤 것을 해결하고 싶으신가요?

사용자: 데이터 가져오기 문제를 다루겠습니다.

사용자: /opsx:new optimize-product-list-fetching

AI:  변경 사항 생성됨. 제안서 생성 준비 완료

사용자: /opsx:continue

AI:  탐색 내용을 바탕으로 제안서 작성 중...
     [조사 결과를 반영한 제안서 작성]

     스펙, 디자인 생성 준비 완료
     다음은 무엇으로 할까요?

사용자: /opsx:continue

AI:  스펙 생성 중...

적합한 경우: 성능 최적화, 디버깅, 아키텍처 결정, 불명확한 요구 사항.

병렬 변경 ​

여러 변경 사항을 동시에 작업:

text
변경 A: /opsx:new ──► /opsx:ff ──► /opsx:apply (진행 중)
                                         │
                                    컨텍스트 전환
                                         │
변경 B: /opsx:new ──► /opsx:ff ──────► /opsx:apply

예시 대화:

text
사용자: add-dark-mode 작업 중인데 버그 수정으로 끌려들어갔어요

사용자: /opsx:new fix-login-redirect

AI:  openspec/changes/fix-login-redirect/ 생성됨

사용자: /opsx:ff

AI:  ✓ 계획 산출물 생성 완료

사용자: /opsx:apply

AI:  fix-login-redirect 작업 중...
     [수정 구현]
     모든 작업 완료!

사용자: /opsx:archive

AI:  ✓ fix-login-redirect 보관 완료

사용자: 다크 모드로 돌아가죠

사용자: /opsx:apply add-dark-mode

AI:  add-dark-mode 재개 중...
     작업 2.3에서 이어서: 헤더 업데이트...

적합한 경우: 병렬 작업 흐름, 긴급 중단, 팀 협업.

완료된 변경 사항이 여러 개 있을 때는 /opsx:bulk-archive를 사용하세요:

text
사용자: /opsx:bulk-archive

AI:  완료된 변경 사항 3개 발견:
     - add-dark-mode (모든 작업 완료)
     - fix-login-redirect (모든 작업 완료)
     - update-footer (모든 작업 완료)

     스펙 충돌 확인 중...
     ⚠ add-dark-mode와 update-footer가 모두 specs/ui/에 영향을 줍니다.

     코드베이스 검사하여 해결 중...
     두 변경 모두 구현되었습니다. 시간순으로 적용하겠습니다.

     변경 사항 3개를 모두 보관할까요?

사용자: 네

AI:  ✓ add-dark-mode 보관 완료
     ✓ fix-login-redirect 보관 완료
     ✓ update-footer 보관 완료
     스펙 병합 순서: add-dark-mode → update-footer

대량 보관은 여러 변경 사항이 동일한 스펙에 영향을 줄 때 이를 감지하고, 실제 구현 여부를 확인하여 충돌을 해결합니다.

변경 사항 완료 ​

권장 완료 흐름:

text
/opsx:apply ──► /opsx:verify ──► /opsx:archive
                    │                 │
              구현 검증         필요 시 동기화 제안

Verify: 작업 확인 ​

/opsx:verify는 구현을 산출물에 대해 세 가지 차원에서 검증합니다:

text
사용자: /opsx:verify

AI:  add-auth 검증 중...

     완전성
     ✓ tasks.md의 12개 작업 모두 체크됨
     ✓ 스펙의 모든 요구 사항에 해당 코드가 있음
     ⚠ "세션 시간 초과" 시나리오가 테스트되지 않음

     정확성
     ✓ 구현이 스펙 의도와 일치
     ✓ 시나리오의 엣지 케이스 처리됨
     ✓ 오류 상태가 스펙 정의와 일치

     일관성
     ✓ 디자인 결정이 코드 구조에 반영됨
     ✓ 명명 규칙이 design.md와 일치
     ⚠ 디자인은 "이벤트 기반"을 언급하지만 구현은 폴링 사용

     요약
     ─────────────────────────────
     치명적 문제: 0
     경고: 2
     보관 준비: 예 (경고 포함)

     권장 사항:
     1. 세션 시간 초과 시나리오에 대한 테스트 추가
     2. 설계된 대로 이벤트 기반으로 리팩터링하거나 design.md 업데이트 고려

verify가 검사하는 것:

차원검증 내용
완전성모든 작업 완료, 모든 요구 사항 구현, 시나리오 처리
정확성구현이 스펙 의도와 일치, 엣지 케이스 처리
일관성디자인 결정이 코드에 반영, 패턴 일관성

Verify는 보관을 차단하지 않지만, 먼저 해결하고 싶을 수 있는 문제를 표면화합니다.

Archive: 변경 사항 확정 ​

/opsx:archive는 변경 사항을 완료하고 아카이브로 이동합니다:

text
사용자: /opsx:archive

AI:  add-auth 보관 중...

     산출물 상태:
     ✓ proposal.md 존재
     ✓ specs/ 존재
     ✓ design.md 존재
     ✓ tasks.md 존재 (12/12 작업 완료)

     델타 스펙: 아직 메인과 동기화되지 않음
     → 지금 동기화할까요?

사용자: 네

AI:  ✓ 스펙을 openspec/specs/auth/spec.md에 동기화
     ✓ openspec/changes/archive/2025-01-24-add-auth/로 이동

     변경 사항이 성공적으로 보관되었습니다.

스펙이 동기화되지 않은 경우 Archive가 프롬프트를 표시합니다. 불완전한 작업이 있어도 차단하지 않지만, 경고는 표시합니다.

언제 무엇을 사용할까 ​

/opsx:ff vs /opsx:continue ​

상황사용
요구 사항이 명확하고, 구축 준비 완료/opsx:ff
탐색 중이며 각 단계를 검토하고 싶음/opsx:continue
스펙 작성 전에 제안서를 반복하고 싶음/opsx:continue
시간 압박, 빠르게 진행 필요/opsx:ff
복잡한 변경, 제어를 원함/opsx:continue

경험 법칙: 전체 범위를 사전에 설명할 수 있다면 /opsx:ff를 사용하고, 진행하면서 파악하고 있다면 /opsx:continue를 사용하세요.

업데이트 vs 새로 시작 ​

기존 변경 사항을 업데이트해도 되는 시점과 새로 시작해야 하는 시점은 언제일까요?

기존 변경 사항을 업데이트할 때:

  • 동일한 의도, 개선된 실행
  • 범위가 좁아짐 (MVP 먼저, 나머지는 나중에)
  • 학습 기반 수정 (코드베이스가 예상과 다름)
  • 구현 발견에 따른 디자인 조정

새로운 변경 사항을 시작할 때:

  • 의도가 근본적으로 변경됨
  • 범위가 완전히 다른 작업으로 확대됨
  • 원래 변경 사항을 단독으로 "완료"로 표시할 수 있음
  • 패치가 혼란을 더 야기할 때
text
                     ┌─────────────────────────────────────┐
                     │      동일한 작업인가?                 │
                     └──────────────┬──────────────────────┘
                                    │
                 ┌──────────────────┼──────────────────┐
                 │                  │                  │
                 ▼                  ▼                  ▼
          동일한 의도?      50% 이상 중복?      원래 변경 없이
          동일한 문제?       동일한 범위?       "완료"로 처리 가능?
                 │                  │                  │
       ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
       │                 │  │             │   │               │
      예               아니오 예           아니오  아니오         예
       │                 │  │             │   │               │
       ▼                 ▼  ▼             ▼   ▼               ▼
    업데이트          새로 생성  업데이트     새로 생성  업데이트        새로 생성

예시: "다크 모드 추가"

  • "커스텀 테마도 지원해야 함" → 새 변경 사항 (범위 확대)
  • "시스템 환경 설정 감지가 예상보다 어려움" → 업데이트 (동일한 의도)
  • "토글 먼저 출시하고, 나중에 설정 추가" → 업데이트 후 보관, 그 다음 새 변경 사항

모범 사례 ​

변경 사항을 집중적으로 유지하기 ​

한 번의 변경에는 하나의 논리적 작업 단위를 할당하세요. "기능 X 추가 및 Y 리팩토링"과 같이 여러 작업을 한 번에 수행해야 하는 경우, 별도의 두 가지 변경으로 나누는 것을 고려하세요.

중요한 이유:

  • 검토와 이해가 용이함
  • 아카이브 역사가 깔끔함
  • 독립적으로 배포 가능
  • 필요 시 롤백이 단순함

명확하지 않은 요구사항에는 /opsx:explore 사용 ​

변경 사항에 확정하기 전에 문제 공간을 탐색하세요:

text
사용자: /opsx:explore

AI:  무엇을 탐색하고 싶으신가요?

사용자: API의 속도 제한(rate limiting)을 어떻게 처리해야 할까요?

AI:  현재 설정과 옵션을 조사해 보겠습니다...
     [코드베이스 조사, 패턴 고려]

     다음과 같은 세 가지 접근 방식을 제안할 수 있습니다:
     1. 미들웨어 기반 (단순, 엔드포인트별 적용)
     2. Redis 기반 (확장성 우수, 공유 상태 관리)
     3. 사용자별 토큰 버킷 (공정하지만 복잡함)

     현재 스택을 보면 #1 또는 #2가 적합해 보입니다. 예상 규모는 어떻게 되나요?

탐색은 아티팩트를 생성하기 전에 사고를 명확히 합니다.

아카이빙 전 검증하기 ​

/opsx:verify를 사용하여 구현 내용이 아티팩트와 일치하는지 확인하세요:

text
사용자: /opsx:verify

AI:  add-dark-mode 변경 사항을 검증 중입니다...

     ✓ tasks.md의 모든 작업이 완료됨
     ✓ 명세(specs)의 요구사항에 해당하는 코드가 존재함
     ✓ 설계 결정 사항이 구현에 반영됨

     아카이빙 준비 완료!

변경 사항을 닫기 전에 불일치를 잡아냅니다.

변경 사항 이름을 명확하게 지정하기 ​

명확한 이름은 openspec list 명령어의 유용성을 높입니다:

text
좋은 예:                          피해야 할 예:
add-dark-mode                    feature-1
fix-login-redirect               update
optimize-product-query           changes
implement-2fa                    wip

명령어 빠른 참조 ​

전체 명령어 세부 정보와 옵션은 Commands 문서를 참조하세요.

명령어목적사용 시기
/opsx:propose변경 사항 및 계획 아티팩트 생성기본 경로(core 프로필)에서 빠르게 시작
/opsx:exploreAI와 함께 아이디어 구체화불분명한 요구사항, 조사, 옵션 비교 등 확신이 없을 때 시작
/opsx:new변경 사항 구조(scaffold) 시작확장 모드, 명시적인 아티팩트 제어
/opsx:continue다음 아티팩트 생성확장 모드, 단계별 아티팩트 생성
/opsx:ff모든 계획 아티팩트 생성확장 모드, 명확한 범위 정의
/opsx:apply작업 구현코드 작성을 준비한 상태
/opsx:verify구현 내용 검증확장 모드, 아카이빙 전
/opsx:sync델타 명세(delta specs) 병합확장 모드, 선택 사항
/opsx:archive변경 사항 완료모든 작업 종료
/opsx:bulk-archive여러 변경 사항 일괄 아카이빙확장 모드, 병렬 작업

다음 단계 ​

  • Writing Good Specs - 강력한 요구사항과 시나리오의 특징, 그리고 적절한 변경 사항 크기 조절 방법
  • Reviewing a Change - 코드 작성 전 초안 검토를 위한 2분 체크리스트
  • OpenSpec on a Team - 변경 사항이 브랜치 및 풀 리퀘스트(Pull Request)와 어떻게 연동되는지
  • Commands - 옵션이 포함된 전체 명령어 참조
  • Concepts - 명세, 아티팩트, 스키마에 대한 심층 분석
  • Customization - 사용자 정의 워크플로우 생성