設定你的專案

將 OpenSpec 加入專案：執行 init、查看它寫入了什麼，然後進行調整。

選擇 OpenSpec 的存放位置

• 在你的儲存庫中（預設）：規格與變更會放在它們所描述的程式碼旁邊，並隨程式碼一起進行版本控制。本頁其餘內容皆依此方式說明。
• 在 Store 中：這是一個獨立的規劃儲存庫，由使用它的儲存庫共用，適用於多儲存庫設定，或將規劃完全移出儲存庫。Stores（Beta） 說明何時值得這麼做，以及如何設定一個 Store。

初始化你的專案

安裝 CLI 後（安裝），在專案根目錄執行 init。在終端機中：

cd <your-project>
openspec init

Init 會詢問你使用哪些 AI 工具，為你選取的工具寫入工作流程檔案，並回報結果：

OpenSpec Setup Complete

Created: Claude Code
6 skills and 6 commands in .claude/
Config: openspec/config.yaml (schema: spec-driven)

重新啟動 IDE，讓新指令生效。

重新執行 init 是安全的：

• 你已設定過的工具會顯示 Refreshed，而不是 Created。
• 再次執行 init 並選取新工具時，會加入該工具。
• --tools 旗標會略過選取器（CLI 參考）。

移轉現有的 project.md

Init 不會將舊版 openspec/project.md 複製到 config.yaml。它會保留該檔案，並顯示一段 AI 輔助移轉請求。

在 AI 對話中：

檢閱 openspec/project.md，並將其有用的內容移轉到 openspec/config.yaml。
保持內容脈絡簡潔：只包含建立產出物、套用與封存期間所需的專案整體事實。
將特定產出物的指引移至對應產出物的 rules 中。
將套用或封存的指引移至對應的 operations 項目。
略過一般性、過時或冗長的內容。請勿刪除 project.md。

檢閱 config.yaml，準備好後再刪除 project.md。

init 會安裝什麼

執行 init 會在專案中建立兩項內容：

• 儲存庫根目錄下的 openspec/ 資料夾
• 加入你的 AI 工具資料夾（.agents/、.claude/ 等）的工作流程檔案（技能與指令）

像其他原始碼一樣，將這些內容全部提交。Init 不會變更你儲存庫中的其他任何內容（如果發現舊版 OpenSpec 留下的殘留檔案，會先詢問再清理）。

openspec/ 資料夾

每個 OpenSpec 產出物都位於這裡，也就是專案根目錄。看起來如下：

openspec/
├── config.yaml     專案設定與供 AI 使用的內容脈絡
├── specs/          你的規格（目前為空）
└── changes/        進行中的變更（目前為空）
    └── archive/    已完成的變更會移到此處

專案設定 涵蓋 config.yaml。

工作流程檔案（技能與指令）

這些是 OpenSpec 工作流程，也就是你在工作時會使用的動作。以下將它們呈現為已安裝的技能，位於多數工具使用的共用 .agents/ 資料夾中：

.agents/skills/
├── openspec-explore/              先仔細思考一個想法
├── openspec-propose/              提出變更
├── openspec-apply-change/         實作變更的任務
├── openspec-update-change/        修訂變更的計畫
├── openspec-sync-specs/           將變更的規格更新同步至 specs/
├── openspec-archive-change/       將完成的變更移至封存區
├── openspec-verify-change/        檢查實作是否符合計畫（預設不包含）
└── openspec-bulk-archive-change/  一次封存多個變更（預設不包含）

這是預設組合，另加兩個選用工作流程。設定檔（Profiles） 列出全部十二個工作流程。

每個工作流程預設會以兩種形式安裝：

• 技能（openspec-apply-change）：當你要求執行工作時，你的代理程式會自行採用的指示。
• 指令（Claude Code 中的 /opsx:apply）：相同工作流程的輸入進入點，名稱較短。

兩者在功能上完全相同。工作流程的技能與其指令包含相同的指示。

為什麼要有兩種：指令先出現，而且每個工具都有自己的命名方式。技能是較新的標準，由各工具共用，但並非每個工具都能直接叫用技能，因此指令仍作為這些工具的進入點。

有些工具僅以技能形式安裝。若工具會直接執行技能，init 會略過指令並顯示提示（Commands skipped for: codex (uses skills)）。

我們偏好技能，並預期最終淘汰指令。

變更要安裝的內容

互動式選取器會變更交付形式與工作流程組合（設定檔（Profiles））。在終端機中：

openspec config profile

以下是切換為僅使用技能：

Current profile settings
  Delivery: both

? What do you want to configure? Delivery only
? Delivery mode (how workflows are installed): Skills only

Config changes:
  delivery: both -> skills
? Apply changes to this project now? (Y/n) y

回答 yes 會立即套用到目前專案。其他專案會在下一次執行 openspec update 時套用。此設定是全域的，以機器為單位。

Claude Code 未顯示工作流程

Claude Code 會根據你的交付設定，從下列一或兩個專案路徑載入 OpenSpec 工作流程：

• 技能：.claude/skills/openspec-*/SKILL.md
• 指令：.claude/commands/opsx/<id>.md

如果檔案不存在，請重新整理專案。在終端機中：

openspec update

如果指令檔案存在，但 /opsx: 沒有顯示任何 OpenSpec 指令，請更新 Claude Code 並重新啟動。如果指令仍未載入，也啟用技能。在終端機中：

openspec config set delivery both
openspec update

重新啟動 Claude Code，然後在其對話中執行 /openspec-propose。如果只有部分工作流程缺少，變更你的設定檔。

設定完成。快速入門 會從這裡帶你完成第一個變更。