自訂
OpenSpec 提供三個層級的自訂：
| 層級 | 功能 | 適用情境 |
|---|---|---|
| 專案設定 | 設定預設值、注入情境與規則 | 大多數團隊 |
| 自訂結構描述 | 定義自己的工作流程成品 | 流程獨特的團隊 |
| 全域覆寫 | 在所有專案間共用結構描述 | 進階使用者 |
專案設定
openspec/config.yaml 檔案是最簡單的團隊自訂 OpenSpec 方式，讓你可以：
- 設定預設結構描述 – 不需要在每個指令加上
--schema - 注入專案情境 – AI 能看見你的技術堆疊、慣例等資訊
- 為特定成品加入規則 – 針對個別成品加入自訂規則
- 加入每個操作的指引 – 為
apply與archive作業提供建議偏好 - 記住整合選項 – 例如 GitHub Copilot 雲端編碼代理 的選擇加入設定
快速設定
openspec init這會以互動方式引導你建立設定檔。也可以手動建立：
# openspec/config.yaml
schema: spec-driven
context: |
Tech stack: TypeScript, React, Node.js, PostgreSQL
API style: RESTful, documented in docs/api.md
Testing: Jest + React Testing Library
We value backwards compatibility for all public APIs
rules:
proposal:
- Include rollback plan
- Identify affected teams
specs:
- Use Given/When/Then format
- Reference existing patterns before inventing new ones
operations:
apply:
guidance:
- Run focused tests before the full suite
archive:
guidance:
- Keep the completion summary concise
# 由 `openspec init` 在你選擇（或拒絕）GitHub Copilot
# 雲端編碼代理時設定；控制 `init`/`update` 是否產生其檔案。
githubCopilot:
cloudAgent: false運作方式
預設結構描述：
# 沒有設定檔時
openspec new change my-feature --schema spec-driven
# 有設定檔時 – 結構描述會自動選用
openspec new change my-feature情境與規則的注入：
在產生任何成品時，你的情境與規則都會注入到 AI 提示中：
<context>
Tech stack: TypeScript, React, Node.js, PostgreSQL
...
</context>
<rules>
- Include rollback plan
- Identify affected teams
</rules>
<template>
[結構描述內建的範本]
</template>- 情境 會出現在所有成品中
- 規則 只會針對對應的成品出現
操作指引：
operations.apply.guidance 與 operations.archive.guidance 是非必要的陣列，用來提供代理該如何執行這些操作的建議說明。它們與「規則」分開：操作指引不會限制成品內容，而成品規則也不會被重新標示為操作指引。
apply 與 archive 會在執行時取用這些輸入：
openspec instructions apply --change my-feature --json
openspec instructions archive --change my-feature --json兩個介面都會將當前的專案 context 與對應的 operationGuidance 以獨立的非必要欄位傳回。每次呼叫都會從解析後的根目錄讀取最新的快照。當選用 --store <id> 時，變更、情境與指引都會來自該儲存庫，而非當前的存放庫。archive 的指令指令是唯讀的：它不會檢查或合併差異規格、寫入主規格、移動變更，或執行靜態的封存工作流程。
專案情境是提示層級的必要輸入。產生的流程會讀取它，並套用相關的專案事實、慣例與約束。操作指引則是額外的建議：流程會考量每一條項目，並遵循其中適用且與內建流程相容的項目。
這兩個欄位與 CLI 控制的狀態、解析後的路徑、內建步驟、明確的使用者選擇以及成品規則保持分開。流程在遇到情境衝突時會回報並保留控制值，不會遵循不適用或衝突的指引，並會說明原因。這兩個欄位都不是可入強制執行的檢查，流程也不會將它們的文字複製到實作檔案、規格、變更成品或摘要中，除非使用者另外要求。
封存與規格同步的輸入安全性：
封存、批次封存以及獨立的同步作業會使用 openspec status --json 中的 artifactPaths.specs.existingOutputPaths 作為唯一的差異規格來源。如果結構描述沒有 specs 成品，或是變更的實際輸出清單為空，就沒有需要同步的內容；其他成品不會被用來推斷差異規格。
在語意合併寫入主規格之前，流程會取用當下的 openspec instructions specs --change <name> --json 輸出。回傳的 specs 規則只會約束由該合併產生的主規格。單一封存會將該快照傳遞給內嵌同步，獨立同步則會直接取得，而批次封存會在任何規格寫入前先取得所有必要的快照。如果 archive 或 specs 指令回傳非零或無效的 JSON 回應，則視為查詢失敗，而非空白輸入：流程會在受影響的規格寫入或變更移動之前停止（批次封存則是在任何批次寫入或移動前停止）。
此設定不會改變封存的執行階段、使用者提示、檔案系統操作、語意合併的所有權、直接的 openspec archive 指令，或是成品 rules 的結構與輸出。
結構描述解析順序
當 OpenSpec 需要結構描述時，會依下列順序檢查：
- CLI 旗標：
--schema <name> - 變更的中介資料（變更資料夾中的
.openspec.yaml） - 專案設定（
openspec/config.yaml） - 預設值（
spec-driven）
自訂 Schema
當專案設定不足以滿足需求時，您可以建立自己的 schema，搭配完全自訂的工作流程。自訂 schema 位於專案的 openspec/schemas/ 目錄中，並與您的程式碼一起進行版本控制。
your-project/
├── openspec/
│ ├── config.yaml # 專案設定
│ ├── schemas/ # 自訂 schema 存放於此
│ │ └── my-workflow/
│ │ ├── schema.yaml
│ │ └── templates/
│ └── changes/ # 您的變更
└── src/Fork 現有 Schema
最快的自訂方式是 fork 一個內建 schema：
openspec schema fork spec-driven my-workflow這會將整個 spec-driven schema 複製到 openspec/schemas/my-workflow/，您可以在其中自由編輯。
您會得到：
openspec/schemas/my-workflow/
├── schema.yaml # 工作流程定義
└── templates/
├── proposal.md # 提案產物範本
├── spec.md # 規格範本
├── design.md # 設計範本
└── tasks.md # 任務範本現在可以編輯 schema.yaml 來修改工作流程，或編輯範本來改變 AI 產生的內容。
從零建立 Schema
若要建立完全全新的工作流程：
# 互動模式
openspec schema init research-first
# 非互動模式
openspec schema init rapid \
--description "Rapid iteration workflow" \
--artifacts "proposal,tasks" \
--defaultSchema 結構
Schema 定義了工作流程中的產物及其相互依賴關係：
# openspec/schemas/my-workflow/schema.yaml
name: my-workflow
version: 1
description: My team's custom workflow
artifacts:
- id: proposal
generates: proposal.md
description: Initial proposal document
template: proposal.md
instruction: |
Create a proposal that explains WHY this change is needed.
Focus on the problem, not the solution.
requires: []
- id: design
generates: design.md
description: Technical design
template: design.md
instruction: |
Create a design document explaining HOW to implement.
requires:
- proposal # Can't create design until proposal exists
- id: tasks
generates: tasks.md
description: Implementation checklist
template: tasks.md
requires:
- design
apply:
requires: [tasks]
tracks: tasks.md關鍵欄位：
| 欄位 | 用途 |
|---|---|
id | 唯一識別碼，用於命令和規則 |
generates | 輸出檔名（支援萬用字元，如 specs/**/*.md） |
template | templates/ 目錄中的範本檔 |
instruction | 建立此產物時的 AI 指示 |
requires | 依賴關係 — 哪些產物必須先存在 |
請按您希望書寫的順序列出產物。requires 決定哪些操作是可行的；而 artifacts: 列表中的順序則決定當多個產物同時就緒時，哪個先被處理。
範本
範本是引導 AI 的 Markdown 檔案。在建立對應產物時，它們會被注入到提示詞中。
<!-- templates/proposal.md -->
## Why
<!-- Explain the motivation for this change. What problem does this solve? -->
## What Changes
<!-- Describe what will change. Be specific about new capabilities or modifications. -->
## Impact
<!-- Affected code, APIs, dependencies, systems -->範本可以包含：
- AI 應填寫的章節標題
- 包含 AI 指引的 HTML 註解
- 展示預期結構的範例格式
驗證您的 Schema
在使用自訂 schema 之前，請先進行驗證：
openspec schema validate my-workflow驗證項目包括：
schema.yaml語法是否正確- 所有引用的範本是否存在
- 是否存在循環依賴
- 產物 ID 是否有效
使用您的自訂 Schema
建立完成後，使用以下方式套用您的 schema：
# 在命令中指定
openspec new change feature --schema my-workflow
# 或在 config.yaml 中設為預設
schema: my-workflow除錯 Schema 解析
不確定正在使用哪個 schema？使用以下命令檢查：
# 查看特定 schema 的解析來源
openspec schema which my-workflow
# 列出所有可用的 schema
openspec schema which --all輸出會顯示該 schema 來自專案、使用者目錄還是套件：
Schema: my-workflow
Source: project
Path: /path/to/project/openspec/schemas/my-workflow注意： OpenSpec 也支援位於
~/.local/share/openspec/schemas/的使用者層級 schema，可跨專案共用，但建議使用位於openspec/schemas/的專案層級 schema，因為它們會與您的程式碼一起進行版本控制。
範例
快速迭代工作流程
一個用於快速迭代的最小工作流程：
# openspec/schemas/rapid/schema.yaml
name: rapid
version: 1
description: Fast iteration with minimal overhead
artifacts:
- id: proposal
generates: proposal.md
description: Quick proposal
template: proposal.md
instruction: |
Create a brief proposal for this change.
Focus on what and why, skip detailed specs.
requires: []
- id: tasks
generates: tasks.md
description: Implementation checklist
template: tasks.md
requires: [proposal]
apply:
requires: [tasks]
tracks: tasks.md新增審查產物
Fork 預設 schema 並新增審查步驟：
openspec schema fork spec-driven with-review然後編輯 schema.yaml 新增：
- id: review
generates: review.md
description: Pre-implementation review checklist
template: review.md
instruction: |
Create a review checklist based on the design.
Include security, performance, and testing considerations.
requires:
- design
- id: tasks
# ... existing tasks config ...
requires:
- specs
- design
- review # Now tasks require review too社群 Schema
OpenSpec 也支援由社群維護的 schema，透過獨立儲存庫分發。這些 schema 提供具有特定觀點的工作流程，將 OpenSpec 與其他工具或系統整合，類似於 github/spec-kit 的社群擴充目錄 對 spec-kit 的作用。
社群 schema 不會被納入 OpenSpec 核心 — 它們擁有自己的儲存庫和發布節奏。要使用其中一個，請將 schema 套件複製到專案的 openspec/schemas/<schema-name>/ 目錄中（每個儲存庫的 README 都有安裝說明）。
| Schema | 維護者 | 儲存庫 | 描述 |
|---|---|---|---|
intent-driven | @harikrishnan83 | intent-driven-dev/openspec-schemas | 在實作之前捕捉變更意圖、可觀察行為、技術設計和持久的架構決策。新增變更本地的 ADR 審查清單，並將符合條件的長期決策寫入為不可變、可取代的 ADR。 |
superpowers-bridge | @JiangWay | JiangWay/openspec-schemas | 將 OpenSpec 的產物治理與 obra/superpowers 的執行技能（腦力激盪、撰寫計畫、透過子代理進行 TDD、程式碼審查、收尾）整合。新增一個以證據為先的 retrospective 產物，填補 Superpowers 原生未涵蓋的空白。 |
nanopm | @nmrtn | nmrtn/nanopm | 以 PM 為先的工作流程。在實作上游執行 nanopm 的規劃管線（稽核 → 策略 → 路線圖 → PRD）。將產品規劃橋接至 OpenSpec 的規格驅動工程工作流程。若存在 .nanopm/ 目錄，產物將從中讀取 — 提案來源於稽核，設計來源於策略，任務來源於 PRD 拆解。 |
e2e-runbooks | @Lukk17 | Lukk17/openspec-schemas | 能力層級的端到端測試運行手冊。每個能力都有一個不可變的規格、一個不可變的任務範本，以及每次執行的一個帶時間戳記的運行記錄。斷言僅限於可觀察行為（HTTP 狀態碼、回應主體、持久化狀態 — 絕非日誌子字串）；每次運行記錄開始/結束 UTC 時間、持續時間和最佳估計的 LLM token 消耗量。 |
anvil | @jikkujoyce | jikkujoyce/openspec-schemas | 具有 TDD 紀律和對抗性審查步驟的規格驅動工作流程。流程：proposal → specs → design → review → test-plan → tasks → apply → verify。review 由全新上下文、唯讀的審查者撰寫（在可用時使用第二個模型），並輸出一行 VERDICT: 指示代理門控 test-plan、tasks 和 apply；OpenSpec 僅檢查產物是否存在，因此請使用自己的 CI 或 hook 強制執行門控。test-plan 將每個規格場景對應到一個命名的測試，並作為 verify 稽核的紅/綠帳本。 |
想要貢獻社群 schema？請開啟一個 issue 並附上您的儲存庫連結，或提交一個 PR 在此表格中新增一行。
另請參閱
- CLI 參考：Schema 命令 - 完整的命令文件