Files
Obsidian/CSDN等国内/OpenSpec 團隊導入實戰指南:從安裝到第一個 PR 的完整教學.md
T
coco 8b94d76799 a
2026-07-21 13:57:15 +08:00

523 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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 <change> --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 <change>` |
## 常用 CLI 指令速查表
| 指令 | 用途 | 常用參數 |
| --- | --- | --- |
| `openspec init` | 初始化專案 | `--tools claude,cursor` |
| `openspec list` | 列出所有 changes | `--specs` (列出 specs) |
| `openspec show <change>` | 顯示特定 change 內容 | `--json` |
| `openspec view` | 互動式 dashboard | — |
| `openspec validate <change>` | 驗證特定 change | `--strict` 、 `--json` |
| `openspec validate --all` | 驗證所有 changes | `--strict` 、 `--json` |
| `openspec status` | 顯示 OpenSpec 狀態 | — |
| `openspec archive <change>` | 封存變更 | — |
| `openspec config profile` | 切換 workflow profile | — |
| `openspec update` | 更新工具整合 | — |
| `openspec schemas --export` | 匯出 schema 到專案 | — |
| `openspec templates` | 管理模板 | — |
## OPSX Slash Commands 速查表
這些指令在你的 AI 工具對話框中使用:
| 指令 | 用途 | Profile |
| --- | --- | --- |
| `/opsx:propose <name>` | 一鍵建立 change + 產生所有 artifacts | core |
| `/opsx:apply` | 按 tasks 實作 | core |
| `/opsx:archive` | 合併 + 封存 | core |
| `/opsx:new <name>` | 建立新的 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 的「部分採用」策略是對的
先從最小的改變開始,讓團隊嘗到甜頭,習慣自然就來了
---