OpenSpec 導入現有專案（Brownfield 指南）

將 OpenSpec Spec-Driven Development 框架整合至已存在專案的三個 Phase 流程：基礎架構建設、現有系統 Spec 回填、格式驗證，含 AI 輔助回填工作流程與 config.yaml 設定模板。

概述

OpenSpec 框架設計為 Brownfield-first，明確針對「已有程式碼的專案」而設計，不要求從零開始。這與需要先建立完整文件再開始開發的框架不同，OpenSpec 允許先導入框架、再逐步補充 spec。

導入的核心挑戰是「回填」（Backfill）：為現有每個模組撰寫 spec 文件，讓 OpenSpec 知道系統現狀。OpenSpec CLI 本身不具備自動掃描程式碼的能力，但可借助 AI 助手（Claude Code、Cursor 等）大幅加速這個過程。

本指南記錄從安裝到驗證的完整流程，以及在 M365 MCP Server 專案的實際導入經驗。

核心內容

OpenSpec CLI 的實際能力範圍

導入前必須釐清幾個常見誤解：

能力	是否支援
安裝 CLI 工具	✅ npm install -g @fission-ai/openspec@latest
初始化專案骨架	✅ openspec init
新增變更提案	✅ openspec new change
驗證 spec 格式	✅ openspec validate
自動掃描程式碼產生 spec	❌ 無 scan/generate/backfill 指令
自動偵測技術棧填入 config.yaml	❌ context 必須手動填寫
自動建立 spec 子目錄	❌ 需手動 mkdir

config.yaml 的角色

openspec init 只產生 config.yaml 的骨架（包含 schema、空的 context、預設 rules），context 區塊必須手動填寫。Context 是 OpenSpec 與 AI 助手的橋梁——執行 /opsx:propose 時，OpenSpec 將 context 注入 prompt，讓 AI 理解你的技術棧和慣例，產出更貼合專案的 artifacts。

實用技巧：把專案的 README、package.json/pyproject.toml 貼給 AI 助手，請它草擬 context 初稿，再由你審閱後貼入。

Spec 文件格式要求

OpenSpec 對 spec 格式有嚴格要求，違反會導致 openspec validate 失敗：

• ### Requirement: 必須用 3 個 #（不可少）
• #### Scenario: 必須用 4 個 #（不可少）
• 每個 Requirement 至少要有一個 Scenario
• Scenario 使用 WHEN/THEN 結構（不需要 GIVEN）
• 文件必須有 ## Purpose 和 ## Requirements 頂層區塊

使用 RFC 2119 關鍵字描述需求強度：SHALL/MUST（強制）、SHOULD（建議）。

AI 輔助回填流程（推薦）

OpenSpec CLI 不能自動掃描，最有效率的回填方式是借助 AI 助手：

1. 用 /opsx:explore 讓 AI 掃描專案結構，產出模組清單與建議的 spec 目錄名稱
2. 一次性建立所有目錄
3. 逐模組請 AI 讀取源碼，產出符合格式的 spec 初稿
4. 人工審閱確認每份 spec（AI 可能遺漏邊界條件或誤解業務邏輯）
5. openspec validate --all 驗證格式

實務數據：一個模組從源碼到定稿 spec 約 10-15 分鐘（AI 產初稿 2 分鐘 + 人工審閱 8-13 分鐘）。

回填的優先順序

不需要一次回填所有模組，建議按優先級分批：

1. 第一批（必要）：核心業務邏輯、API 介面、認證機制
2. 第二批（重要）：配置管理、資料模型、錯誤處理
3. 第三批（按需）：部署、CI/CD、監控、日誌

關鍵要點

• OpenSpec CLI 不能自動掃描程式碼，回填需靠人工或 AI 助手
• config.yaml 的 context 是 AI 理解專案的關鍵，必須手動填寫
• Spec 格式對 # 層級很嚴格，### Requirement: 和 #### Scenario: 的層級不可錯
• 建議將 openspec validate --all 加入 CI pipeline 確保格式持續正確
• openspec/ 和 .claude/（或其他 AI 工具目錄）都應納入 Git 版本控制

實際應用

M365 MCP Server 專案採用此流程完成回填：使用 /opsx:explore 盤點出 system-overview、auth-oauth、tool-send-mail、token-caching 等模組，逐一讓 AI 產出初稿後人工審閱。整個回填過程每個模組平均不超過 15 分鐘。

導入完成後，每次功能開發都透過 /opsx:propose 產出四份 artifacts（proposal → delta specs → design → tasks），再用 /opsx:apply 執行，完成後 /opsx:archive 歸檔。若搭配 GitHub Copilot Sub-Agent 進行更大規模的 AI 編排開發，可參考 GitHub Copilot Sub-Agent 編排。

部署設定參考

Phase 1：基礎架構建設

# 前置條件：Node.js >= 20.19.0
node --version
npm --version

# 安裝 CLI
npm install -g @fission-ai/openspec@latest
openspec --version

# 在專案目錄初始化
cd /your/project
openspec init --tools claude --profile core --force

初始化後的目錄結構：

openspec/
├── config.yaml           # 骨架，需手動填寫 context
├── specs/                # 空目錄，等待 spec 回填
├── changes/              # 變更提案目錄
└── changes/archive/      # 已完成變更歸檔
.claude/commands/opsx/    # Claude Code slash commands
.claude/skills/openspec-* # Claude Code skills

config.yaml 模板

schema: spec-driven

# ⚠️ context 必須手動填寫，OpenSpec 不會自動偵測技術棧
context: |
  Project: <你的專案名稱>
  Purpose: <一句話描述專案用途>
  Tech stack: <語言, 框架, 資料庫, 佇列等>
  Auth: <認證機制>
  Infrastructure: <部署方式>
  Testing: <測試框架>
  Conventions:
    - <慣例 1，例如 async-first>
    - <慣例 2，例如 conventional commits>
  Domain: <業務領域>

rules:
  proposal:
    - Keep proposals under 500 words
    - Always include a "Non-goals" section
    - Reference affected spec IDs explicitly
  specs:
    - Use RFC 2119 keywords (SHALL, MUST, SHOULD) for requirement strength
    - Each requirement must have at least one testable scenario
    - Focus on observable behavior, not implementation details
  tasks:
    - Break tasks into chunks completable in under 30 minutes
    - Include verification step for each task

Phase 2：AI 輔助 Spec 回填

# 步驟 1：讓 AI 盤點模組
# /opsx:explore "請盤點這個專案的所有模組，列出每個模組的職責、主要檔案路徑
#               和建議的 spec 目錄名稱"

# 步驟 2：一次性建立所有目錄
mkdir -p openspec/specs/{system-overview,auth,api-endpoints,database,deployment}

# 步驟 3：逐模組請 AI 產出初稿
# "請讀取 src/auth/*.py 為 auth 模組撰寫 spec.md 初稿，
#  遵循 OpenSpec 的 Purpose + Requirements + Scenarios 格式"

# 步驟 4：人工審閱各份 spec

# 步驟 5：驗證格式
openspec validate --all

Spec 文件格式

## Purpose

描述模組職責（1-2 段）。

## Requirements

### Requirement: <需求名稱>

系統 SHALL <行為描述>。

#### Scenario: <場景名稱>

- WHEN <觸發條件>
- THEN <預期結果>
- AND <額外結果（可選）>

範例（認證模組）：

## Purpose

定義使用者認證流程，包含登入、Token 產生和 Session 管理。

## Requirements

### Requirement: 使用者登入驗證

系統 SHALL 驗證使用者的帳號密碼組合，並在驗證成功後發放 JWT Token。

#### Scenario: 帳號密碼正確

- WHEN 使用者提交正確的 email 和 password
- THEN 系統回傳 HTTP 200 和 JWT access token
- AND token 的有效期為 1 小時

#### Scenario: 密碼錯誤

- WHEN 使用者提交正確的 email 但錯誤的 password
- THEN 系統回傳 HTTP 401 Unauthorized
- AND 不洩漏「帳號是否存在」的資訊

Phase 3：驗證

openspec validate --all               # 驗證所有 specs
openspec validate auth                # 驗證單一 spec
openspec validate --all --json        # CI 用 JSON 格式輸出

常見驗證失敗原因：

• Requirement 或 Scenario 的 # 層級錯誤
• 某個 Requirement 沒有任何 Scenario
• 文件缺少 ## Purpose 或 ## Requirements 頂層區塊

日常工作流程指令

指令	階段	說明
/opsx:explore	探索	調查 codebase，無 artifact 產出
/opsx:propose	規劃	一步產出 proposal + specs + design + tasks
/opsx:apply	實作	依 tasks 逐步執行
/opsx:verify	驗證	全局驗證實作 vs. spec（Expanded profile）
/opsx:archive	歸檔	delta specs 合併回 spec library

相關概念

• OpenSpec SDD 框架 — OpenSpec 核心概念：propose→apply→verify→archive 工作流、四個 artifact、與 Claude Code Superpowers 整合
• GitHub Copilot Sub-Agent 編排 — 以 Coordinator/Worker 模式搭配 OpenSpec 進行更大規模的 AI 輔助開發
• M365 MCP Server（Kubernetes 部署） — 實際採用 OpenSpec 回填流程的專案案例
• Superpowers AI 開發方法論 — OpenSpec 的互補框架；整合工作流中 Brownfield onboard 完成後，可銜接 Superpowers 的嚴謹任務計畫與執行

來源

• 原始素材：2026-04-11 OpenSpec 導入指南 — 將規格驅動開發框架整合至現有專案
• OpenSpec 官方文件