工作流程
本指南涵蓋 OpenSpec 的常見工作流程模式，以及何時使用它們。如需基本設定資訊，請參閱 快速開始。如需命令參考資料，請參閱 命令。
理念：行動而非階段
傳統的工作流程會強制你經歷各個階段：規劃、然後實作，最後完成。但實際工作並無法如此整齊地劃分。
OPSX 採取不同的方法：
text
傳統（階段鎖定）：
PLANNING ────────► IMPLEMENTING ────────► DONE
│ │
│ 「無法回頭」 │
└────────────────────┘
OPSX（流暢的行動）：
proposal ──► specs ──► design ──► tasks ──► implement核心原則：
- 行動，而非階段 - 命令是你能夠執行的動作，而不是你被困住的步驟
- 依賴關係是使能條件 - 它們顯示哪些操作可行，而非下一步必須做什麼
自訂： OPSX 工作流程由定義工件序列的模式驅動。有關建立自訂模式的詳細資訊，請參閱 自訂。
工作流程總覽
預設工作流程保持流暢：探索與驗證為選用，當實作揭露新資訊時，您可以隨時更新規劃工件。
mermaid
flowchart TD
Idea["想法或問題"] --> Explore["/opsx:explore<br/>（選用）"]
Idea --> Propose["/opsx:propose"]
Explore --> Propose
Propose --> Review{"規劃工件<br/>已就緒？"}
Review -->|"精簡"| Update["/opsx:update"]
Update --> Review
Review -->|"實作"| Apply["/opsx:apply"]
Apply -->|"計畫變更"| Update
Apply --> Archive["/opsx:archive"]
Apply --> Verify["/opsx:verify<br/>（選用，自訂選擇）"]
Apply --> Sync["/opsx:sync<br/>（歸檔前可選）"]
Verify --> Verified{"可歸檔？"}
Verified -->|"修正實作"| Apply
Verified -->|"修訂計畫"| Update
Verified -->|"就緒"| Sync
Verified -->|"就緒"| Archive
Sync --> ArchiveAI 助理驅動工作流程，而 CLI 提供確定性的架構、狀態和工件指示：
mermaid
sequenceDiagram
actor 人類
participant Assistant as AI 助理
participant CLI as OpenSpec CLI
participant Files as 規劃與實作檔案
Human->>Assistant: /opsx:propose "變更"
Assistant->>CLI: openspec new change
CLI->>Files: 建立變更中繼資料
Assistant->>CLI: 要求狀態與工件指示
CLI-->>Assistant: 建置順序、路徑與範本
Assistant->>Files: 撰寫依 schema 定義的規劃工件
Assistant-->>Human: 呈現工件供審閱
Human->>Assistant: /opsx:apply
Assistant->>CLI: 要求套用指示
CLI-->>Assistant: 內容檔案與任務狀態
Assistant->>Files: 實作任務並更新核取方塊
Assistant-->>Human: 回報實作狀態
Human->>Assistant: /opsx:archive
Assistant->>CLI: 要求歸檔輸入與工件狀態
CLI-->>Assistant: 規劃路徑與工件完成度
Assistant->>Files: 讀取任務狀態並比對差異規格
opt 存在差異規格
Assistant-->>Human: 提議在歸檔前同步
alt 接受同步
Human->>Assistant: 確認同步
Assistant->>Files: 將差異規格合併至主要規格
else 略過同步
Human->>Assistant: 不經同步直接歸檔
end
end
Assistant->>Files: 將變更移至歸檔區
Assistant-->>Human: 回報歸檔位置與同步結果
Note over Human,CLI: CLI 替代方式：openspec archive change-name --yes 可跳過確認提示，仍會驗證、套用任何差異規格，然後歸檔兩種模式
預設快速路徑（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/
可建立：proposal
您：/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：讓我協助調查……
[分析 bundle 大小、找出緩慢的查詢、檢視元件渲染模式]
我發現三個主要瓶頸：
1. 大型未最佳化的圖片
2. ProductList 中的同步資料擷取
3. 因 context 變更導致的重新渲染
您想先處理哪一個？
您：我們先處理資料擷取問題。
您：/opsx:new optimize-product-list-fetching
AI：已建立變更。可建立：proposal
您：/opsx:continue
AI：根據我們的探索建立提案……
[撰寫納入調查見解的提案]
可建立：specs、design
您接下來想要哪一個？
您：/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 繼續：更新 Header……最佳適用： 平行工作流、緊急插單、團隊協作。
當您有多個完成的變更時，可使用 /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
│ │
驗證實作 若需要則提示同步驗證：檢查您的成果
/opsx:verify 會根據您的工件，從三個面向驗證實作：
text
您：/opsx:verify
AI：正在驗證 add-auth……
完整性
✓ tasks.md 中的所有 12 個任務都已勾選
✓ 所有規格需求都有對應程式碼
⚠ 情境「閒置逾時後的工作階段」未測試
正確性
✓ 實作符合規格意圖
✓ 已處理情境中的邊界案例
✓ 錯誤狀態符合規格定義
一致性
✓ 設計決策反映在程式碼結構中
✓ 命名慣例與 design.md 一致
⚠ 設計提到「事件驅動」，但實作使用輪詢
摘要
─────────────────────────────
嚴重問題：0
警告：2
可歸檔：是（有警告）
建議：
1. 為工作階段逾時情境新增測試
2. 考慮如設計所述重構為事件驅動，或更新 design.mdverify 檢查什麼：
| 面向 | 驗證內容 |
|---|---|
| 完整性 | 所有任務完成、所有需求實作、情境涵蓋 |
| 正確性 | 實作符合規格意圖、邊界案例已處理 |
| 一致性 | 設計決策反映在程式碼、模式一致 |
Verify 不會阻擋歸檔，但會浮現您可能想先處理的問題。
歸檔：完成變更
/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/
變更已成功歸檔。歸檔時若規格未同步會提示。它不會因任務未完成而阻擋，但會發出警告。
何時使用什麼
/opsx:ff vs /opsx:continue
| 情況 | 使用 |
|---|---|
| 需求明確，準備建置 | /opsx:ff |
| 正在探索，想逐步檢視 | /opsx:continue |
| 想要在規格前反覆調整提案 | /opsx:continue |
| 時間壓力，需要快速推進 | /opsx:ff |
| 複雜變更，想要控制 | /opsx:continue |
經驗法則： 如果您能事先描述完整範圍，使用 /opsx:ff。如果您邊做邊摸索，使用 /opsx:continue。
何時更新 vs 重新開始
常見問題：何時可以更新既有變更，何時應開始新的？
在以下情況更新既有變更：
- 相同意圖，精簡執行
- 範圍縮小（先做 MVP，其餘稍後）
- 學習驅動的修正（程式碼庫不如預期）
- 基於實作發現的設計調整
在以下情況開始新變更：
- 意圖根本改變
- 範圍爆炸，變成完全不同的工作
- 原始變更可獨立標記為「完成」
- 修補會造成更多混淆而非釐清
text
┌─────────────────────────────────────┐
│ 這是相同的工作嗎？ │
└──────────────┬──────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
相同意圖？ >50% 重疊？ 原始變更可
相同問題？ 相同範圍？ 在沒有這些
│ │ 變更下「完成」？
│ │ │
┌────────┴────────┐ ┌──────┴──────┐ ┌───────┴───────┐
│ │ │ │ │ │
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指令快速參考
完整的指令詳細資訊和選項，請參閱 Commands。
| 指令 | 用途 | 何時使用 |
|---|---|---|
/opsx:propose | 建立變更及規劃產出物 | 快速預設路徑（core 配置檔） |
/opsx:explore | 與 AI 一起思考想法 | 不確定時從這裡開始：需求不明確、調查、比較選項 |
/opsx:new | 建立變更骨架 | 擴展模式，明確控制產出物 |
/opsx:continue | 建立下一個產出物 | 擴展模式，逐步建立產出物 |
/opsx:ff | 建立所有規劃產出物 | 擴展模式，範圍明確 |
/opsx:apply | 實作任務 | 準備好撰寫程式碼 |
/opsx:verify | 驗證實作 | 擴展模式，存檔前 |
/opsx:sync | 合併增量規格 | 擴展模式，選填 |
/opsx:archive | 完成變更 | 所有工作已完成 |
/opsx:bulk-archive | 存檔多個變更 | 擴展模式，並行工作 |
下一步
- 撰寫優質規格 - 強有力的需求和場景長什麼樣子，以及如何適度調整變更規模
- 審查變更 - 在撰寫任何程式碼之前，對擬定計畫進行兩分鐘的快速檢查
- 團隊中的 OpenSpec - 變更如何與分支和 Pull Request 配合
- Commands - 完整的指令參考及選項
- Concepts - 深入探討規格、產出物和 Schema
- Customization - 建立自訂工作流程