📖 前置閱讀：SDD 環境安裝篇

📚 延伸閱讀：Git 入門：版本控制基礎指令

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

新人：「SDD 裝好了，但指令好多，不知道從哪開始…」
資深工程師：「其實只要記三個：proposal、apply、archive。」
新人：「就這樣？」
資深工程師：「對，其他都可以請 Claude 幫你執行。這三個是 SDD 的核心流程。」
新人：「那其他指令什麼時候用？」
資深工程師：「遇到再查就好。我先教你最常用的。」

這篇文章會教你：

  • SDD 核心三步驟
  • 實際操作一次完整流程
  • Claude Code 常用指令

SDD 核心：三個斜線指令

記住這三個，就能開始用 SDD：

/openspec:proposal  →  /openspec:apply  →  /openspec:archive
     建立提案              實作程式碼           歸檔變更
步驟 指令 做什麼
1 /openspec:proposal 寫下你要什麼，讓 AI 確認理解
2 /openspec:apply AI 照規格實作，自動跑測試
3 /openspec:archive 記錄這次變更，整理文件

重點：所有操作都在 Claude Code 中完成，不需要記其他指令。

實戰：新增 /version 端點

用上一篇建立的專案，實際走一次 SDD 流程：

cd my-sdd-project
claude

Step 1：Proposal（建立提案）

> /openspec:proposal

Claude 會問你想做什麼：

> 我想新增一個 /version 端點，回傳應用程式版本資訊

Claude 會：

  1. 建立 openspec/changes/<id>/proposal.md
  2. 詢問細節（回傳格式、版本號來源等）
  3. 確認你同意後，準備進入實作

Step 2：Apply（實作）

> /openspec:apply

Claude 會：

  1. 根據提案寫程式碼
  2. 自動執行測試
  3. 測試失敗會自動修正
  4. 更新 tasks.md 進度

你只需要看著它做，有問題再介入。

Step 3：Archive（歸檔）

測試都通過後：

> /openspec:archive

Claude 會：

  1. 整理變更記錄
  2. 移動檔案到 archive/ 目錄
  3. 更新主規格文件

完成！ 訪問 http://127.0.0.1:8000/version 測試新端點。

別忘了 commit

> 請幫我 commit

Claude 會自動產生適當的 commit message。

當流程不順利時

提案需要修改

在 /openspec:apply 之前：

> 請修改提案，/version 要多回傳 Python 版本

測試一直失敗

直接貼錯誤訊息給 Claude：

> 測試失敗：AssertionError: expected 200 but got 404

Archive 後發現問題

  • 小 bug：直接請 Claude 修，不用開新提案
  • 大改動：開新的 /openspec:proposal

Claude Code 常用指令

基本操作

指令 說明
claude 啟動互動模式
claude "問題" 單次提問，不進互動模式
Ctrl+C 取消當前操作
Ctrl+D 或 /exit 退出

常用斜線指令

指令 什麼時候用
/help 不知道有什麼指令
/clear 開始新任務，清除舊對話
/compact 對話太長，接近上限
/usage 查看訂閱額度用了多少
/tasks 管理背景執行的程式
/resume 繼續之前的對話

模式切換（Shift+Tab）

模式 說明
Normal 預設，執行前會問你
Plan 只規劃不執行（SDD 用 proposal 取代）
Accept Edits 自動接受編輯，不逐一確認

背景執行伺服器

開發時需要邊跑伺服器邊對話：

> 請在背景啟動開發伺服器

管理背景任務：

/tasks          # 查看所有背景任務
/tasks → k      # 停止選中的任務

OpenSpec 專案結構

執行 openspec init --tools claude 後產生：

./
├── CLAUDE.md                    # Claude 專案設定
├── openspec/
│   └── project.md               # 專案約定
└── .claude/commands/openspec/   # 斜線指令定義
    ├── proposal.md
    ├── apply.md
    └── archive.md

建立提案後，會產生：

openspec/changes/<change-id>/
├── proposal.md    # 提案內容
├── tasks.md       # 實作清單
└── specs/         # 規格變更

歸檔後移至 openspec/changes/archive/。

選用：uv 指令

非 SDD 必要：如果你使用 Python 開發，以下是常用指令。完整說明請參考 uv 入門。

指令 說明
uv add fastapi 新增套件
uv run python main.py 執行程式
uv run uvicorn main:app --reload 啟動開發伺服器
uv run pytest 執行測試

提示：這些指令都可以請 Claude 代為執行。

指令速查表

每日常用

指令 用途
claude 啟動 AI 助手
/openspec:proposal 建立提案
/openspec:apply 實作
/openspec:archive 歸檔
/clear 清除對話
請幫我 commit 提交變更

偶爾使用

指令 用途
/usage 查看額度
/compact 壓縮對話
/tasks 管理背景任務
/resume 恢復對話

一次性（專案初始化）

指令 用途
openspec init --tools claude 初始化 SDD
uv init 初始化 Python 專案
git init 初始化版本控制

下一步

現在你已經會用 SDD 了！核心就是：

/openspec:proposal → /openspec:apply → /openspec:archive

其他指令遇到再查。實際多用幾次就會熟練。

參考連結