name: sdd-dev-workflow description: "規範驅動開發工作流（SDD + Speckit + Claude Code）。用於複雜軟體開發專案。⚠️ 必需環境變數: ZHIPU_API_KEY。可選: GITHUB_TOKEN, ANTHROPIC_API_KEY。當用戶需要開發複雜應用、進行多迭代開發專案、使用 sessions_spawn 自動化開發時使用此 skill。"

SDD 開發工作流 Skill

快速開始：見下方 | 安裝指南：references/installation.md | 問題排查：references/troubleshooting.md

🎯 核心理念

用規範驅動開發（SDD）把需求變成結構化的"規範文件"，讓 LLM 在準確上下文中輸出更符合預期的程式碼。

三大原則：規範優先 → 規範錨定 → 規範作為源

⚡ 快速開始

# 環境檢查
~/.openclaw/skills/sdd-dev-workflow/scripts/check-environment.sh

# 建立專案
~/.openclaw/skills/sdd-dev-workflow/scripts/init-project.sh my-project
cd ~/openclaw/workspace/projects/my-project

# 啟動開發
claude --permission-mode acceptEdits

Speckit 工作流

/speckit.constitution 閱讀並使用 ~/.openclaw/skills/sdd-dev-workflow/templates/constitution-enterprise.md
/speckit.specify [功能描述]
/speckit.clarify    # ⚠️ 強制執行至少1次
/speckit.plan [技術棧]
/speckit.tasks
/speckit.analyze    # ⚠️ 強制執行至少1次
/speckit.implement 嚴格遵循憲法 @.specify/memory/constitution.md

🔄 迭代開發流程

新專案 vs 迭代：流程相同，區別僅在於初始化

流程對比

專案初始化（僅新專案）

⚠️ 詢問使用者：GitHub 倉庫如何處理？

選項 1：新建倉庫

gh repo create my-project --private --clone
cd my-project

選項 2：關聯現有倉庫

git init
git remote add origin https://github.com/user/existing-repo.git

然後執行 Specify init（僅一次）：

specify init . --here --ai claude --force --no-git

迭代開發（跳過專案初始化）

已初始化專案，直接建立新迭代： - 跳過 GitHub 初始化 - 跳過 specify init - 直接在 Claude Code 執行：/speckit.specify <功能描述>

Specify 序號自動遞增：

# 檢測下一個序號
next_num=$(~/.openclaw/skills/sdd-dev-workflow/scripts/get-next-iteration.sh)
iteration_name="${next_num}-new-feature"

問題修復：Specify CLI 建立迭代時序號可能重複（001-xxx, 001-yyy），使用 get-next-iteration.sh 自動檢測最大序號 + 1。

🔒 Git 版本控制（強制）

AI 開發不確定性高 → Git 是安全網

初始化檢查

觸發條件：專案目錄不存在 .git 資料夾

# 檢查並初始化
if [ ! -d ".git" ]; then
  # 詢問 Git 倉庫地址或使用預設
  git init
  git add .
  git commit -m "chore: 初始化專案結構"
fi

提交規範

每個階段完成後必須提交：

# 每個階段完成後執行
git add . && git commit -m "<commit-message>"

驗收後自動 PR

觸發條件：驗收通過 + 特性分支（非 main）

# 檢查驗收結果
if [ "$ACCEPTANCE_RESULT" = "PASS" ]; then
  # 提交最終變更
  git add . && git commit -m "chore: 工作流完成"

  # 檢查是否在特性分支
  current_branch=$(git branch --show-current)
  if [ "$current_branch" != "main" ]; then
    # 推送特性分支
    git push -u origin "$current_branch"

    # 建立 PR
    gh pr create \
      --title "feat: $current_branch" \
      --body "## 變更說明

- 迭代序號：$current_branch
- 驗收狀態：✅ PASS

## 測試結果

- 語法檢查：通過
- 單元測試：通過
- 服務啟動：驗證成功" \
      --base main
  else
    # main 分支直接推送
    [ -n "$(git remote -v)" ] && git push origin main
  fi
fi
更多技能請訪問小蔥技能站7w4.net。

詳見：references/git-version-control.md

📦 依賴自動安裝（零注意力）

完成開發，不為工具停頓

兩層依賴策略

自動安裝邏輯

# 檢測到 ModuleNotFoundError 時自動執行
if error contains "ModuleNotFoundError: No module named 'fastapi'"; then
  pip install fastapi
fi

不詢問，直接安裝。

預裝依賴檢查

~/.openclaw/skills/sdd-dev-workflow/scripts/check-environment.sh

詳見：references/dependency-installation.md

⚠️ 工具鏈協作方式（必讀）

Specify CLI 的角色

Specify CLI         →       Claude Code          →      完成開發
（僅用於初始化）           （執行 /speckit 命令）        （程式碼實現）

Specify CLI 僅用於初始化： - ✅ specify init 初始化專案結構（每個專案執行一次） - ❌ 不支援 clarify/plan/tasks/analyze/implement

非互動模式：

specify init . --here --ai claude --force --no-git

後續所有 /speckit 命令都在 Claude Code 內執行。

許可權模式選擇

安全建議： - 生產環境 → acceptEdits + 人工稽核 - 隔離測試環境 → bypassPermissions（VM/容器） - 禁止：在生產伺服器使用 bypassPermissions

最終目標

完成標準： - ✅ 程式碼已實現（不是文件） - ✅ 測試已通過 - ✅ 功能可執行

🚨 子 Agent 強制規則（CRITICAL）

核心原則：子 agent = 流程驅動器（driver），不是程式碼實現者（implementer）

絕對禁止

• ❌ 禁止使用 write 工具寫程式碼檔案（src/**/*.py, tests/**/*.py）
• ❌ 禁止跳過 /speckit.* 命令

必須執行

• ✅ 必須通過 sdd-driver.sh 指令碼操作
• ✅ 必須通過 tmux 驅動 Claude Code

意外處理

詳見：references/autonomous-agent.md

📋 Speckit 工作流

init → constitution → specify → clarify → plan → tasks → analyze → implement

⚠️ 強制階段：clarify ≥1 次，analyze ≥1 次

人類介入點

介入判斷：資訊不完整/疑義 → 轉發使用者；資訊完整 → 自己決策 補充規範 等待回覆 繼續執行 收到後繼續

#### 自動決策條件（無需介入）

- 資訊完整，只是細節缺失
- 常規技術選擇（如用 requests 還是 httpx）
- 憲法已有明確規定
- clarify 連續 2 次無問題
- 簡單專案，需求明確

#### 需要介入的條件

- 多個方案各有優劣，需要業務決策
- 需求有明顯矛盾或衝突
- 涉及外部依賴或資源
- 超出憲法規定的邊界
- analyze 發現嚴重一致性問題

---

## 🏛️ 公共憲法模板

### 使用方式

```bash
# 在 Claude Code 中引用公共憲法
/speckit.constitution 閱讀並使用公共憲法模板 ~/.openclaw/skills/sdd-dev-workflow/templates/constitution-enterprise.md

模板位置： - templates/constitution-enterprise.md（推薦） - templates/constitution-lite.md（精簡）

詳見：references/constitution-guide.md

📁 專案路徑規範

標準目錄結構

~/openclaw/workspace/
├── projects/                    # 正式開發專案（長期維護）
├── tmp/                         # 臨時專案（驗證、測試，可隨時清理）
├── docs/                        # 文件（可選，按需建立）
├── research/                    # 深度研究報告
└── memory/                      # 日期日記

路徑規則

新專案建立規範

# ✅ 正式專案
~/.openclaw/skills/sdd-dev-workflow/scripts/init-project.sh my-project

# ✅ 臨時專案
~/.openclaw/skills/sdd-dev-workflow/scripts/init-project.sh test-xyz --tmp

# ❌ 錯誤：在 workspace 根目錄建立
cd ~/openclaw/workspace && specify init my-project  # 錯誤！

🚀 使用子 Agent（推薦）

標準流程

1. 啟動 Claude Code（bypassPermissions 模式）
2. 逐階段執行 SDD 流程（constitution → specify → clarify → plan → tasks → analyze → implement）
3. 驗收測試（py_compile + pytest + uvicorn）
4. 輸出結果（ACCEPTANCE_RESULT: PASS | FAIL）

關鍵等待規則： - ⏱️ 高峰期（12:00-18:00 GMT+8）GLM-5 響應可能需要 1-5 分鐘 - ⏱️ 使用 process 工具時，設定 timeoutMs: 300000（5分鐘） - ⏱️ 不要在 30 秒內判定為超時

完成標準： - ✅ 程式碼已實現（不是文件） - ✅ 測試已通過（至少 1 個核心測試） - ✅ 功能可執行（服務能啟動）

詳細程式碼模板：見 references/autonomous-agent.md

🔄 長時間執行 Agent

挑戰：上下文丟失、進度中斷、狀態不可知

解決方案：斷點續傳機制

.task-context/
├── progress.json     # 進度跟蹤
├── checkpoint.md     # 檢查點快照
└── session-log.md    # 會話日誌

恢復中斷任務：

sessions_spawn({
  task: "繼續開發 [專案]，讀取 .task-context/checkpoint.md 恢復上下文"
})

詳見：references/long-running-agent.md

📐 開發最佳實踐

詳見：references/best-practices.md

⚠️ 常見問題

• Specify CLI 卡住 → 已跳過，使用離線模式
• 429 限流 → 等待 5 分鐘後重試
• ModuleNotFoundError → 直接 pip install <module>
• 詳細排查：references/troubleshooting.md

📚 參考文件

⚠️ 安全警告

風險評估

使用建議

✅ 推薦做法： - 在 VM/容器中執行 - 使用測試令牌，避免生產憑據 - 使用 acceptEdits 模式，人工稽核 bash 指令碼 - 定期備份 ~/openclaw/workspace/ 目錄

❌ 避免操作： - 在生產伺服器使用 bypassPermissions - 使用高許可權 GitHub 令牌 - 直接執行未經審查的網路指令碼

監控工具：見 references/monitoring.md

這是一套質量不錯的開發助手技能包，特別適合需要 AI 輔助開發複雜專案的團隊使用。它把開發流程拆解得很清晰，從需求規範到程式碼驗收都有章可循，遇到問題也有詳細的排查指南。優點是文件齊全、自動化程度高、驗收標準明確。不過部分操作步驟稍顯複雜，新手可能需要花些時間理解，而且缺少一些實際專案的使用案例參考。