基礎觀念

安裝與初始化

如何在既有專案中安裝 OpenSpec 工具並初始化規格目錄

踏出第一步

在理解了核心觀念之後，本章將指引你如何在自己現有的專案中安裝 OpenSpec 工具，並建立規格管理所需要的基本目錄結構。

1. 工具的安裝

OpenSpec 本身是一套無後端、輕量級的規格描述規範。在實務上，我們會搭配 OpenCode 以及相關的 AI 編碼助手（Agentic AI Coding Assistant）一起運作。

如果你是在一個具備 Node.js 環境的 JavaScript/TypeScript 專案中，你可以透過 pnpm 或 npm 下載並使用 CLI 工具（Command Line Interface）。

# 全域安裝 OpenSpec CLI（非必要，亦可透過 npx 執行）
npm install -g @openspec/cli

然而，在許多 AI 協作的場景中，你甚至不需要安裝額外的執行檔，因為 AI 助手本身就會讀取 .opencode/ 或是 .omx/ 目錄下的技能設定，並自動對應相關指令。在這種情況下，你只需要在專案根目錄下完成「規格初始化」即可。

2. 專案初始化：openspec init

要在專案中啟用 OpenSpec，請在終端機中切換至專案根目錄，並執行以下初始化指令：

openspec init

這個指令會自動在你的專案根目錄下建立 openspec 資料夾，並包含以下結構：

your-project/
├── openspec/
│   ├── specs/          ← 放各功能「現況規格」的目錄
│   ├── changes/        ← 放「進行中變更」的目錄
│   └── config.yaml     ← 規格管理的設定檔

3. 設定檔剖析：config.yaml

在 openspec/config.yaml 中，記錄了 OpenSpec 對此專案的運作規則。一個典型且基本的設定檔內容如下：

# openspec/config.yaml
changesDir: openspec/changes
specsDir: openspec/specs
defaultSchema: spec-driven

這個檔案通常包含以下幾個關鍵欄位：

  • changesDir (變更計畫目錄)：告訴工具進行中的變更計畫（Changes）應該放在哪裡。預設為 openspec/changes。
  • specsDir (現況規格目錄)：告訴工具系統目前最新的規格說明書（Specs）存在哪裡。預設為 openspec/specs。
  • defaultSchema (預設工作流模式)：定義專案採用的規格管理架構。最常見且推薦的是 spec-driven (規格驅動模式)；另外也有基於測試或文檔的其他模式。

4. 第一個現況規格

初始化完畢後，你的 openspec/specs/ 目錄是空的。你可以手動建立第一個現況規格，或是透過 /opsx:onboard 讓 AI 自動梳理專案現況。

如果你想手動建立第一個規格書，請在 openspec/specs/ 下建立以能力（Capability）命名的子目錄，並在內部放置 spec.md。例如：

openspec/specs/user-authentication/spec.md：

## ADDED Requirements

### Requirement: User password login
The system SHALL verify user credentials against the database on submit.

#### Scenario: Login success
- **WHEN** a user enters correct username and password and clicks submit
- **THEN** the system SHALL generate a session cookie and redirect to the dashboard

這就是一個最簡單的規格起步。每當你新增這個檔案，代表你的系統「已經具備」這項能力。

5. 使用 /opsx:onboard 導入既有專案

如果你要在一套已經寫了數千行程式碼的既有專案（Legacy Project）中導入 OpenSpec，手動撰寫所有規格書會是一大挑戰。此時你可以使用以下指令：

/opsx:onboard

這是一個專門用於「專案現況梳理」的 Experimental 指令。當你調用此指令時，AI 會掃描你目前的專案結構（包含程式碼與既有文件），自動在 openspec/specs/ 下建立對應的 Capability 資料夾與 spec.md 檔案，為你完成開箱即用的「現況規格書」。

總結

  1. 透過 openspec init 在專案中一鍵初始化。
  2. 專案的運作規範記錄在 openspec/config.yaml 中。
  3. 對於全新專案，你可以從空白的 openspec/specs/ 開始；對於既有專案，建議調用 /opsx:onboard 來自動產生初始規格。

在專案完成初始化並有了最初的規格後，我們就可以開始建立第一個變更計畫。下一章 [你的第一個 Change] 將會帶你實際操作如何新增功能。