예시 및 레시피
실제 변경 사항, 처음부터 끝까지. 각 레시피는 입력할 명령어와 그에 대한 응답을 보여 주므로, 상황에 맞는 패턴을 찾아 복사할 수 있습니다. 기본 핵심 명령어(propose, explore, apply, update, sync, archive)를 사용합니다. 확장된 명령어 세트가 유용한 경우에는 별도로 표시합니다.
시작하기 전에 알림: /opsx:propose 같은 슬래시 명령어는 AI 어시스턴트 채팅에 입력하고, openspec 명령어는 터미널에 입력합니다. 이 부분이 처음이라면 명령어 작동 방식을 먼저 읽어 보세요. 아래 대화 기록에서 You:와 AI:는 채팅이고, $로 시작하는 줄은 터미널입니다.
아직 무엇을 만들지 확실하지 않나요? 대부분의 레시피는
/opsx:explore로 먼저 생각을 정리하면 더 효과적입니다. 레시피 3에서 실제 사용 예를 볼 수 있고, 탐색 우선 가이드에서 전체적인 설명을 확인할 수 있습니다.
레시피 1: 작은 기능, 빠른 경로
사용 시점: 원하는 것이 명확하고, 범위가 제한된 작업일 때. 가장 일반적인 레시피입니다.
전체 과정은 세 가지 명령어입니다. 제안, 빌드, 보관.
You: /opsx:propose add-logout-button
AI: Created openspec/changes/add-logout-button/
✓ proposal.md — why and what
✓ specs/ — the new requirement and its scenarios
✓ design.md — technical approach
✓ tasks.md — implementation checklist
Ready for implementation. Run /opsx:apply.이제 계획을 읽어 보세요. 제안서와 델타 스펙을 엽니다. OpenSpec이 만들어진 이유가 바로 이 순간입니다: 잘못된 가정을 400줄의 코드가 아닌 한 문단일 때 잡아내는 것입니다. 문제가 있으면 아티팩트를 직접 편집한 다음 계속 진행합니다.
You: /opsx:apply
AI: Working through tasks...
✓ 1.1 Add logout button to header
✓ 1.2 Clear session on click
✓ 1.3 Add confirmation dialog
All tasks complete!
You: /opsx:archive
AI: Archiving add-logout-button...
✓ Merged specs into openspec/specs/auth/spec.md
✓ Moved to openspec/changes/archive/2026-06-22-add-logout-button/
Done. Ready for the next change.이것이 전부입니다. 로그아웃 동작은 이제 스펙의 일부가 되었고, 변경 사항은 전체 컨텍스트와 함께 정리되어 보관됩니다.
레시피 2: 버그 수정
사용 시점: 무언가 고장 났고, 수정 사항을 미스터리 커밋이 아닌 의도적인 동작 변경으로 기록하고 싶을 때.
버그 수정은 기능과 정확히 동일하게 작동합니다. 차이점은 제안을 구성하는 방식입니다: 단순히 "버그 수정"이 아니라 올바른 동작을 설명하세요.
You: /opsx:propose fix-login-redirect-loop
AI: Created openspec/changes/fix-login-redirect-loop/
The proposal captures the current broken behavior and the
intended behavior. The delta spec MODIFIES the redirect
requirement so it's now precise and testable.
Ready for implementation.수정 사항이 MODIFIED 요구 사항과 새로운 시나리오로 기록되므로, 다음 사람(또는 다음 AI 세션)은 단순히 수정했다는 사실뿐만 아니라 "올바른" 동작이 무엇인지도 알 수 있습니다. 그런 다음 평소처럼 /opsx:apply와 /opsx:archive를 실행합니다.
팁: 수정의 경우 좋은 시나리오는 회귀 테스트를 산문으로 작성한 것입니다. "로그아웃된 사용자가 유효한 자격 증명을 제출하면 대시보드에 도달하고 다시 리다이렉트되지 않는다." 이것을 작성하면 구현에 명확한 목표가 생깁니다.
레시피 3: 커밋 전에 탐색하기
사용 시점: 문제는 있지만 아직 계획이 없을 때. 무엇을 만들지, 어떤 접근 방식이 맞는지 확실하지 않을 때.
/opsx:explore로 시작하세요. 구조나 아티팩트 생성 없이 생각을 정리하는 파트너입니다. 코드베이스를 읽고 결정을 도와줍니다.
You: /opsx:explore
AI: What would you like to explore?
You: Page loads feel slow but I don't know where the time goes.
AI: Let me look... I found three likely culprits:
1. Large unoptimized images on the product list
2. Synchronous data fetching that blocks render
3. Re-renders triggered by context changes
Which should we tackle first?
You: The data fetching one.
You: /opsx:propose optimize-product-list-fetching
AI: Created the change, with a proposal informed by what we just
found. Ready for implementation.탐색은 변경 사항에 투자하기 전에 생각을 명확히 합니다. 통찰력이 구체화되면 제안하고, AI가 컨텍스트를 이어받습니다.
레시피 4: 두 가지 변경 동시 처리
사용 시점: 기능 작업 중에 긴급 수정이 대기열에 끼어들 때.
변경 사항은 독립적인 폴더이므로 병렬 작업은 충돌하지 않습니다. 수정을 시작하고 배포한 다음, 중단했던 지점에서 기능 작업을 재개하세요.
You: I'm partway through add-dark-mode, but I need to fix a login bug now.
You: /opsx:propose fix-login-redirect
AI: Created openspec/changes/fix-login-redirect/. Ready for implementation.
You: /opsx:apply
AI: Implemented the fix. All tasks complete.
You: /opsx:archive
AI: ✓ Archived fix-login-redirect.
You: Back to dark mode.
You: /opsx:apply add-dark-mode
AI: Resuming add-dark-mode. Picking up at task 2.3: Update Header.../opsx:apply add-dark-mode에서 변경 이름을 지정하는 것은 두 개 이상의 변경이 활성화되어 있을 때 AI를 특정 변경으로 안내하는 방법입니다. 작업 완료 상태는 tasks.md에 추적되므로 AI는 정확히 어디서 중단했는지 알 수 있습니다.
여러 변경이 동시에 완료되면 확장된 /opsx:bulk-archive 명령으로 함께 보관하고, 실제 구현된 내용을 확인하여 스펙 충돌을 해결합니다. 워크플로를 참조하세요.
레시피 5: 동작 변경 없는 리팩토링
사용 시점: 코드를 재구성하고 있으며, 외부에서 보이는 동작은 동일하게 유지되어야 할 때.
순수 리팩토링은 스펙에 추가할 것이 없기 때문에 흥미로운 경우입니다. 동작 계약은 변경되지 않습니다. 구현만 변경됩니다. 따라서 작업은 설계와 작업에만 있으며, 스펙 델타는 비어 있거나 없습니다.
You: /opsx:propose refactor-payment-module
AI: Created the change. The proposal states the goal (split the
payment module, no behavior change) and the design captures
the new structure. No spec changes, since behavior is identical.
Ready for implementation.변경 사항의 .openspec.yaml에서 skip_specs: true를 설정하여 빈 델타를 명시적으로 선언하세요:
schema: spec-driven
skip_specs: true표시가 없으면 openspec validate는 델타가 없는 변경을 거부합니다(따라서 잊어버린 스펙 단계도 잡아냅니다). 표시가 있으면 검증을 통과하고 openspec status는 스펙 단계가 보류 중이 아니라 명시적으로 건너뛰었음을 표시합니다. 리팩토링이 결국 동작을 변경하게 되면 .openspec.yaml에서 skip_specs를 제거하고 델타 스펙을 작성하세요. validate는 표시와 스펙 파일이 함께 있는 것을 충돌로 간주하므로, 오래된 표시가 조용히 남아 있을 수 없습니다.
표시된 변경을 보관할 때 추가 플래그는 필요하지 않습니다(병합할 델타가 없기 때문). 독립적으로, --skip-specs 플래그는 터미널 명령어가 스펙 단계를 명시적으로 건너뛰도록 지시합니다:
$ openspec archive refactor-payment-module --skip-specs동일한 플래그는 도구, CI 및 문서 전용 변경에도 유용합니다. 원칙: 스펙은 동작을 설명하므로, 동작이 변경되지 않았다면 스펙도 변경되지 않아야 합니다. 개념을 참조하세요.
레시피 6: 단계별 제어 (확장 명령어)
사용 시점: 복잡하거나 위험한 변경으로, 각 아티팩트를 검토한 후 다음 단계로 진행하고 싶을 때.
핵심 /opsx:propose는 모든 것을 한 번에 초안 작성합니다. 한 단계씩 진행하려면 확장 명령어를 활성화하세요:
$ openspec config profile # select the expanded workflows
$ openspec update # apply them to this project이제 점진적으로 스캐폴드하고 빌드할 수 있습니다:
You: /opsx:new add-2fa
AI: Created openspec/changes/add-2fa/. Ready to create: proposal.
You: /opsx:continue
AI: Created proposal.md. Now available: specs, design.
You: /opsx:continue
AI: Created specs/auth/spec.md. Now available: design.각 아티팩트가 생성되면 검토하고 자유롭게 편집한 다음 만족할 때 계속 진행하세요. 나머지를 한 번에 초안 작성하려면 /opsx:ff가 남은 계획 아티팩트를 빠르게 진행합니다. 보관 전에 /opsx:verify가 구현이 실제로 스펙과 일치하는지 확인합니다. 워크플로를 참조하세요.
레시피 7: 전체 루프 직접 경험
사용 시점: OpenSpec을 설치했고 실제 코드에서 워크플로를 체감하고 싶을 때. 장난감 예제가 아니라요.
확장 명령어를 켠 다음(레시피 6 참조):
You: /opsx:onboard
AI: Welcome to OpenSpec! I'll walk you through a complete change
using your actual codebase. Let me scan for a small, safe
improvement we can make together.../opsx:onboard는 실제(작은) 개선점을 찾아 변경을 만들고 구현하고 보관하며 각 단계를 설명합니다. 15~30분이 소요되며, 유지하거나 버릴 수 있는 실제 변경 사항을 남깁니다. 가장 부드러운 학습 방법입니다. 명령어를 참조하세요.
터미널에서 작업 확인
언제든지 터미널에서 상태를 확인할 수 있습니다:
$ openspec list # active changes
$ openspec show add-dark-mode # one change in detail
$ openspec validate add-dark-mode # check structure
$ openspec view # interactive dashboard이것들은 읽기 및 검사 도구입니다. 제안과 빌드는 여전히 채팅의 슬래시 명령어를 통해 이루어집니다. 자세한 내용은 CLI 참조에 있습니다.