快速開始
你的第一個變更，從想法到歸檔，無論是全新或既有的專案。
開始之前，你需要在本機安裝 CLI（安裝），並在專案中初始化 OpenSpec（設定專案）。
從空白專案開始
你可以不選定技術棧或完整架構就開始。在專案資料夾中初始化 OpenSpec，然後請你的代理與你一起探索選項。在 AI 聊天中：
Help me explore a task tracker from scratch. I have not picked a stack. Compare the options and help me choose the first behavior to build.決定第一個變更需要什麼，並為日後的架構選擇保留空間。請你的代理提案該變更，然後按照以下步驟進行。隨著專案成長，你可以重新檢視架構。
流程一覽
每個變更都經過相同的五個步驟：你與代理一起釐清想法、它起草計畫、在程式碼還不存在時你修正計畫、代理根據計畫建構、歸檔則將已交付的內容更新到規格中。
flowchart LR
explore["1 · 探索<br/>一起釐清想法"] --> propose["2 · 提案<br/>代理起草計畫"]
propose --> review["3 · 審查<br/>你修正計畫"]
review --> apply["4 · 套用<br/>代理逐項建構"]
apply --> archive["5 · 歸檔<br/>規格吸收變更"]
archive -. "下一個變更" .-> explore
以下每個提示都在 AI 聊天中輸入，與你要求程式碼的地方相同。範例使用淺白語言，因此在各種工具中都能運作。你也可以直接呼叫技能；語法因工具而異（支援的工具）。
步驟 1：探索
在要求計畫之前，先與你的代理一起釐清想法。在 AI 聊天中：
Help me explore how rate limiting should work in this app.探索是一種思考模式。代理會調查你的程式碼庫、提出重要的問題、勾勒選項並挑戰假設。它從不寫程式碼。除非你要求它記錄你的決定，或在它提出時說好，否則它不會寫其他東西。產出是一個更清晰的想法。
視問題需要在此停留多久。當輪廓感覺對了，就交接：
Propose the change we just discussed.這一行會為你啟動提案，帶著你確定的所有內容。跳過步驟 2 的第一個提示。
步驟 2：提案
提案將想法轉化為可審查的計畫。從探索進入時，它已經在運作。如果是直接開始，當變更在你腦海中已經很清晰時，直接要求。在 AI 聊天中：
Propose a change to add rate limiting.代理會詢問它需要的內容，然後寫入變更資料夾：
openspec/changes/add-rate-limiting/
├── proposal.md 原因與變更內容
├── specs/ 「完成」的定義，以可測試的需求呈現
├── design.md 技術決策（僅當變更需要時）
└── tasks.md 實作檢查清單還沒有程式碼。提案停在計畫階段。
步驟 3：審查並修正計畫
在計畫還只是文字、尚未建構任何東西時修正它。依以下順序閱讀：
proposal.md：這是正確的問題嗎？規模合適嗎？specs/：價值最高的閱讀。你會接受這些需求為已完成嗎？tasks.md：任務是否涵蓋了規格，且沒有多餘的內容？
要修正內容，以下兩種方式都可以：
- 自己編輯檔案。這些產出是純 markdown，檔案本身就是計畫。
- 告訴你的代理哪裡錯了（「規格缺少未驗證的情況」）。它會修改產出。
步驟 4：套用
套用將計畫轉化為程式碼。開啟一個新的聊天工作階段，因為實作在乾淨的上下文視窗中會更順利。在 AI 聊天中：
Apply the add-rate-limiting change.代理會讀取變更資料夾，然後處理 tasks.md，逐一勾選完成任務。
- 被中斷或超出上下文？ 開啟新工作階段並要求它再次套用。它會從未勾選的任務繼續。
- 計畫結果是錯的？ 修正產出（使用步驟 3 的任一方式），然後繼續套用。
- 進度記錄在
tasks.md的核取方塊中。沒有隱藏的狀態。
步驟 5：歸檔
歸檔做兩件事：它將變更的需求更新到主要規格中，並將變更資料夾移到歸檔資料夾（位於 /openspec/changes/archive/*）。
當 tasks.md 中的每個核取方塊都被勾選時，在 AI 聊天中：
Archive the add-rate-limiting change.逐步了解歸檔的執行內容：
## 已完成的變更
> 實作已完成。增量規格（此變更新增的內容）仍在變更資料夾內；specs/ 還不知道速率限制。
openspec/
├── specs/ （尚無 rate-limiting 規格）
└── changes/
└── add-rate-limiting/
├── proposal.md
├── tasks.md 每個核取方塊都已勾選
└── specs/
└── rate-limiting/
└── spec.md 增量：已新增的需求
## 需求進入 specs/
> 增量中的每個需求都會進入主要規格：新增的會附加，修改的會取代舊版本。新能力會獲得新的規格檔案。
openspec/
├── specs/
+ │ └── rate-limiting/
+ │ └── spec.md 獲得「需求：速率限制」
└── changes/
└── add-rate-limiting/
└── specs/
└── rate-limiting/
└── spec.md 增量，合併的來源
## 資料夾移至 archive/
> 整個變更資料夾（包含增量）以日期前綴移至歸檔。不會刪除任何內容。
openspec/
├── specs/
│ └── rate-limiting/
│ └── spec.md
└── changes/
- └── add-rate-limiting/
+ └── archive/
+ └── 2026-08-08-add-rate-limiting/
+ ├── proposal.md
+ ├── tasks.md
+ └── specs/rate-limiting/spec.md
## 規格描述已建置的系統
> changes/ 已清空，準備迎接下一個變更。specs/ 是系統行為的真實來源；archive/ 則是系統如何演進的歷史。
openspec/
├── specs/
│ └── rate-limiting/
│ └── spec.md 已建置的規格
└── changes/
└── archive/
└── 2026-08-08-add-rate-limiting/Git 是獨立的考量。將變更資料夾與程式碼一起提交，你的工作流程其他部分不會改變。
保留或修剪已歸檔的變更
openspec/changes/archive/ 保存每個已完成變更的提案、設計、任務和增量。在上述歸檔流程中，增量已更新了 openspec/specs/。
- 保留整個變更資料夾：當你想在目前的 checkout 中擁有自包含的記錄時。
- 移除已歸檔變更的
specs/資料夾：當 Git 是你的規格歷史時。先提交歸檔，然後刪除openspec/changes/archive/<change>/specs/。提案、設計和任務仍保留在 checkout 中。openspec validate --archived仍然有效，因為它檢查任務完成情況，而非已套用的增量。 - 移除整個變更資料夾：僅當你在 checkout 中不再需要其提案、設計或任務歷史時。目前的規格不會改變，但
openspec validate --archived和 checkout 的搜尋將不再包含該變更。
WARNING
如果你想讓 Git 保留已刪除的檔案，請在儲存庫歷史中保留歸檔提交。將歸檔和清理提交壓縮在一起會移除該中間快照。
OpenSpec 不會自動修剪已歸檔的變更，也不提供保留設定。
進一步了解
進階指南
尚未撰寫；我們計畫新增的指南：
- 先做原型：在任何規格之前先進行技術驗證，然後根據原型的經驗回填提案。
- 疊代式建置：一連串小變更，而非一個大型提案。
- 修改已實作的變更：計畫在套用後需要再次調整，但變更尚未合併或歸檔。