ClaudeCode 與 OpenSpec 實現AI規範驅動開發
整理版優先睇
OpenSpec結合Claude Code，透過提案→規範→設計→任務流程，實現AI規範驅動開發，確保需求與代碼高度一致。
呢篇文章介紹OpenSpec呢個規範驅動開發（SDD）工具，佢嘅核心係解決AI編程時經常偏離預期嘅問題。作者認為，先對齊需求再寫Code，可以大幅減少出錯機會，提升開發效率。
OpenSpec提倡「先對齊，再編碼」，透過結構化文檔（Proposal → Spec → Design → Tasks）確保人與AI達成共識。佢仲引入「變更即代碼」概念，將每次變更當做獨立可版本化嘅單元，方便追蹤同驗證。另外，OpenSpec強調「流動而非僵化」，唔強制階段門控，支持迭代開發；「增量規範」只記錄新增修改內容，減少上下文負擔；「棕地優先」專為現有項目設計，無需重構即可引入。
總括嚟講，OpenSpec輕量無侵入，兼容Copilot、Cursor、Claude等主流AI工具，尤其適合需要精準控制AI輸出嘅開發團隊。透過呢套工作流，開發者可以更有效率咁管理AI生成嘅代碼，提升項目質量同可維護性。
- 結論：OpenSpec提供一套結構化流程，確保AI編碼前與人類需求對齊，避免自由發揮導致嘅偏差。
- 方法：使用 /openspec:proposal 創建提案，/openspec:apply 按任務清單實施代碼，/openspec:archive 歸檔完成變更。
- 差異：相比傳統 AI 編程，OpenSpec 強調「先對齊再編碼」同「變更即代碼」，將每次變更視為可版本化單元。
- 啟發：規範驅動開發（SDD）可以提升 AI 執行精度，尤其適用於複雜業務邏輯同多步驟開發。
- 可行動點：立即喺項目根目錄執行 openspec init 初始化，然後用斜槓命令開始提案驅動開發。
OpenSpec初始化命令
執行 openspec init 生成項目規範目錄結構，包括 openspec/ 和 .claude/ 文件夾。
OpenSpec規範驅動開發工作流
1. 提案 (/openspec:proposal) -> 2. 審查提案文件 -> 3. 實施 (/openspec:apply) -> 4. 歸檔 (/openspec:archive)。
需求提案輸入方式
可以直接用自然語言描述，或者先寫 requirements.md 再讓 AI 讀取；亦可交互式修正提案。
OpenSpec 嘅核心理念
OpenSpec 嘅核心係規範驅動開發（Spec-Driven Development, SDD），意思係喺寫任何 Code 之前，先同 AI 傾清楚「要做啲乜」，形成清晰可追溯嘅共識。咁樣就可以避免 AI 自由發揮搞到 Code 偏離預期。
先對齊，再編碼：透過結構化文檔（Proposal → Spec → Design → Tasks）確保需求、設計同實現高度一致。
除咗「先對齊」，OpenSpec 仲有幾個核心概念：變更即代碼（Change-as-Code）、流動而非僵化、增量規範同棕地優先。呢啲理念共同構成一個輕量無侵入嘅開發框架。
初始化同目錄結構
執行 openspec init 之後，項目會生成以下目錄結構：
your-project/
├── openspec/
│ ├── AGENTS.md
│ ├── project.md
│ ├── specs/
│ └── changes/
└── .claude/AGENTS.md 定義與 Claude Code 交互嘅指令集，project.md 記錄技術棧等元信息。
呢個結構專為 Claude Code 設計，但亦兼容其他 AI 工具。
核心工作流指令
完成初始化之後，就可以用斜槓命令喺 Claude Code 入面驅動開發流程。主要有三個步驟：
提案命令會自動喺 openspec/changes/ 下建立對應文件夾，包含 proposal.md、design.md、tasks.md 同 specs 子目錄。
另外仲有 openspec list、openspec show、openspec validate 等管理命令。
需求提案嘅輸入方式
提案嘅輸入可以好靈活，主要分三種方式：
直接自然語言輸入：喺命令度詳細描述需求細節，AI 會自動提取成結構化文檔。
第二種係先寫好需求文檔（例如 requirements.md），再叫 AI 讀取生成提案。呢種適合複雜需求。
第三種係交互式修正：先叫 AI 生成草案，再通過對話修正，最後先實施。
一、OpenSpec 介紹
OpenSpec 嘅核心思想係規範驅動開發（Spec-Driven Development, SDD），佢嘅本質係喺寫任何 code 之前，要叫人同 AI 就「要做啲乜」達成清晰、可以追溯嘅共識，咁就可以避免 AI 自由發揮搞到 code 偏離預期。
佢嘅核心理念可以概括成以下幾點：
先對齊，再寫 code：喺動手寫 code 之前，通過結構化文檔（Proposal → Spec → Design → Tasks）確保需求、設計同實現高度一致。
變即係 code（Change-as-Code）：將每一次軟件變更當做一個獨立、可以版本化、可以驗證嘅 code 單元，包含完整嘅上下文資訊。
流動而唔係死板（Fluid not rigid）：唔強制階段閘門（gate），支持隨時回溯、迭代同並行開發，適應敏捷同探索性工作。
增量規範（Delta Specs）：淨係記錄新增（ADDED）、修改（MODIFIED）、刪除（REMOVED）嘅內容，減少上下文負擔，提升 AI 執行精度。
棕地優先（Brownfield-first）：專為現有項目設計，唔使重構就可以引入，輕量冇侵入，兼容主流 AI 編程工具（好似 Copilot、Cursor、Claude）。
二、OpenSpec 項目初始化
入咗項目目錄之後，執行：
openspec inityour-project/
├── openspec/
│ ├── AGENTS.md # 定義瞭如何與 Claude Code 交互的指令集
│ ├── project.md # 項目元信息，如技術棧
│ ├── specs/ # 存放項目規範文件
│ └── changes/ # 存放變更提案
└── .claude/ # Claude Code 的配置目錄三、OpenSpec 指令
🚀 核心工作流
集成完成之後，你就可以喺 Claude Code 度通過斜槓命令嚟驅動開發流程。
啟動 Claude Code
喺項目根目錄下面，運行
claude code命令進入交互模式提案 (Propose)
當你需要開發一個新功能嗰時，首先創建一個變更提案。咁會令 AI 先產生一份包含需求、設計同任務清單嘅文檔。
/openspec:proposal "為 API 添加用戶角色過濾功能"執行之後，OpenSpec 會喺
openspec/changes/目錄下面創建一個對應嘅提案文件夾同文檔 add_role_filter
呢個目錄下面有4個重要文件：
1、proposal.md
AI 嘅作用：AI 會將你嘅簡短需求擴寫成一份標準嘅需求文檔。
內容示例：
背景：點解要加呢個功能？
目標：用戶可以喺 GET /users 接口度通過 ?role=admin 篩選用戶。
驗收標準：非管理員訪問會被拒絕；參數缺失嗰時默認返回普通用戶。
2、design.md
AI 嘅作用：AI 會根據你嘅技術棧（例如 Express, TypeORM, PostgreSQL）生成具體嘅技術方案。
User 表係咪已經有 role 字段，如果冇，就生成 Migration 腳本嘅偽代碼。API 變更：定義 GET /users 嘅 Query 參數類型。
代碼結構：指出需要修改 user.controller.ts 和 user.service.ts
3、Tasks.md
AI 嘅作用：呢個係最重要嘅文件。AI 會將設計拆解成可以執行嘅步驟清單。呢個係後續 /openspec:apply 命令執行嘅直接依據。
內容示例：
創建數據庫遷移檔案 add-role-to-users
更新User 實體類，添加 role 枚舉字段。修改 UserService.findAll 方法，增加 where 條件邏輯。
寫單元測試覆蓋 role 過濾場景。
4、specs/
AI 嘅作用：如果涉及複雜嘅接口定義（例如 OpenAPI/Swagger）或者數據結構，AI 會喺呢度生成具體嘅規範文件。如果係簡單功能，呢度可能係空嘅或者包含簡單嘅類型定義。
實施 (Implement)審查同意確認提案之後，你可以命令 AI 根據提案裏面嘅任務清單嚟寫 code。/openspec:apply <提案名稱>AI 會嚴格按照規範生成 code，仲可能自動加返引用規範嘅註釋 add_role_filter
歸檔 (Archive)功能開發完成同驗證冇問題之後，將嗰個變更歸檔，形成項目歷史記錄。
/openspec:archive <提案名稱>歸檔之後，相關嘅規範會被移動到
openspec/specs/目錄，完成一次開發閉環 add_role_filter
四、需求提案嘅輸入：重要
1、喺指令度直接通過「自然語言」注入細節
/openspec:proposal "在用戶列表接口(GET /users)添加後端過濾功能。\
需求細節：\
1. 新增查詢參數 'role'，支持 'admin', 'editor', 'viewer' 三種枚舉值。\
2. 只有 'admin' 角色的登錄用戶才能使用該過濾參數，普通用戶傳參應被忽略。\
3. 如果傳了無效的角色值，接口應返回 400 錯誤。\
4. 數據庫字段使用 'user_role' 表，不要修改現有的 API 響應結構，只在查詢時生效。"結果： AI 會根據呢段詳細嘅描述，自動喺 proposal.md 和 design.md 裏面寫入上述所有約束，同喺 tasks.md 裏面生成具體嘅檢查步驟。
2、先寫文檔，俾 AI 讀取（最適合複雜需求）
如果你嘅需求非常複雜（例如涉及複雜嘅業務邏輯判斷、UI 交互細節），寫喺命令行度太長，你可以先創建一個 Markdown 檔案。
創建文件：喺項目根目錄創建一個 requirements.md（或者任何名）。
# 用戶角色過濾需求
- **場景**：管理員需要在後台管理界面篩選用戶。
- **邏輯**：
- 當 `status=active` 且 `role=admin` 時，顯示特定圖標。
- 排序規則：管理員永遠排在第一位。
- **異常處理**：...發送指令：喺 Claude Code 度引用呢個文件
/openspec:proposal "讀取 requirements.md 文件，根據其中的詳細需求生成變更提案。"proposal.md 和 design.md。示例
# 需求文檔：用戶列表角色過濾功能
## 1. 背景與目標
- **背景**：目前後台管理員無法快速篩選出特定角色的用戶，需要人工肉眼查找。
- **目標**：在 `GET /users` 接口中增加按角色篩選的能力，提高管理效率。
- **優先級**：P0 (高)
## 2. 用戶故事
- 作為一名**超級管理員**，我希望在查詢用戶列表時傳入 `role=admin`，以便只看到管理員賬號。
- 作為一名**普通用戶**，如果我嘗試傳入 `role` 參數，我希望被忽略或返回錯誤（取決於安全策略），且不能看到非公開的角色信息。
## 3. 技術約束 (重要)
> AI 必須嚴格遵守以下技術棧和規則：
- **框架**：使用 NestJS (Controller/Service/Module 模式)。
- **ORM**：使用 TypeORM，不要寫原生 SQL。
- **類型安全**：必須使用 TypeScript 的 strict 模式。
- **數據庫**：字段名必須是 `role`，類型是枚舉 `UserRole`。
- **代碼風格**：遵循現有的 `src/users` 目錄結構，不要創建新的 Controller，直接修改現有的 `UsersController`。
- **安全**：必須使用現有的 `@Roles('admin')` 守衞裝飾器。
## 4. 接口與數據定義
### 4.1 數據庫變更
- 表：`users`
- 字段：`role` (Enum: 'admin', 'editor', 'viewer')
- 默認值：'viewer'
### 4.2 API 變更
- **URL**: `GET /users`
- **Query 參數**:
- `role` (可選): 枚舉值 ['admin', 'editor', 'viewer']
- `page` (現有): 保持不變
- **響應示例**:
```json
{
"data": [
{ "id": 1, "name": "Alice", "role": "admin" }
],
"total": 1
}
```
## 5. 驗收標準
- [ ] 傳入 `?role=admin` 時，SQL 查詢必須包含 `WHERE role = 'admin'`。
- [ ] 傳入非法角色值（如 `?role=superuser`）時，接口必須返回 **400 Bad Request**。
- [ ] 非管理員用戶調用該接口並帶參數時，必須被守衞攔截，返回 **403 Forbidden**。
- [ ] 必須補充至少一個單元測試，覆蓋“非法角色值”的場景。3、交互式修正（「先射箭再畫靶子」）
OpenSpec 嘅工作流係迭代嘅。你可以先俾 AI 生成一個「草案」，然後通過對話嚟修正佢，最後再確認。
第一步（生成草案）：
/openspec:proposal "添加用戶角色過濾功能"第二步（審查同修正）：呢個時候，AI 已經生成了
openspec/changes/xxx/proposal.md
你打開睇一眼，發現佢將「過濾邏輯」寫錯咗。
你直接喺對話框對 Claude 講：
“剛才生成的 proposal 裏，關於權限的判斷邏輯不對。應該是：只有超級管理員才能看到‘禁用用戶’的選項，普通管理員不行。請更新 proposal.md 和 design.md。”AI 會自動重寫嗰兩個文件。你確認冇問題之後，再執行 /openspec:apply。
💡 補充說明
常用命令一覽
除咗上面嘅核心命令，你仲可以用以下 CLI 命令嚟管理項目：
openspec list：列出所有變更提案openspec show <name>：查看指定提案嘅詳情openspec validate：驗證規範嘅語法正確性openspec update：更新AGENTS.md文件，確保 AI 指令係最新嘅
配置中文界面
如果你希望 OpenSpec 嘅終端提示同交互式精靈顯示做中文，可以執行以下命令：
openspec config set locale zh-CN請注意，呢個隻影響 OpenSpec 嘅界面語言，唔影響規範文件本身嘅內容。
往期推薦
一、OpenSpec 介紹
OpenSpec 的核心思想是規範驅動開發（Spec-Driven Development, SDD），其本質是在編寫任何代碼之前，讓人與 AI 就“要做什麼”達成清晰、可追溯的共識，從而避免 AI 自由發揮導致的代碼偏離預期。
其核心理念可概括為以下幾點：
先對齊，再編碼：在動手寫代碼前，通過結構化文檔（Proposal → Spec → Design → Tasks）確保需求、設計與實現高度一致。
變更即代碼（Change-as-Code）：將每一次軟件變更視為一個獨立、可版本化、可驗證的代碼單元，包含完整的上下文信息。
流動而非僵化（Fluid not rigid）：不強制階段門控，支持隨時回溯、迭代和並行開發，適應敏捷與探索性工作。
增量規範（Delta Specs）：只記錄新增（ADDED）、修改（MODIFIED）、刪除（REMOVED）的內容，減少上下文負擔，提升 AI 執行精度。
棕地優先（Brownfield-first）：專為現有項目設計，無需重構即可引入，輕量無侵入，兼容主流 AI 編程工具（如 Copilot、Cursor、Claude）。
二、OpenSpec 項目初始化
進入項目目錄後，執行：
openspec inityour-project/
├── openspec/
│ ├── AGENTS.md # 定義瞭如何與 Claude Code 交互的指令集
│ ├── project.md # 項目元信息，如技術棧
│ ├── specs/ # 存放項目規範文件
│ └── changes/ # 存放變更提案
└── .claude/ # Claude Code 的配置目錄三、OpenSpec 指令
🚀 核心工作流
集成完成後，你就可以在 Claude Code 中通過斜槓命令來驅動開發流程。
啓動 Claude Code
在項目根目錄下，運行
claude code命令進入交互模式提案 (Propose)
當你需要開發一個新功能時，首先創建一個變更提案。這會讓 AI 先生成一份包含需求、設計和任務清單的文檔。
/openspec:proposal "為 API 添加用戶角色過濾功能"執行後，OpenSpec 會在
openspec/changes/目錄下創建一個對應的提案文件夾和文檔add_role_filter
這個目錄下面有4個重要文件：
1、proposal.md
AI 的作用：AI 會將你的簡短需求擴寫為一份標準的需求文檔。
內容示例：
背景：為什麼要加這個功能？
目標：用戶可以在 GET /users 接口中通過 ?role=admin 篩選用戶。
驗收標準：非管理員訪問被拒絕；參數缺失時默認返回普通用戶。
2、design.md
AI 的作用：AI 會根據你的技術棧（如 Express, TypeORM, PostgreSQL）生成具體的技術方案。
User 表是否已有 role 字段，如果沒有，生成 Migration 腳本的偽代碼。API 變更：定義 GET /users 的 Query 參數類型。
代碼結構：指出需要修改 user.controller.ts 和 user.service.ts
3、Tasks.md
AI 的作用：這是最重要的文件。AI 會將設計拆解為可執行的步驟清單。這是後續 /openspec:apply 命令執行的直接依據。
內容示例：
創建數據庫遷移文件 add-role-to-users
更新User 實體類，添加 role 枚舉字段。修改 UserService.findAll 方法，增加 where 條件邏輯。
編寫單元測試覆蓋 role 過濾場景。
4、specs/
AI 的作用：如果涉及複雜的接口定義（如 OpenAPI/Swagger）或數據結構，AI 會在這裏生成具體的規範文件。如果是簡單功能，這裏可能是空的或者包含簡單的類型定義。
實施 (Implement)審查並確認提案後，你可以命令 AI 根據提案中的任務清單來實施代碼。/openspec:apply <提案名稱>AI 會嚴格按照規範生成代碼，並可能自動添加引用規範的註釋add_role_filter
歸檔 (Archive)功能開發完成並驗證無誤後，將該變更歸檔，形成項目歷史記錄。
/openspec:archive <提案名稱>歸檔後，相關的規範會被移動到
openspec/specs/目錄，完成一次開發閉環add_role_filter
四、需求提案的輸入：重要
1、在指令中直接通過“自然語言”注入細節
/openspec:proposal "在用戶列表接口(GET /users)添加後端過濾功能。\
需求細節：\
1. 新增查詢參數 'role'，支持 'admin', 'editor', 'viewer' 三種枚舉值。\
2. 只有 'admin' 角色的登錄用戶才能使用該過濾參數，普通用戶傳參應被忽略。\
3. 如果傳了無效的角色值，接口應返回 400 錯誤。\
4. 數據庫字段使用 'user_role' 表，不要修改現有的 API 響應結構，只在查詢時生效。"結果： AI 會根據這段詳細的描述，自動在 proposal.md 和 design.md 中寫入上述所有約束，並在 tasks.md 中生成具體的檢查步驟。
2、先寫文檔，讓 AI 讀取（最適合複雜需求）
如果你的需求非常複雜（比如涉及複雜的業務邏輯判斷、UI 交互細節），寫在命令行裏太長，你可以先創建一個 Markdown 文件。
創建文件：在項目根目錄創建一個 requirements.md（或者任何名字）。
# 用戶角色過濾需求
- **場景**：管理員需要在後台管理界面篩選用戶。
- **邏輯**：
- 當 `status=active` 且 `role=admin` 時，顯示特定圖標。
- 排序規則：管理員永遠排在第一位。
- **異常處理**：...發送指令：在 Claude Code 中引用這個文件
/openspec:proposal "讀取 requirements.md 文件，根據其中的詳細需求生成變更提案。"proposal.md 和 design.md。示例
# 需求文檔：用戶列表角色過濾功能
## 1. 背景與目標
- **背景**：目前後台管理員無法快速篩選出特定角色的用戶，需要人工肉眼查找。
- **目標**：在 `GET /users` 接口中增加按角色篩選的能力，提高管理效率。
- **優先級**：P0 (高)
## 2. 用戶故事
- 作為一名**超級管理員**，我希望在查詢用戶列表時傳入 `role=admin`，以便只看到管理員賬號。
- 作為一名**普通用戶**，如果我嘗試傳入 `role` 參數，我希望被忽略或返回錯誤（取決於安全策略），且不能看到非公開的角色信息。
## 3. 技術約束 (重要)
> AI 必須嚴格遵守以下技術棧和規則：
- **框架**：使用 NestJS (Controller/Service/Module 模式)。
- **ORM**：使用 TypeORM，不要寫原生 SQL。
- **類型安全**：必須使用 TypeScript 的 strict 模式。
- **數據庫**：字段名必須是 `role`，類型是枚舉 `UserRole`。
- **代碼風格**：遵循現有的 `src/users` 目錄結構，不要創建新的 Controller，直接修改現有的 `UsersController`。
- **安全**：必須使用現有的 `@Roles('admin')` 守衞裝飾器。
## 4. 接口與數據定義
### 4.1 數據庫變更
- 表：`users`
- 字段：`role` (Enum: 'admin', 'editor', 'viewer')
- 默認值：'viewer'
### 4.2 API 變更
- **URL**: `GET /users`
- **Query 參數**:
- `role` (可選): 枚舉值 ['admin', 'editor', 'viewer']
- `page` (現有): 保持不變
- **響應示例**:
```json
{
"data": [
{ "id": 1, "name": "Alice", "role": "admin" }
],
"total": 1
}
```
## 5. 驗收標準
- [ ] 傳入 `?role=admin` 時，SQL 查詢必須包含 `WHERE role = 'admin'`。
- [ ] 傳入非法角色值（如 `?role=superuser`）時，接口必須返回 **400 Bad Request**。
- [ ] 非管理員用戶調用該接口並帶參數時，必須被守衞攔截，返回 **403 Forbidden**。
- [ ] 必須補充至少一個單元測試，覆蓋“非法角色值”的場景。3、交互式修正（“先射箭再畫靶子”）
OpenSpec 的工作流是迭代的。你可以先讓 AI 生成一個“草案”，然後通過對話來修正它，最後再確認。
第一步（生成草案）：
/openspec:proposal "添加用戶角色過濾功能"第二步（審查與修正）：此時，AI 已經生成了
openspec/changes/xxx/proposal.md
你打開看一眼，發現它把“過濾邏輯”寫錯了。
你直接在對話框對 Claude 說：
“剛才生成的 proposal 裏，關於權限的判斷邏輯不對。應該是：只有超級管理員才能看到‘禁用用戶’的選項，普通管理員不行。請更新 proposal.md 和 design.md。”AI 會自動重寫那兩個文件。你確認沒問題了，再運行 /openspec:apply。
💡 補充說明
常用命令速覽
除了上述核心命令，你還可以使用以下 CLI 命令來管理項目：
openspec list: 列出所有變更提案openspec show <name>: 查看指定提案的詳情openspec validate: 驗證規範的語法正確性openspec update: 更新AGENTS.md文件，確保 AI 指令是最新的
配置中文界面
如果你希望 OpenSpec 的終端提示和交互式嚮導顯示為中文，可以執行以下命令：
openspec config set locale zh-CN請注意，這僅影響 OpenSpec 的界面語言，不影響規範文件本身的內容。
往期推薦