遷移至 OPSX

本指南協助您從舊版 OpenSpec 工作流程遷移至 OPSX。此次遷移設計為無縫過渡——您現有的工作將完整保留，而新系統提供更靈活的選項。

有哪些變化？

OPSX 以流暢的、以操作為導向的方式取代了舊版的階段鎖定工作流程。以下是關鍵轉變：

面向	舊版	OPSX
指令	/openspec:proposal、/openspec:apply、/openspec:archive	預設：/opsx:propose、/opsx:explore、/opsx:apply、/opsx:update、/opsx:sync、/opsx:archive（擴充工作流程指令為選配）
工作流程	一次性建立所有產出物	可逐步建立或一次性建立——由您決定
回溯	不方便的階段閘門	自然流暢——隨時更新任何產出物
自訂	固定結構	以 Schema 驅動，完全可修改
設定	CLAUDE.md 搭配標記 + project.md	在 openspec/config.yaml 中進行乾淨的設定

理念上的轉變： 工作並非線性的。OPSX 不再假裝它是線性的。

---

開始之前

您現有的工作內容是安全的

遷移過程以保留為核心設計：

• openspec/changes/ 中的活躍變更 — 完全保留。您可以使用 OPSX 命令繼續處理它們。
• 已封存的變更 — 不會被更動。您的歷史紀錄保持完整。
• openspec/specs/ 中的主規格 — 不會被更動。這些是您的真實來源。
• CLAUDE.md、AGENTS.md 等檔案中的您的內容 — 保留。僅會移除 OpenSpec 標記區塊；您所編寫的一切都會保留下來。

會被移除的內容

僅移除將被取代的 OpenSpec 管理檔案：

移除項目	原因
舊式斜線命令目錄／檔案	由新的技能系統取代
openspec/AGENTS.md	已過時的工作流程觸發器
CLAUDE.md、AGENTS.md 等檔案中的 OpenSpec 標記	不再需要

依工具分類的舊式命令位置（範例—您的工具可能不同）：

• Claude Code：.claude/commands/openspec/
• Cursor：.cursor/commands/openspec-*.md
• Devin Desktop（前身為 Windsurf）：.windsurf/workflows/openspec-*.md
• Cline：.clinerules/workflows/openspec-*.md
• Roo：.roo/commands/openspec-*.md
• GitHub Copilot：.github/prompts/openspec-*.prompt.md（僅限 IDE 擴充功能；不支援 Copilot CLI）
• Codex：OpenSpec 現在使用標準的 .agents/skills/openspec-* 路徑。舊版 .codex/skills 路徑下的 OpenSpec 管理 SKILL.md 檔案，僅在已有取代項目後才會被整合；自訂檔案和分歧的副本會保留在原處。如果未標記的 .agents 樹狀結構已包含 OpenSpec 技能，OpenSpec 會保留其現有的 Codex（$openspec-*）或通用（/openspec-*）呈現方式，而不會根據舊目錄猜測。若要切換所有權，請明確地以 openspec init 選擇 codex。舊版提示清理仍然只針對 OpenSpec 白名單中的 Codex 提示檔名，範圍在 $CODEX_HOME/prompts 或 ~/.codex/prompts 內。
• 及其他（Augment、Continue、Amazon Q 等）

遷移過程會偵測您已設定的工具，並清理其舊式檔案。

要移除的清單可能看起來很長，但這些都是 OpenSpec 原本建立的檔案。您自己的內容絕不會被刪除。

需要您注意的部分

有一個檔案需要手動遷移：

openspec/project.md — 這個檔案不會自動刪除，因為它可能包含您編寫的專案背景資訊。您需要：

1. 檢閱其內容
2. 將有用的背景資訊移至 openspec/config.yaml（請參閱下方指引）
3. 準備好後刪除該檔案

我們進行此變更的原因：

舊的 project.md 是被動的 — 代理人可能會讀取它，也可能不會，甚至會忘記讀過的內容。我們發現可靠性不一致。

新的 config.yaml 背景資訊會主動注入每一個 OpenSpec 規劃請求。這表示當 AI 在建立成品時，您專案的慣例、技術堆疊和規則始終存在。可靠性更高。

取捨：

由於背景資訊會注入到每個請求，您會需要精簡內容。專注在真正重要的事：

• 技術堆疊與關鍵慣例
• AI 需要知道的非顯而易見的限制條件
• 之前經常被忽略的規則

無需追求完美。我們仍在探索這裡的最佳做法，並會隨著實驗改進背景資訊注入的方式。

---

執行遷移

openspec init 和 openspec update 都會偵測舊式檔案，並引導您完成相同的清理程序。請根據您的情況選擇適用的一個：

• 全新安裝預設使用 core 設定檔（propose、explore、apply、update、sync、archive）。
• 已遷移的安裝會透過在需要時寫入 custom 設定檔，保留您先前安裝的工作流程。

使用 openspec init

若您想要新增工具或重新設定已安裝的工具，請執行此命令：

openspec init

init 命令會偵測舊式檔案並引導您進行清理：

正在升級至新的 OpenSpec

OpenSpec 現在使用代理人技能，這是跨程式碼代理人的新興標準。
這能簡化您的設定，同時保持一切如常運作。

要移除的檔案
無需保留的使用者內容：
  • .claude/commands/openspec/
  • openspec/AGENTS.md

要更新的檔案
OpenSpec 標記將被移除，您的內容會保留：
  • CLAUDE.md
  • AGENTS.md

需要您注意
  • openspec/project.md
    我們不會刪除此檔案。它可能包含有用的專案背景資訊。

    新的 openspec/config.yaml 有一個「context:」段落，用來存放規劃背景資訊。
    這會包含在每個 OpenSpec 請求中，且比舊的 project.md 方法更可靠。

    請檢閱 project.md，將任何有用的內容移至 config.yaml 的 context 段落，
    然後在準備好時刪除該檔案。

? 要升級並清理舊式檔案嗎？ (Y/n)

當您同意時會發生什麼事：

1. 舊式斜線命令目錄被移除
2. 從 CLAUDE.md、AGENTS.md 等檔案中移除 OpenSpec 標記（您的內容保留）
3. 刪除 openspec/AGENTS.md
4. 在 .claude/skills/ 中安裝新技能
5. 建立帶有預設 schema 的 openspec/config.yaml

使用 openspec update

若您只是想遷移並將現有工具更新到最新版本，請執行此命令：

openspec update

update 命令同樣會偵測並清理舊式成品，然後重新整理產生的技能／命令以符合您目前的設定檔和交付設定。

非互動／CI 環境

用於腳本化的遷移：

openspec init --force --tools claude

--force 旗標會跳過提示並自動接受清理。

這包括清理全域 Codex 提示目錄中由 OpenSpec 管理的 Codex 提示檔案。清理僅針對 OpenSpec 白名單中的舊式 Codex 提示檔名，且僅在替代的 .agents/skills/openspec-* 技能存在後才會移除，並保留所有其他檔案。

---

將 project.md 遷移至 config.yaml

舊的 openspec/project.md 是一個自由格式的 Markdown 檔案，用來記錄專案背景。新的 openspec/config.yaml 是結構化的，且關鍵的是—會注入到每一個規劃請求中，讓您的慣例在 AI 作業時始終存在。

之前（project.md）

# Project Context

This is a TypeScript monorepo using React and Node.js.
We use Jest for testing and follow strict ESLint rules.
Our API is RESTful and documented in docs/api.md.

## Conventions

- All public APIs must maintain backwards compatibility
- New features should include tests
- Use Given/When/Then format for specifications

之後（config.yaml）

schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js
  Testing: Jest with React Testing Library
  API: RESTful, documented in docs/api.md
  We maintain backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan for risky changes
  specs:
    - Use Given/When/Then format for scenarios
    - Reference existing patterns before inventing new ones
  design:
    - Include sequence diagrams for complex flows

主要差異

project.md	config.yaml
自由格式 Markdown	結構化 YAML
單一文字區塊	分離的背景資訊與各成品規則
使用時機不明確	背景資訊會出現在所有成品；規則僅出現在對應的成品中
無 schema 選擇	明確的 schema: 欄位設定預設工作流程

保留什麼，捨棄什麼

遷移時要有選擇性。問問自己：「AI 在每個規劃請求中都需要這個嗎？」

適合放在 context: 的內容：

• 技術堆疊（語言、框架、資料庫）
• 關鍵架構模式（monorepo、微服務等）
• 非顯而易見的限制條件（「我們不能使用 X 函式庫，因為...」）
• 經常被忽略的關鍵慣例

改放到 rules: 的內容：

• 特定成品格式（「在規格中使用 Given/When/Then」）
• 審查標準（「提案必須包含復原計畫」）
• 這些僅會出現在對應的成品中，讓其他請求更輕量。

完全捨棄的內容：

• AI 已知道的一般最佳實踐
• 可被總結的冗長說明
• 不影響目前工作的歷史背景

遷移步驟

1. 建立 config.yaml（如果 init 尚未建立）：

   schema: spec-driven

2. 加入您的背景資訊（保持精簡—這會進入每個請求）：

   context: |
     您專案的背景資訊放在這裡。
     聚焦在 AI 真正需要知道的內容。

3. 加入各成品規則（選用）：

   rules:
     proposal:
       - 您的提案專屬指引
     specs:
       - 您的規格撰寫規則

4. 一旦您移轉了所有有用的內容後，刪除 project.md。

不用過度思考。 從基本需求開始，並逐步迭代。如果您注意到 AI 遺漏了某個重要的東西，就加入。如果背景資訊感覺過於冗長，就修剪。這是一份活的文件。

需要幫助？使用此提示

如果您不確定如何精簡您的 project.md，請詢問您的 AI 助理：

我正在從 OpenSpec 舊的 project.md 遷移到新的 config.yaml 格式。

這是我目前的 project.md：
[貼上您的 project.md 內容]

請協助我建立一個 config.yaml，包含：
1. 一個精簡的 `context:` 段落（這會注入到每一個規劃請求中，因此請保持簡潔—聚焦於技術堆疊、關鍵限制條件，以及經常被忽略的慣例）
2. 如果任何內容是針對特定成品，則放入 `rules:`（例如，「使用 Given/When/Then」應放在規格規則中，而非全域背景資訊）

省略任何 AI 模型已經知道的一般性內容。請嚴格追求簡潔。

AI 會協助您辨別哪些是必要的，哪些可以修剪。

---

新的命令

命令的可用性取決於設定檔：

預設（core 設定檔）：

命令	用途
/opsx:propose	建立變更並在同一步驟中產生規劃成品
/opsx:explore	無結構地思考想法
/opsx:apply	從 tasks.md 實作任務
/opsx:update	修訂變更的規劃成品並保持它們一致
/opsx:sync	將差異規格合併回主規格
/opsx:archive	完成並封存變更

擴展工作流程（自訂選項）：

命令	用途
/opsx:new	建立新的變更架構
/opsx:continue	建立下一個成品（一次一個）
/opsx:ff	快進—一次建立所有規劃成品
/opsx:verify	驗證實作是否符合規格
/opsx:bulk-archive	一次封存多個變更
/opsx:onboard	引導式端到端入門工作流程

使用 openspec config profile 啟用擴展命令，然後執行 openspec update。

舊命令對應表

舊命令	OPSX 等效命令
/openspec:proposal	/opsx:propose（預設）或 /opsx:new 然後 /opsx:ff（擴展）
/openspec:apply	/opsx:apply
/openspec:archive	/opsx:archive

新功能

這些功能是擴展工作流程命令集的一部分。

細粒度的成品建立：

/opsx:continue

根據相依性一次建立一個成品。當您想檢閱每個步驟時可使用此命令。

探索模式：

/opsx:explore

在提交變更前，與夥伴一起思考想法。

---

理解新架構

從階段鎖定到流式作業

舊版工作流程強制線性推進：

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   PLANNING   │ ───► │ IMPLEMENTING │ ───► │   ARCHIVING  │
│    PHASE     │      │    PHASE     │      │    PHASE     │
└──────────────┘      └──────────────┘      └──────────────┘

If you're in implementation and realize the design is wrong?
Too bad. Phase gates don't let you go back easily.

OPSX 使用動作（actions），而非階段（phases）：

         ┌───────────────────────────────────────────────┐
         │           ACTIONS (not phases)                │
         │                                               │
         │     new ◄──► continue ◄──► apply ◄──► archive │
         │      │          │           │             │   │
         │      └──────────┴───────────┴─────────────┘   │
         │                    any order                  │
         └───────────────────────────────────────────────┘

相依性圖

產物（Artifacts）形成有向圖。相依性是啟用條件，而非閘門：

                        proposal
                       (root node)
                            │
              ┌─────────────┴─────────────┐
              │                           │
              ▼                           ▼
           specs                       design
        (requires:                  (requires:
         proposal)                   proposal)
              │                           │
              └─────────────┬─────────────┘
                            │
                            ▼
                         tasks
                     (requires:
                     specs, design)

當您執行 /opsx:continue 時，系統會檢查哪些產物已就緒，並提供下一個可建立的產物。您也可以以任何順序建立多個已就緒的產物。

Skills 與 Commands

舊版系統使用特定工具的指令檔案：

.claude/commands/openspec/
├── proposal.md
├── apply.md
└── archive.md

OPSX 使用新興的 skills 標準：

.claude/skills/
├── openspec-explore/SKILL.md
├── openspec-new-change/SKILL.md
├── openspec-continue-change/SKILL.md
├── openspec-apply-change/SKILL.md
└── ...

Skills 可被多種 AI 編碼工具識別，並提供更豐富的元資料。

Codex 在 OPSX 中僅支援 skills。OpenSpec 不再產生 Codex 自訂提示詞檔案；請改用產生的 .agents/skills/openspec-* 目錄。

---

延續現有變更

您進行中的變更可與 OPSX 指令無縫配合。

有來自舊版工作流程的活躍變更嗎？

/opsx:apply add-my-feature

OPSX 會讀取現有產物，並從您上次中斷處繼續。

想為現有變更新增更多產物嗎？

/opsx:continue add-my-feature

會根據已存在的內容，顯示哪些產物已就緒可建立。

需要查看狀態嗎？

openspec status --change add-my-feature

---

新的設定系統

config.yaml 結構

# Required: Default schema for new changes
schema: spec-driven

# Optional: Project context (max 50KB)
# Injected into ALL artifact instructions
context: |
  Your project background, tech stack,
  conventions, and constraints.

# Optional: Per-artifact rules
# Only injected into matching artifacts
rules:
  proposal:
    - Include rollback plan
  specs:
    - Use Given/When/Then format
  design:
    - Document fallback strategies
  tasks:
    - Break into 2-hour maximum chunks

Schema 解析

在決定使用哪個 schema 時，OPSX 依序檢查：

1. CLI 旗標：--schema <name>（最高優先級）
2. 變更元資料：變更目錄中的 .openspec.yaml
3. 專案設定：openspec/config.yaml
4. 預設值：spec-driven

可用的 Schemas

Schema	Artifacts	適用場景
spec-driven	proposal → specs → design → tasks	大多數專案

列出所有可用的 schemas：

openspec schemas

自訂 Schemas

建立自己的工作流程：

openspec schema init my-workflow

或從現有 schema 分叉：

openspec schema fork spec-driven my-workflow

詳細資訊請參閱 自訂。

---

疑難排解

"Legacy files detected in non-interactive mode"

您正在 CI 或非互動式環境中執行。請使用：

openspec init --force

遷移後指令未出現

重新啟動您的 IDE。Skills 是在啟動時偵測的。

"Unknown artifact ID in rules"

請確認您的 rules: 鍵值與 schema 的產物 ID 相符：

• spec-driven：proposal、specs、design、tasks

執行以下指令查看有效的產物 ID：

openspec schemas --json

設定未生效

1. 確認檔案位於 openspec/config.yaml（而非 .yml）
2. 驗證 YAML 語法
3. 設定變更立即生效——無需重新啟動

project.md 未遷移

系統刻意保留 project.md，因為其中可能包含您的自訂內容。請手動檢視，將有用部分移至 config.yaml，然後刪除該檔案。

想查看哪些內容會被清理？

執行 init 並拒絕清理提示——您將看到完整的偵測摘要，且不會進行任何變更。

---

快速參考

遷移後的檔案結構

project/
├── openspec/
│   ├── specs/                    # Unchanged
│   ├── changes/                  # Unchanged
│   │   └── archive/              # Unchanged
│   └── config.yaml               # NEW: Project configuration
├── .claude/
│   └── skills/                   # NEW: OPSX skills
│       ├── openspec-propose/     # default core profile
│       ├── openspec-explore/
│       ├── openspec-apply-change/
│       ├── openspec-update-change/
│       ├── openspec-sync-specs/
│       ├── openspec-archive-change/
│       └── ...                   # expanded profile adds new/continue/ff/etc.
├── CLAUDE.md                     # OpenSpec markers removed, your content preserved
└── AGENTS.md                     # OpenSpec markers removed, your content preserved

已移除的內容

• .claude/commands/openspec/ — 已由 .claude/skills/ 取代
• openspec/AGENTS.md — 已過時
• openspec/project.md — 遷移至 config.yaml 後刪除
• CLAUDE.md、AGENTS.md 等檔案中的 OpenSpec 標記區塊

指令速查表

/opsx:propose      快速開始（預設核心 profile）
/opsx:apply        實作任務
/opsx:archive      完成並歸檔

# 擴展工作流程（若已啟用）：
/opsx:new          建立變更骨架
/opsx:continue     建立下一個產物
/opsx:ff           建立規劃產物

---

尋求協助

• Discord：discord.gg/YctCnvvshC
• GitHub Issues：github.com/Fission-AI/OpenSpec/issues
• 文件：docs/opsx.md 完整的 OPSX 參考手冊