--- title: "OpenSpec 團隊導入實戰指南:從安裝到第一個 PR 的完整教學" source: "https://xn--uy0a.tw/AI/openspec-team-adoption-practical-guide/" author: - "[[Jim Chen]]" published: 2026-02-26 created: 2026-03-13 description: "AI 是不知疲倦的工作者,它們為了我的輕鬆而努力。" tags: - "clippings" --- ![OpenSpec 團隊導入實戰指南:從安裝到第一個 PR 的完整教學](https://xn--uy0a.tw/processed_images/preview.c9123b5421bc0766.webp) Made with Nano Banana 2 by Gemini 3.1 Pro 琳 上一篇寫得不錯 不過我們同事看完可能會問:「所以我到底要怎麼開始用?」 悠奈 了解了 這篇就是那個「所以我到底要怎麼開始用」的完整答案 從 `npm install` 到第一個 PR 被 merge,一步都不跳 前篇分析了 OpenSpec 是什麼、為什麼值得關注。這篇的目標完全不同: **讓你的團隊能在今天就開始用。** 每一個步驟都附上可以直接複製貼上的指令。不需要先理解整個框架的哲學,照著做就行。哲學的部分,前篇已經說完了。 ## 準備工作:安裝 OpenSpec CLI ### 確認 Node.js 版本 OpenSpec 要求 Node.js **20.19.0 以上** 。先確認你的版本: ```shellscript node --version # 需要 v20.19.0 或更高 ``` 如果版本不夠,用你慣用的版本管理器升級: ```shellscript # nvm nvm install 20 nvm use 20 # fnm fnm install 20 fnm use 20 ``` ### 安裝 CLI ```shellscript # npm(最常見) npm install -g @fission-ai/openspec@latest # pnpm pnpm add -g @fission-ai/openspec@latest # yarn yarn global add @fission-ai/openspec@latest # bun bun add -g @fission-ai/openspec@latest ``` 安裝完成後驗證: ```shellscript openspec --version # 應顯示 1.2.0 或更高 ``` ## 路徑 A:Greenfield 新專案 如果你的專案是全新開始,恭喜,這是最簡單的路。 ### 第一步:初始化 在你的專案根目錄執行: ```shellscript cd your-project openspec init ``` 這會啟動互動式設定。它會問你使用哪些 AI 工具(Claude、Cursor、GitHub Copilot 等),然後自動生成對應的 skill/command 檔案。 如果不想跑互動式,可以直接指定: ```shellscript # 只用 Claude 和 Cursor openspec init --tools claude,cursor # 不整合任何工具(純 CLI 使用) openspec init --tools none ``` 初始化後你的 repo 會多出這些東西: ```plain your-project/ └── openspec/ ├── specs/ # 空的,等你填入系統行為規格 ├── changes/ # 空的,等你建立第一個變更 └── config.yaml # 專案級設定(可能是空的) ``` ### 第二步:建立你的第一個變更 在你的 AI 工具對話框中輸入: ```plain /opsx:propose add-user-authentication ``` 或者如果你想更細粒度地控制(expanded workflow): ```plain /opsx:new add-user-authentication ``` 這會建立 `openspec/changes/add-user-authentication/` 資料夾,裡面包含: | 檔案 | 用途 | 你需要做的 | | --- | --- | --- | | `proposal.md` | 描述 Why 和 What | 審查並修改 | | `design.md` | 描述 How(SDD 文件) | 審查並修改 | | `tasks.md` | 實作清單 | 審查並修改 | | `specs/` | Delta specs | 審查格式 | ### 第三步:人工校準 **這步是關鍵。** AI 產生的 artifacts 是起點,不是終點。 打開 `proposal.md` ,確認: - 目標是否正確 - 範圍是否合理 - 非目標(Non-Goals)是否有列出 打開 `design.md` ,確認: - 技術方案是否合理 - 有沒有列出替代方案和為什麼選這個 - 風險和緩解措施是否考慮周全 打開 `specs/` 裡的 delta spec,確認: - Requirement 是否用了 SHALL/MUST 等 RFC 2119 關鍵字 - 每個 Requirement 至少有一個 Scenario - Scenario 的 When/Then 是否足夠具體到可以寫測試 ### 第四步:驗證 ```shellscript openspec validate add-user-authentication --strict ``` 如果有格式問題(比如缺少某個必要段落),它會告訴你。修正後再驗: ```shellscript # 看 JSON 格式的詳細結果 openspec validate add-user-authentication --strict --json ``` ### 第五步:實作 在 AI 對話框中: ```plain /opsx:apply ``` AI 會按照 `tasks.md` 裡的清單逐一實作。 ### 第六步:封存 實作完成、PR 被 merge 後: ```plain /opsx:archive ``` 這會把 delta specs 合併回 `openspec/specs/` (主規格),並把 change 資料夾移到 `openspec/changes/archive/YYYY-MM-DD-add-user-authentication/` 。 ## 路徑 B:Brownfield 既有專案 **這是大多數人的真實情況。** 你有一個已經跑了好幾年的專案,上百個檔案,沒有任何 spec。 ### 核心原則:不要回頭補 spec 我要先打破一個常見的迷思: 你不需要先把既有系統的所有行為都寫成 spec 才能開始用 OpenSpec。 OpenSpec 設計成 brownfield-first。它的 `openspec/specs/` 是逐步累積的,不是一次寫完的。正確的做法是: 1. **從下一個變更開始** :不補舊的 spec 2. **每做一次變更,就累積一點 spec** :delta specs archive 後會自動合併到主 specs 3. **幾個月後,spec 自然覆蓋了大部分活躍模組** :因為你改過的地方都有 spec 了 ### 第一步:初始化(跟 greenfield 一樣) ```shellscript cd your-existing-project openspec init ``` 此時 `openspec/specs/` 是空的。這沒問題。 ### 第二步:挑一個即將進行的變更 選一個中等複雜度的任務,不要太簡單(修 typo 不需要 spec),也不要太複雜(第一次用就挑跨服務重構容易勸退團隊)。 ```plain /opsx:propose improve-search-performance ``` ### 第三步:寫 Delta Specs 時的注意事項 因為你的 `openspec/specs/` 是空的,delta spec 除了「要改的」行為,還需要涵蓋「目前系統的實際狀態」。 實務上的寫法: ```markdown ## ADDED Requirements ### Requirement: 搜尋回應時間 系統 SHALL 在 P99 latency 低於 500ms 的條件下回傳搜尋結果。 #### Scenario: 一般查詢效能 - **WHEN** 使用者以少於 3 個關鍵字搜尋 - **THEN** 回應時間 P99 低於 500ms ## MODIFIED Requirements ### Requirement: 搜尋結果排序 系統 MUST 依據相關性分數由高至低排序搜尋結果。 (原先:依建立時間排序) #### Scenario: 相關性排序 - **WHEN** 搜尋 "openspec tutorial" - **THEN** 標題包含完整關鍵字的結果排在前面 ``` ### 第四步:Archive 後觀察 第一次 archive 之後, `openspec/specs/` 裡就會出現你剛才描述過行為的 spec 檔案。下次有人改到同一個模組,他就能從既有的 spec 出發寫 delta,而非從零開始。 這就是 brownfield 導入的魔法:每次變更都在幫未來的自己累積知識。 ### Brownfield 常見踩坑 **踩坑 1:Archive 可能破壞 Git History** 前篇提過,archive 操作用「刪除再新建」取代 `git mv` ,可能導致 git history 斷裂。在重視追溯性的團隊,導入時建議: - 先在一個測試分支上跑一次完整的 propose → archive 流程 - 檢查 `git log --follow openspec/specs/` 是否能追到 archive 前的歷史 - 如果追不到,把「archive 後 spec 的 git history」列為已知限制,用 `openspec/changes/archive/` 裡的完整上下文做補償 **踩坑 2:RFC 2119 關鍵字與中文 Spec** 如果你的團隊用中文寫 spec, `openspec validate --strict` 可能因為找不到 SHALL/MUST 等英文關鍵字而報 warning。兩種處理方式: 1. **混合寫法** :中文描述 + 英文關鍵字,例如「系統 SHALL 在使用者登入後顯示首頁」 2. **不用 `--strict`** :改用 `openspec validate` (不加 strict),讓關鍵字檢查變成 warning 而非 error 建議採用方式 1。RFC 2119 關鍵字的精確性確實有價值,混合寫法在一兩篇之後就會習慣。 **踩坑 3:團隊成員的學習曲線** 不是每個人都能馬上適應「先寫 spec 再寫 code」的流程。建議: - 先由 1-2 個人跑通整個流程,產出第一個成功案例 - 把這個案例當作 PR 給全團隊看,讓他們理解 artifacts 長什麼樣 - 準備一份 FAQ(本文後面會提供) ## 團隊共識注入:config.yaml `openspec/config.yaml` 讓你把團隊的工程共識「寫進去」,而非口頭傳達;每次 AI 產生 artifacts 時,都會自動讀取這份設定。 ### 最小可用的 config.yaml ```yaml # openspec/config.yaml context: | 這是一個使用 TypeScript + Node.js 的後端 API 服務。 主要框架:Express.js 資料庫:PostgreSQL + Prisma ORM 測試框架:Vitest 部署環境:Kubernetes on AWS rules: - 所有 API endpoint 必須有對應的 OpenAPI schema - 所有資料庫變更必須有 migration script - 新功能必須有至少 80% 的測試覆蓋率 - commit message 遵循 Conventional Commits 格式 - 回滾策略必須在 design.md 中明確描述 ``` ### 進階設定:自訂 Schema 如果你的團隊有額外的 artifacts 需求(比如必須產出 API 契約或安全審查文件),可以 fork 內建 schema: ```shellscript # 把內建 schema 複製到專案內 openspec schemas --export ``` 這會在 `openspec/schemas/` 建立一份可編輯的 schema 副本。你可以: - 新增 artifact 類型(例如 `security-review.md` ) - 修改依賴關係(例如要求 security review 必須在 tasks 之前完成) - 調整模板內容 修改後記得把這份 schema 納入 version control,這是你團隊工作流的正式定義。 ## CI/CD 整合 ### GitHub Actions 以下是可以直接複製到你 repo 的 workflow 檔案: ```yaml # .github/workflows/openspec-validate.yml name: OpenSpec Validate on: pull_request: paths: - "openspec/**" jobs: validate: runs-on: ubuntu-latest env: OPENSPEC_TELEMETRY: "0" DO_NOT_TRACK: "1" steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: "20" - name: Install OpenSpec run: npm install -g @fission-ai/openspec@latest - name: Validate all changes run: openspec validate --all --strict --json ``` ### 其他 CI 系統 核心邏輯都一樣,只是語法不同: ```shellscript # GitLab CI / Jenkins / 其他 npm install -g @fission-ai/openspec@latest OPENSPEC_TELEMETRY=0 DO_NOT_TRACK=1 openspec validate --all --strict --json ``` `--json` 輸出讓你可以用腳本解析驗證結果,做更細緻的判斷(例如只在 error 時 fail,warning 放行)。 ## Code Review Checklist 把這份 checklist 加到你的 PR template 或 review 流程裡: | 項目 | 判斷標準 | 檢查方式 | | --- | --- | --- | | 變更資料夾是否完整 | proposal.md、specs/、tasks.md 都存在 | `openspec validate --strict` | | Delta specs 格式 | ADDED/MODIFIED/REMOVED 區段正確 | `openspec validate` + 人工 | | Requirements 精確性 | 使用 SHALL/MUST 等 RFC 2119 關鍵字 | `openspec validate --strict` | | Scenarios 可測試性 | 每個 Requirement 至少 1 個 Scenario | `openspec validate --strict` | | SDD 決策與風險 | design.md 列出 decisions 和 risks | 人工審查 | | 跟既有 spec 的一致性 | delta 不跟 source-of-truth 矛盾 | 人工 + `openspec show ` | ## 常用 CLI 指令速查表 | 指令 | 用途 | 常用參數 | | --- | --- | --- | | `openspec init` | 初始化專案 | `--tools claude,cursor` | | `openspec list` | 列出所有 changes | `--specs` (列出 specs) | | `openspec show ` | 顯示特定 change 內容 | `--json` | | `openspec view` | 互動式 dashboard | — | | `openspec validate ` | 驗證特定 change | `--strict` 、 `--json` | | `openspec validate --all` | 驗證所有 changes | `--strict` 、 `--json` | | `openspec status` | 顯示 OpenSpec 狀態 | — | | `openspec archive ` | 封存變更 | — | | `openspec config profile` | 切換 workflow profile | — | | `openspec update` | 更新工具整合 | — | | `openspec schemas --export` | 匯出 schema 到專案 | — | | `openspec templates` | 管理模板 | — | ## OPSX Slash Commands 速查表 這些指令在你的 AI 工具對話框中使用: | 指令 | 用途 | Profile | | --- | --- | --- | | `/opsx:propose ` | 一鍵建立 change + 產生所有 artifacts | core | | `/opsx:apply` | 按 tasks 實作 | core | | `/opsx:archive` | 合併 + 封存 | core | | `/opsx:new ` | 建立新的 change(不自動產生) | expanded | | `/opsx:continue` | 繼續產生/補完 artifacts | expanded | | `/opsx:ff` | Fast-forward:跳過已完成的步驟 | expanded | | `/opsx:verify` | 品質檢查(completeness/correctness) | expanded | | `/opsx:sync` | 同步 delta specs 到主 specs | expanded | ## 團隊導入時間表 以下是基於研究報告估算的導入節奏,以「兩週內可啟動」為目標: ### 第 1 天:環境準備 - 全員安裝 OpenSpec CLI - 確認 Node.js 版本 ≥ 20.19.0 - 企業內網的話,設定 `OPENSPEC_TELEMETRY=0` ### 第 2-3 天:PoC - 選一個中等複雜度的變更 - 由 1-2 個人跑通 propose → validate → apply → archive - 把 PR 給全團隊看,收集回饋 ### 第 4-5 天:團隊規範 - 撰寫 `openspec/config.yaml` - 決定 RFC 2119 關鍵字的使用方式(純英文 or 中英混合) - 建立 code review checklist ### 第 6-7 天:CI 整合 - 加入 `openspec validate --all --strict --json` 到 CI - 設定 telemetry opt-out 環境變數 - 確認 validate 在 PR 流程中正常運作 ### 第 8-10 天:全員啟動 - 全員跑第一個自己的 change - 安排一次 15 分鐘的 Q&A - 開始收集「常見問題」建立內部 FAQ ## FAQ:你的同事可能會問的問題 **Q:每個小修改都要走這套流程嗎?** 不用。修 typo、改 CSS 顏色、更新依賴版本這類不影響系統行為的變更,不需要走 OpenSpec 流程。 規則是:如果變更會影響對外可觀察的行為,就走 OpenSpec;如果不會,直接提 PR。 **Q:我可以先寫 code 再補 spec 嗎?** 技術上可以,但不建議。OpenSpec 的核心價値在於「先對齊再實作」。如果你先寫了 code,那 spec 就變成「記錄你做了什麼」而不是「定義你要做什麼」,兩者實質效益差距很大。 但如果是探索性的原型,可以先寫 code 驗證可行性,然後再用 spec 定義最終行為。前篇提到的「依任務複雜度調整力道」在這裡完全適用。 **Q:OpenSpec 會取代我們的 OpenAPI / AsyncAPI 嗎?** 不會。前篇已經詳細比較過。它們解決的問題在不同層面。OpenAPI/AsyncAPI 描述系統的外部介面契約,OpenSpec 描述系統的行為變更流程。兩者共存是最佳實踐。 **Q:Spec 寫了之後要怎麼維護?** `openspec/specs/` 會隨著每次 archive 自動更新。只要你的團隊持續用 OpenSpec 流程做變更,spec 就會自動保持最新。不需要額外的「spec 維護時間」。 **Q:如果 validate 通過了但實作其實不符合 spec 怎麼辦?** `openspec validate` 只檢查 spec 本身的格式和結構,不檢查程式碼是否符合 spec。「實作是否對齊規格」需要靠 `/opsx:verify` (agent 層級的檢查)和人工 code review 來把關。Scenario 的 When/Then 可以轉化成測試案例,但具體生成與執行仍是人或 AI coding assistant 的工作。 ## 範例:一個完整的變更流程 把前面所有步驟串起來,這是一個從頭到尾的實際流程: ```shellscript # 1. 確認 OpenSpec 狀態 openspec status # 2. 在 AI 工具對話框中建立變更 # /opsx:propose add-email-notification # 3. 審查 AI 產生的 artifacts # 打開 openspec/changes/add-email-notification/ 裡的所有檔案 # 修正不合理的地方 # 4. 驗證 openspec validate add-email-notification --strict # 5. 在 AI 工具對話框中實作 # /opsx:apply # 6. 提 PR,用 checklist 做 review git add -A git commit -m "feat: add email notification (OpenSpec-guided)" git push origin feature/add-email-notification # 開 PR,附上 openspec/changes/add-email-notification/ 的內容摘要 # 7. PR merge 後封存 # /opsx:archive ``` 整個流程中,OpenSpec 的 artifacts(proposal、specs、design、tasks)就是你 PR 的「設計文件」。Reviewer 先看 spec 確認方向對不對,再看 code 確認實作對不對。這比直接看 2000 行 diff 高效得多。 悠奈 寫完這篇的感覺是 OpenSpec 最難的不是工具本身,而是改變團隊的習慣 「先寫 spec 再寫 code」聽起來簡單,但真正做到需要的是紀律 工具只是讓紀律的成本變低而已 琳 關鍵不是 tool,是 culture 悠奈 沒錯 不過呢,好的工具能降低建立好文化的門檻 這也是為什麼我覺得 OpenSpec 的「部分採用」策略是對的 先從最小的改變開始,讓團隊嘗到甜頭,習慣自然就來了 ---