SDD 开发工作流 Skill

快速开始：见下方 | 安装指南：references/installation.md | 问题排查：references/troubleshooting.md

🎯 核心理念

用规范驱动开发（SDD）把需求变成结构化的"规范文档"，让 LLM 在准确上下文中输出更符合预期的代码。

三大原则：规范优先 → 规范锚定 → 规范作为源

⚡ 快速开始

CODEBLOCK0

Speckit 工作流

CODEBLOCK1

🔄 迭代开发流程

新项目 vs 迭代：流程相同，区别仅在于初始化

流程对比

项目类型	GitHub 初始化	Specify	特性分支	验收后
新项目	✅ 需要	✅ 初始化	自动创建	推送 + PR
迭代

❌ 跳过 | ✅ 新迭代 | 自动创建 | 推送 + PR |

项目初始化（仅新项目）

⚠️ 询问用户：GitHub 仓库如何处理？

选项 1：新建仓库
CODEBLOCK2

选项 2：关联现有仓库
CODEBLOCK3

然后执行 Specify init（仅一次）：
CODEBLOCK4

迭代开发（跳过项目初始化）

已初始化项目，直接创建新迭代：

- 跳过 GitHub 初始化
跳过 INLINECODE0
直接在 Claude Code 执行：INLINECODE1

Specify 序号自动递增：
CODEBLOCK5

问题修复：Specify CLI 创建迭代时序号可能重复（001-xxx, 001-yyy），使用 get-next-iteration.sh 自动检测最大序号 + 1。

🔒 Git 版本控制（强制）

AI 开发不确定性高 → Git 是安全网

初始化检查

触发条件：项目目录不存在 .git 文件夹

CODEBLOCK6

提交规范

每个阶段完成后必须提交：

阶段	提交信息
constitution	INLINECODE4
specify

CODEBLOCK7

验收后自动 PR

触发条件：验收通过 + 特性分支（非 main）

CODEBLOCK8

详见：references/git-version-control.md

📦 依赖自动安装（零注意力）

完成开发，不为工具停顿

两层依赖策略

Layer	类型	处理方式
Layer 1	预装依赖	环境检查脚本验证
Layer 2

项目依赖 | 遇到时自动安装 |

自动安装逻辑

CODEBLOCK9

不询问，直接安装。

预装依赖检查

CODEBLOCK10

详见：references/dependency-installation.md

⚠️ 工具链协作方式（必读）

Specify CLI 的角色

CODEBLOCK11

Specify CLI 仅用于初始化：

- ✅ specify init 初始化项目结构（每个项目执行一次）
❌ 不支持 clarify/plan/tasks/analyze/implement

非交互模式：
CODEBLOCK12

后续所有 /speckit 命令都在 Claude Code 内执行。

权限模式选择

模式	用途	行为	安全等级
INLINECODE10	人工监督开发	文件编辑自动批准，bash脚本需确认	✅ 推荐
INLINECODE11

自动化 agent | 所有操作自动批准 | ⚠️ 仅限隔离环境 |

安全建议：

- 生产环境 → acceptEdits + 人工审核
隔离测试环境 → bypassPermissions（VM/容器）
禁止：在生产服务器使用 INLINECODE14

最终目标

❌ 错误理解	✅ 正确理解
生成 spec.md	完成代码实现
生成 plan.md

通过测试验证 | | 生成 tasks.md | 功能可以运行 |

完成标准：

- ✅ 代码已实现（不是文档）
✅ 测试已通过
✅ 功能可运行

🚨 子 Agent 强制规则（CRITICAL）

核心原则：子 agent = 流程驱动器（driver），不是代码实现者（implementer）

绝对禁止

- ❌ 禁止使用 write 工具写代码文件（src/**/*.py, tests/**/*.py）
❌ 禁止跳过 /speckit.* 命令

必须执行

- ✅ 必须通过 sdd-driver.sh 脚本操作
✅ 必须通过 tmux 驱动 Claude Code

意外处理

情况	可恢复	行动
429 rate limit	✅	等待 5 分钟后重试
timeout

详见：references/autonomous-agent.md

📋 Speckit 工作流

CODEBLOCK13

⚠️ 强制阶段：clarify ≥1 次，analyze ≥1 次

人类介入点

阶段	介入原因	介入方式
clarify	需求歧义	发送问题 → 等待回复
analyze

一致性问题 | 发送报告 → 等待确认 |

介入判断：信息不完整/疑义 → 转发用户；信息完整 → 自己决策
补充规范等待回复
继续执行收到后继续


#### 自动决策条件（无需介入）

- 信息完整，只是细节缺失
- 常规技术选择（如用 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](references/constitution-guide.md)

---

## 📁 项目路径规范

### 标准目录结构

~/openclaw/workspace/
├── projects/ # 正式开发项目（长期维护）
├── tmp/ # 临时项目（验证、测试，可随时清理）
├── docs/ # 文档（可选，按需创建）
├── research/ # 深度研究报告
└── memory/ # 日期日记


### 路径规则

| 类型 | 路径 | 示例 |
|------|------|------|
| **正式项目** | `projects/<name>/` | `projects/my-app/` |
| **临时项目** | `tmp/<name>/` | `tmp/test-workflow/` |
| **研究报告** | `research/<topic>/` | `research/ai-sovereignty/` |

### 新项目创建规范

bash

✅ 正式项目

~/.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](references/autonomous-agent.md)

---

## 🔄 长时间运行 Agent

> **挑战**：上下文丢失、进度中断、状态不可知

**解决方案**：断点续传机制

.task-context/ ├── progress.json # 进度跟踪 ├── checkpoint.md # 检查点快照 └── session-log.md # 会话日志


**恢复中断任务**：

javascript sessions_spawn({ task: "继续开发 [项目]，读取 .task-context/checkpoint.md 恢复上下文" }) ``



详见：[references/long-running-agent.md](references/long-running-agent.md)

---

## 📐 开发最佳实践

详见：[references/best-practices.md](references/best-practices.md)

---

## ⚠️ 常见问题

- **Specify CLI 卡住** → 已跳过，使用离线模式
- **429 限流** → 等待 5 分钟后重试
- **ModuleNotFoundError** → 直接

pip install


- 详细排查：[references/troubleshooting.md](references/troubleshooting.md)

---

## 📚 参考文档

| 文档 | 用途 |
|------|------|
| [installation.md](references/installation.md) | 安装与初始化 |
| [autonomous-agent.md](references/autonomous-agent.md) | 子 agent 模式 |
| [constitution-guide.md](references/constitution-guide.md) | 宪法模板指南 |
| [acceptance-protocol.md](references/acceptance-protocol.md) | 验收协议规范 |
| [git-version-control.md](references/git-version-control.md) | Git 版本控制 |
| [dependency-installation.md](references/dependency-installation.md) | 依赖自动安装 |
| [troubleshooting.md](references/troubleshooting.md) | 问题排查 |

---

## ⚠️ 安全警告

### 风险评估

| 操作类型 | 风险等级 | 说明 |
|---------|---------|------|
| 环境变量 | 中 | 需要 ZHIPU_API_KEY（必需）、GITHUB_TOKEN（可选） |
| 自动安装 | 中 | 脚本会自动执行 npm install、pip install、apt install |
| Git 操作 | 中 | 自动初始化仓库、提交、推送、创建 PR |
| 文件读写 | 低 | 操作 ~/.openclaw/ 和 ~/openclaw/workspace/ 目录 |
| 权限模式 | 高 | 推荐使用 acceptEdits，bypassPermissions 仅限隔离环境 |

### 使用建议

**✅ 推荐做法**：
- 在 VM/容器中运行
- 使用测试令牌，避免生产凭据
- 使用

acceptEdits

 模式，人工审核 bash 脚本
- 定期备份

~/openclaw/workspace/

 目录

**❌ 避免操作**：
- 在生产服务器使用

bypassPermissions`

- 使用高权限 GitHub 令牌
直接运行未经审查的网络脚本

监控工具：见 references/monitoring.md

SDD 开发工作流 Skill

快速开始：见下方 | 安装指南：references/installation.md | 问题排查：references/troubleshooting.md

🎯 核心理念

用规范驱动开发（SDD）把需求变成结构化的规范文档，让 LLM 在准确上下文中输出更符合预期的代码。

三大原则：规范优先 → 规范锚定 → 规范作为源

⚡ 快速开始

bash

环境检查

~/.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 工作流

bash
/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 初始化	Specify	特性分支	验收后
新项目	✅ 需要	✅ 初始化	自动创建	推送 + PR
迭代

❌ 跳过 | ✅ 新迭代 | 自动创建 | 推送 + PR |

项目初始化（仅新项目）

⚠️ 询问用户：GitHub 仓库如何处理？

选项 1：新建仓库
bash
gh repo create my-project --private --clone
cd my-project

选项 2：关联现有仓库
bash
git init
git remote add origin https://github.com/user/existing-repo.git

然后执行 Specify init（仅一次）：
bash
specify init . --here --ai claude --force --no-git

迭代开发（跳过项目初始化）

已初始化项目，直接创建新迭代：

- 跳过 GitHub 初始化
跳过 specify init
直接在 Claude Code 执行：/speckit.specify <功能描述>

Specify 序号自动递增：
bash

检测下一个序号

next_num=$(~/.openclaw/skills/sdd-dev-workflow/scripts/get-next-iteration.sh)
iterationname=${nextnum}-new-feature

问题修复：Specify CLI 创建迭代时序号可能重复（001-xxx, 001-yyy），使用 get-next-iteration.sh 自动检测最大序号 + 1。

🔒 Git 版本控制（强制）

AI 开发不确定性高 → Git 是安全网

初始化检查

触发条件：项目目录不存在 .git 文件夹

bash

检查并初始化

if [ ! -d .git ]; then
# 询问 Git 仓库地址或使用默认
git init
git add .
git commit -m chore: 初始化项目结构
fi

提交规范

每个阶段完成后必须提交：

阶段	提交信息
constitution	docs: 添加项目宪法
specify

bash

每个阶段完成后执行

git add . && git commit -m

验收后自动 PR

触发条件：验收通过 + 特性分支（非 main）

bash

检查验收结果

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

详见：references/git-version-control.md

📦 依赖自动安装（零注意力）

完成开发，不为工具停顿

两层依赖策略

Layer	类型	处理方式
Layer 1	预装依赖	环境检查脚本验证
Layer 2

项目依赖 | 遇到时自动安装 |

自动安装逻辑

bash

检测到 ModuleNotFoundError 时自动执行

if error contains ModuleNotFoundError: No module named fastapi; then
pip install fastapi
fi

不询问，直接安装。

预装依赖检查

bash
~/.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

非交互模式：
bash
specify init . --here --ai claude --force --no-git

后续所有 /speckit 命令都在 Claude Code 内执行。

权限模式选择

模式	用途	行为	安全等级
acceptEdits	人工监督开发	文件编辑自动批准，bash脚本需确认	✅ 推荐
bypassPermissions

自动化 agent | 所有操作自动批准 | ⚠️ 仅限隔离环境 |

安全建议：

- 生产环境 → acceptEdits + 人工审核
隔离测试环境 → bypassPermissions（VM/容器）
禁止：在生产服务器使用 bypassPermissions

最终目标

❌ 错误理解	✅ 正确理解
生成 spec.md	完成代码实现
生成 plan.md

通过测试验证 | | 生成 tasks.md | 功能可以运行 |

完成标准：

- ✅ 代码已实现（不是文档）
✅ 测试已通过
✅ 功能可运行

🚨 子 Agent 强制规则（CRITICAL）

核心原则：子 agent = 流程驱动器（driver），不是代码实现者（implementer）

绝对禁止

- ❌ 禁止使用 write 工具写代码文件（src//.py, tests//.py）
❌ 禁止跳过 /speckit.* 命令

必须执行

- ✅ 必须通过 sdd-driver.sh 脚本操作
✅ 必须通过 tmux 驱动 Claude Code

意外处理

情况	可恢复	行动
429 rate limit	✅	等待 5 分钟后重试
timeout

详见：references/autonomous-agent.md

📋 Speckit 工作流

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

sdd-dev-workflow规范驱动工作流

sdd-dev-workflow

SDD 开发工作流 Skill

🎯 核心理念

⚡ 快速开始

Speckit 工作流

🔄 迭代开发流程

流程对比

项目初始化（仅新项目）

迭代开发（跳过项目初始化）

🔒 Git 版本控制（强制）

初始化检查

提交规范

验收后自动 PR

📦 依赖自动安装（零注意力）

两层依赖策略

自动安装逻辑

预装依赖检查

⚠️ 工具链协作方式（必读）

Specify CLI 的角色

权限模式选择

最终目标

🚨 子 Agent 强制规则（CRITICAL）

绝对禁止

必须执行

意外处理

📋 Speckit 工作流

人类介入点

在 Claude Code 中引用公共宪法

✅ 正式项目

✅ 临时项目

❌ 错误：在 workspace 根目录创建

SDD 开发工作流 Skill

🎯 核心理念

⚡ 快速开始

环境检查

创建项目

启动开发

Speckit 工作流

🔄 迭代开发流程

流程对比

项目初始化（仅新项目）

迭代开发（跳过项目初始化）

检测下一个序号

🔒 Git 版本控制（强制）

初始化检查

检查并初始化

提交规范

每个阶段完成后执行

验收后自动 PR

检查验收结果

测试结果

📦 依赖自动安装（零注意力）

两层依赖策略

自动安装逻辑

检测到 ModuleNotFoundError 时自动执行

预装依赖检查

⚠️ 工具链协作方式（必读）

Specify CLI 的角色

权限模式选择

最终目标

🚨 子 Agent 强制规则（CRITICAL）

绝对禁止

必须执行

意外处理

📋 Speckit 工作流

标签

通过对话安装

方式一：安装 SkillHub 和技能

方式二：设置 SkillHub 为优先技能安装源

通过命令行安装

下载

相关推荐

self-improvement

self-improvement

self-improvement

self-improvement