範例與食譜
從頭到尾的真實變更。每個食譜都展示了你會輸入的命令以及你會看到的回應，這樣你就可以將自己的情況與某個模式對照並直接複製使用。這些食譜使用預設的 core 命令（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：修復 Bug
何時使用： 某處出錯了，你想將修復記錄為一個有意識的行為變更，而不是一個來龍去脈不明的提交。
Bug 修復的運作方式與功能完全相同。差別在於你如何撰寫提案：描述正確的行為，而不只是「修復這個 bug」。
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。
提示：對於修復，一個好的場景就是文字版的回歸測試。「GIVEN 一個已登出的使用者，WHEN 他們提交有效憑證，THEN 他們會到達儀表板且不會再次被重定向。」寫下這個，實作就有了明確的目標。
食譜 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 並撰寫增量規格——驗證會將標記加上規格檔案視為衝突，因此過期的標記不會靜默殘留。
歸檔已標記的變更不需要額外旗標（沒有增量需要合併）。獨立地，--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 參考。