OpenSpec

快速入門 ​

本指南說明在安裝並初始化 OpenSpec 之後，它是如何運作的。安裝說明請參閱主 README或安裝指南。首次接觸整套文件？文件首頁為您整理了一切。

這些指令應該在哪裡輸入？ 有兩個地方，搞混它們是最常見的初期障礙。

  • openspec ... 指令（如 openspec init）在終端機中執行。
  • /opsx:... 指令（如 /opsx:propose）在AI 助手的對話框中執行，也就是你通常請它寫程式碼的那個地方。

沒有獨立的「互動模式」需要啟動。你只需在對話中輸入斜線指令，AI 助手就會接手後續工作。完整說明請參閱：指令運作方式。

你的前五分鐘 ​

完整流程，每個步驟都標註了執行位置：

text
TERMINAL   $ npm install -g @fission-ai/openspec@latest
TERMINAL   $ cd your-project && openspec init
AI CHAT      /opsx:explore                    (可選：先思考規劃)
AI CHAT      /opsx:propose add-dark-mode      (AI 起草計畫；你進行審核)
AI CHAT      /opsx:apply                      (AI 開始建置)
AI CHAT      /opsx:archive                    (規格已更新，變更已歸檔)

終端機中只需兩個步驟完成設定，之後你就在對話中工作。本指南的其餘部分將逐步說明每個步驟的作用以及你會看到什麼。

不想自己操作終端機？ 將設定提示詞貼到 AI 助手中，它會處理這兩行指令，然後回報它建立了什麼。

還不清楚要建置什麼？從 /opsx:explore 開始。 它是一個無風險的思考夥伴，會閱讀你的程式碼庫、權衡各種選項，並在任何產物或程式碼存在之前，將模糊的想法釐清為具體計畫。當方向明確時，它會交接給 /opsx:propose。這是與 AI 協作時最重要的習慣，否則 AI 會自信地建置錯誤的東西。請參閱探索指南。

運作方式 ​

OpenSpec 幫助你和 AI 程式碼助手在撰寫任何程式碼之前，先就建置內容達成共識。

預設快速路徑（核心配置）：

text
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
   (可選)

當你還在思考要做什麼時，從 /opsx:explore 開始；當你已經知道要什麼時，直接跳到 /opsx:propose。Explore 包含在預設配置中，因此隨時可用。

擴展路徑（自訂工作流程選擇）：

text
/opsx:new ──► /opsx:ff 或 /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

預設全域配置為 core，包含 propose、explore、apply、update、sync 和 archive。你可以使用 openspec config profile 啟用擴展工作流程指令，然後執行 openspec update。

OpenSpec 建立了什麼 ​

執行 openspec init 後，你的專案將具有以下結構：

openspec/
├── specs/              # 事實來源（你的系統行為）
│   └── <domain>/
│       └── spec.md
├── changes/            # 建議的更新（每個變更一個資料夾）
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # 差異規格（變更內容）
│           └── <domain>/
│               └── spec.md
└── config.yaml         # 專案設定（可選）

兩個關鍵目錄：

  • specs/ - 事實來源。這些規格描述了你的系統目前的行為。按領域組織（例如 specs/auth/、specs/payments/）。

  • changes/ - 建議的修改。每個變更都有自己獨立的資料夾，包含所有相關產物。當變更完成後，其規格會合併到主 specs/ 目錄中。

了解產物 ​

每個變更資料夾包含引導工作的產物：

產物用途
proposal.md「為什麼」和「什麼」- 記錄意圖、範圍和方法
specs/差異規格，顯示新增/修改/移除的需求
design.md「如何」- 技術方法和架構決策
tasks.md實作檢查清單（含核選框）

產物之間相互建構：

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            隨著學習持續更新

你可以隨時回頭完善早期的產物，隨著實作過程中獲得更多認識進行調整。

差異規格如何運作 ​

差異規格是 OpenSpec 的核心概念。它們顯示相對於目前規格的變更內容。

格式 ​

差異規格使用章節來標示變更類型：

markdown
# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented

## MODIFIED Requirements

### Requirement: Session Timeout
The system SHALL expire sessions after 30 minutes of inactivity.
(Previously: 60 minutes)

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated

## REMOVED Requirements

### Requirement: Remember Me
(Deprecated in favor of 2FA)

歸檔時會發生什麼 ​

當你歸檔一個變更時：

  1. ADDED 需求會被附加到主規格中
  2. MODIFIED 需求會取代現有版本
  3. REMOVED 需求會從主規格中刪除

變更資料夾會移至 openspec/changes/archive/ 作為稽核歷史記錄。

範例：你的第一個變更 ​

讓我們走一遍為應用程式新增深色模式的流程。

1. 啟動變更（預設） ​

text
You: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — 為什麼要做這件事，有什麼變更
     ✓ specs/       — 需求和情境
     ✓ design.md    — 技術方法
     ✓ tasks.md     — 實作檢查清單
     Ready for implementation!

如果你已啟用擴展工作流程配置，也可以分兩步完成：先 /opsx:new，再 /opsx:ff（或逐步使用 /opsx:continue）。

2. 建立了什麼 ​

proposal.md - 記錄意圖：

markdown
# Proposal: Add Dark Mode

## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage.

## Scope
- Add theme toggle in settings
- Support system preference detection
- Persist preference in localStorage

## Approach
Use CSS custom properties for theming with a React context
for state management.

specs/ui/spec.md - 顯示新需求的差異：

markdown
# Delta for UI

## ADDED Requirements

### Requirement: Theme Selection
The system SHALL allow users to choose between light and dark themes.

#### Scenario: Manual toggle
- GIVEN a user on any page
- WHEN the user clicks the theme toggle
- THEN the theme switches immediately
- AND the preference persists across sessions

#### Scenario: System preference
- GIVEN a user with no saved preference
- WHEN the application loads
- THEN the system's preferred color scheme is used

tasks.md - 實作檢查清單：

markdown
# Tasks

## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence

## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle

## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables

3. 實作 ​

You: /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Created ThemeContext with light/dark state
     ✓ 1.2 Added CSS custom properties to globals.css
     ✓ 1.3 Implemented localStorage persistence
     ✓ 2.1 Created ThemeToggle component
     ...
     All tasks complete!

在實作過程中，如果你發現設計需要調整，只需更新產物然後繼續即可。

4. 歸檔 ​

You: /opsx:archive

AI:  Archiving add-dark-mode...
     ✓ Merged specs into openspec/specs/ui/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
     Done! Ready for the next feature.

你的差異規格現在已成為主規格的一部分，記錄著你的系統如何運作。

驗證與審核 ​

使用 CLI 檢查你的變更：

bash
# List active changes
openspec list

# View change details
openspec show add-dark-mode

# Validate spec formatting
openspec validate add-dark-mode

# Interactive dashboard
openspec view

下一步 ​