📖 前置知識

這篇文章要解決什麼問題？

新人：「Claude 很強，但我請它改 A 功能，結果它把 B 功能改壞了…」
資深工程師：「因為你沒有先跟 AI 對齊需求。它不知道哪些東西不能動。」
新人：「那我要怎麼讓 AI 知道？」
資深工程師：「用 SDD。先寫規格，讓 AI 確認理解，再開始實作。這樣它會照著規格走，不會亂改。」
新人：「聽起來多一個步驟？」
資深工程師：「但省下的 debug 時間遠超過寫規格的時間。而且規格還能當文件。」

這篇文章會教你：

  • 理解 SDD 的核心概念
  • 安裝 SDD 必要工具（Claude Code + OpenSpec）
  • 建立第一個 SDD 專案

什麼是 SDD？

SDD（Specification-Driven Development，規格驅動開發） 是一種「先規格、後實作」的 AI 協作開發方式。

核心流程

1. Proposal（提案）  →  2. Apply（實作）  →  3. Archive（歸檔）
    寫下你要什麼           AI 照規格實作         記錄這次變更

為什麼需要 SDD？

傳統 AI 協作 SDD 協作
直接叫 AI 改 code 先寫規格，AI 確認後再改
AI 可能改錯地方 AI 照規格走，範圍明確
改完不知道改了什麼 每次變更都有記錄
難以 rollback 可以追溯每個決策

SDD 工具組合

工具 角色 說明
Claude Code AI 編碼助手 Anthropic 官方 CLI，負責對話與程式碼生成
OpenSpec 規格管理 追蹤 Proposal → Apply → Archive 流程

需要安裝什麼？

必要工具

順序 工具 用途
1 nvm Node.js 版本管理（推薦）
2 Node.js Claude Code、OpenSpec 的執行環境
3 Claude Code AI 編碼助手
4 OpenSpec SDD 規格管理

選用工具

以下工具非 SDD 必要，但本文作者常用於 Python 開發，故一併介紹：

工具 用途 詳細說明
uv Python 套件管理 uv 入門
FastAPI Python Web 框架 本文範例專案使用

提示：如果你不使用 Python，可以跳過 uv 和 FastAPI 的部分。

環境需求

項目 最低需求 本文使用
作業系統 Ubuntu 22.04+ / macOS / WSL Ubuntu 24.04
Node.js 20.19.0+ v22.17.1
網路連線 需要（安裝套件、認證） -
Claude 帳號 API Key 或 Pro/Max 訂閱 Max 訂閱

Step 1：安裝 nvm 與 Node.js

Claude Code 和 OpenSpec 都需要 Node.js。推薦使用 nvm 安裝，可管理多版本且避免權限問題。

# 1. 安裝 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

# 2. 重新載入 shell 設定
source ~/.bashrc

# 3. 安裝 Node.js 22（LTS）
nvm install 22

# 4. 驗證安裝
node -v    # v22.17.1
npm -v     # 10.9.2
📌 其他安裝方式（apt） ```bash sudo apt update sudo apt install nodejs npm ``` > **注意**：Ubuntu 24.04 apt 預設的 Node.js 是 **18.x**，可能不符合 Claude Code 最低需求（v20.19.0+）。且 `npm install -g` 需加上 `sudo`。

Step 2：安裝 Claude Code

Claude Code 是 Anthropic 官方的 CLI 工具。

安裝

npm install -g @anthropic-ai/claude-code

首次啟動與認證

claude

首次執行會開啟瀏覽器引導認證。你可以選擇：

認證方式 適用對象
Claude Pro/Max 訂閱 個人開發者（本文使用）
Anthropic API Key 企業或需要 API 計費

驗證

claude --version    # 2.0.61 (Claude Code)

認證成功後，輸入 claude 即可進入互動模式。

Step 3：安裝 OpenSpec

OpenSpec 是 SDD 的規格管理工具，與 Claude Code 原生整合。

安裝

# 手動安裝
npm install -g @fission-ai/openspec@latest

# 或請 Claude 協助
claude "請幫我安裝 openspec，使用 npm install -g @fission-ai/openspec@latest"

驗證

openspec --version    # 0.16.0

整合驗證：建立第一個 SDD 專案

確認 Claude Code + OpenSpec 可以協同運作：

# 1. 建立專案目錄
mkdir my-sdd-project && cd my-sdd-project

# 2. 初始化 OpenSpec（選擇 Claude Code）
openspec init --tools claude

# 3. 啟動 Claude Code
claude

在 Claude Code 中輸入：

> /openspec:proposal

如果 Claude 開始詢問你想建立什麼提案，恭喜！SDD 環境安裝成功！

選用：安裝 uv（Python 開發者）

可跳過：如果你不使用 Python，可以直接跳到「下一步」。

uv 是極速的 Python 套件管理器，取代 pip、poetry、pyenv。

# 手動安裝
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

# 或請 Claude 協助
claude "請幫我安裝 uv Python 套件管理器"

# 驗證
uv --version    # uv 0.8.4

📖 詳細說明：uv 入門：極速 Python 套件管理

選用：建立 FastAPI 範例專案

可跳過：這是示範如何結合 SDD + uv + FastAPI，非必要步驟。

cd my-sdd-project

# 請 Claude 協助建立
claude "請用 uv 建立 FastAPI 專案，包含 / 和 /health 兩個端點"

Claude 會執行 uv init、uv add fastapi uvicorn、建立 main.py。

啟動伺服器：

uv run uvicorn main:app --reload

開啟瀏覽器訪問 http://127.0.0.1:8000，看到 {"message": "Hello, SDD!"} 表示成功。

提示：按 Ctrl+C 停止伺服器。

常見問題

Node.js 版本過低

# 檢查版本
node -v

# 如果低於 20.19.0，用 nvm 安裝新版
nvm install 22
nvm use 22

npm 權限問題（EACCES）

改用 nvm 安裝 Node.js 可徹底解決。

Claude Code 認證失敗

  1. 確認網路連線正常
  2. 在 Claude Code 中執行 /login 重新登入

uv 找不到 Python

uv python install 3.12
uv python list

下一步

環境安裝完成！請繼續閱讀：

SDD 規格驅動開發入門（二）：指令介紹篇

學習 /openspec:proposal、/openspec:apply、/openspec:archive 三個核心指令，並實際操作為專案新增功能。

參考連結