OpenSpec 目錄結構

搞懂資料夾，開發不混亂

在導入 OpenSpec 的專案中，你通常會在專案根目錄下看到三個以 openspec 或相關工具命名的資料夾：openspec/、.omx/、以及 .opencode/。

對於剛接觸的人來說，這些資料夾很容易讓人混淆。本章將為你詳細解析這三個資料夾的作用、它們的分工與協作，以及最重要的——哪些應該進入 Git 版本控制，哪些應該被忽略。

1. 核心規格目錄：openspec/

openspec/ 是整個規格驅動開發的靈魂，它是專案的核心規格儲存庫，也是系統事實的唯一來源 (Source of Truth)。

目錄結構

openspec/
├── config.yaml       ← 專案規格管理設定檔
├── specs/            ← 系統目前的「能力規格書 (Capability Specs)」
│   ├── site-foundation/
│   │   └── spec.md
│   └── code-experience/
│       └── spec.md
└── changes/          ← 進行中的變更計畫（歸檔後會被清理）
    └── add-dark-mode/
        ├── proposal.md
        ├── tasks.md
        └── specs/

Git 版本控制規範：【必須上傳】

openspec/ 底下的所有內容（除了本機的臨時備份外）都必須納入 Git 版本控制，上傳到遠端儲存庫。

• 規格跟程式碼放在同一個 repo，能確保「程式碼修改到哪，規格就更新到哪」。
• 任何人 clone 專案後，都能立刻在 openspec/specs/ 中讀到最新的系統規格，不需要到外部的 wiki 或 Notion 尋找。
• 當你發送 Pull Request (PR) 時，審查者可以透過查看 openspec/ 底下的 markdown 變更，一目了然地知道這次變更影響了哪些系統規格。

2. 工具狀態目錄：.omx/

.omx/ 是本地 Ralph 引擎（一個自動化規劃與驗證引擎）在進行目標驅動迭代（Goal-driven Iteration）時所產生的工作目錄。

目錄結構與用途

.omx/
├── plans/
│   └── prd-add-dark-mode.md         ← 當前執行中的產品需求文件 (PRD)
├── state/
│   └── add-dark-mode/
│       └── ralph-progress.json      ← 記錄每條驗收標準是否通過的進度帳本
└── prd.json                         ← 供機器讀取的故事狀態檔案

• PRD (產品需求文件)：描述當前實作任務的最高綱領，是 Ralph 判斷「是否做完」的依據。
• 進度帳本 (Progress Ledger)：記錄各個驗收條件的進度，讓 AI 在重試或重啟對話時能接續先前的進度，避免重頭來過。

Git 版本控制規範：【禁止上傳 (略過)】

.omx/ 目錄純屬本地端執行工具時的臨時快取與進度紀錄，不應上傳至 Git。必須將其加入 .gitignore 中。這是因為：

• 每個開發者在本機執行的 Ralph 進度與狀態可能不同，上傳會導致衝突。
• PRD 與 progress 檔案僅在實作期間有意義，一旦變更完成歸檔，這些臨時檔案就失去了價值。

3. AI 技能與指令目錄：.opencode/

.opencode/ 是 Agent 協作平台（如 Antigravity）在本地執行時，所需要的指令配置與專屬技能（Skills）檔案夾。

目錄結構與用途

.opencode/
├── commands/
│   ├── opsx-propose.md     ← 定義 /opsx:propose 的工作步驟與提示詞
│   └── opsx-apply.md       ← 定義 /opsx:apply 的工作步驟
└── skills/
    └── openspec-apply-change/
        └── SKILL.md        ← 讓 AI 學習如何解析 tasks.md 並進行程式碼修改

• 這裡面的 Markdown 檔案本質上是給 AI 閱讀的指令手冊與提示模板。當你在聊天室輸入 /opsx:apply 時，AI 就會去讀取 .opencode/commands/opsx-apply.md，以此了解它需要跑哪些 git 命令、怎麼改 code。

Git 版本控制規範：【禁止上傳 (略過)】

.opencode/ 是 AI 運行的本地端依賴，不應納入專案的原始碼控制中。同樣必須在 .gitignore 中將其忽略。

• 這些是本地開發環境的「腳本與技能」，跟網站產品的商務邏輯無關。
• 保持 Git repo 的純粹性，只保留產品程式碼、規格、以及基本的專案設定檔。

三大目錄分工表

小結

搞懂這三個目錄後，你的專案就不會充斥著各種工具產生的雜亂檔案。記住最簡單的原則：產品核心的規格 (openspec/) 上傳；工具與 AI 產生的狀態與設定 (.omx/, .opencode/) 忽略。

基礎觀念的學習到此告一段落！在下一章中，我們將開始逐一探討 OpenSpec v1.6.0 的 [12 個核心指令]，看看如何具體使用它們來操控變更計畫。