规范驱动开发工作流(SDD + Speckit + Claude Code)。用于复杂软件开发项目,包含完整的规范驱动开发流程、Claude Code 交互式操作、开发最佳实践。当用户需要开发复杂应用、进行多迭代开发项目时使用此 skill。
快速开始:见下方 | 安装指南:references/installation.md | 问题排查:references/troubleshooting.md
用规范驱动开发(SDD)把需求变成结构化的"规范文档",让大语言模型在相对准确且完整的上下文中,收敛注意力,提供更符合预期的输出。
~/.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
# 临时项目
~/.openclaw/skills/sdd-dev-workflow/scripts/init-project.sh test-xyz --tmp
cd ~/openclaw/workspace/tmp/test-xyz
claude --permission-mode acceptEdits
在 Claude Code 中执行:
/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
Specify CLI → Claude Code → 完成开发
(仅用于初始化) (执行 /speckit 命令) (代码实现)
Specify CLI 仅用于初始化:
specify init 初始化项目结构(每个项目执行一次)非交互模式:
specify init . --here --ai claude --force --no-git
后续所有 /speckit 命令都在 Claude Code 内执行。
| 模式 | 用途 | 行为 |
|---|---|---|
acceptEdits | 人工监督开发 | 文件编辑自动批准,bash脚本需确认 |
bypassPermissions | 自动化 agent | 所有操作自动批准(谨慎使用) |
推荐:
acceptEditsbypassPermissions(需要额外安全措施)| ❌ 错误理解 | ✅ 正确理解 |
|---|---|
| 生成 spec.md | 完成代码实现 |
| 生成 plan.md | 通过测试验证 |
| 生成 tasks.md | 功能可以运行 |
完成标准:
核心原则:子 agent = 流程驱动器(driver),不是代码实现者(implementer)
write 工具写代码文件(src/**/*.py, tests/**/*.py)write 工具创建 constitution/spec/plan/taskssdd-driver.sh 脚本操作| 情况 | 可恢复 | 子 agent 行动 |
|---|---|---|
| 429 rate limit | ✅ | 等待 5 分钟后重试 |
| timeout | ✅ | 检查输出,重启会话或增加超时 |
| stuck(输出无变化) | ✅ | 重启会话 |
| execution_error | ✅ | 让 Claude Code 修复 |
| template_missing | ❌ | 通知人工 |
| session_not_found | ❌ | 通知人工 |
| 需要补充上下文 | ❌ | 通知人工 |
核心原则:尝试过且无法解决,或需要补充上下文 → 通知人工等待响应
只有在以下情况才通知人工:
不要:
详见:references/autonomous-agent.md
┌─────────────────────────────────────────────────────────────┐
│ Speckit 工作流 │
├─────────────────────────────────────────────────────────────┤
│ 1. init → 初始化项目结构 │
│ 2. constitution → 建立项目宪法(工程原则) │
│ 3. specify → 编写功能规范(what & why) │
│ 4. clarify → 需求澄清(消除歧义)⚠️ 强制执行 ≥1 次 │
│ 5. plan → 生成实现计划(how) │
│ 6. tasks → 拆分任务(可执行单元) │
│ 7. analyze → 一致性分析(质量门禁)⚠️ 强制执行 ≥1 次 │
│ 8. implement → 自动实施(代码生成) │
└─────────────────────────────────────────────────────────────┘
⚠️ 强制阶段(不可跳过):
| 阶段 | 介入原因 | 介入方式 |
|---|---|---|
| clarify | 需求歧义需要澄清 | 发送问题 → 等待回复 |
| analyze | 一致性问题需要决策 | 发送报告 → 等待确认 |
| implement | 大规模代码变更 | 可选:发送摘要 → 等待确认 |
clarify/analyze 发现问题
│
▼
信息是否完整?
│
┌──┴──┐
完整 不完整/疑义
│ │
▼ ▼
自己决策 转发用户
补充规范 等待回复
继续执行 收到后继续
# 在 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/ # 日期日记
| 类型 | 路径 | 示例 |
|---|---|---|
| 正式项目 | projects/<name>/ | projects/my-app/ |
| 临时项目 | tmp/<name>/ | tmp/test-workflow/ |
| 研究报告 | research/<topic>/ | research/ai-sovereignty/ |
# ✅ 正式项目
~/.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 # 错误!
目标:完成开发,不为依赖停顿
遇到依赖缺失 → 直接安装,不询问
# 运行时缺少依赖
ModuleNotFoundError: No module named 'redis'
→ 直接执行:pip install redis
sessions_spawn({
task: `
开发 [项目描述]
## 🚨 强制规则
**角色定位**:你是流程驱动器(driver),不是代码实现者
**绝对禁止**:
- ❌ 使用 \`write\` 工具直接写代码文件(\`src/**/*.py\`, \`tests/**/*.py\`)
- ❌ 跳过 SDD 流程阶段
**必须执行**:
- ✅ 通过 tmux 在 Claude Code 中执行自然语言指令
- ✅ 监控执行输出,处理交互问题
- ✅ 遇到权限提示 → 选择 "bypassPermissions"
- ✅ 尝试自动修复可恢复错误
- ✅ 仅在无法修复或需要补充上下文时通知人工
## ⏱️ GLM-5 响应等待(关键)
**高峰期响应慢**:GLM-5 在高峰期(12:00-18:00 GMT+8)响应可能需要 1-5 分钟
**等待规则**:
- ⏱️ 使用 \`process\` 工具时,设置 \`timeoutMs: 300000\`(5分钟)
- ⏱️ 等待 Claude Code 响应时,**不要在 30 秒内判定为超时**
- ⏱️ 如果超过 5 分钟仍无响应 → 通知人工
## Agent 驱动流程(SDD 阶段)
\`\`\`bash
# 1. 初始化项目(如需要)
cd ~/openclaw/workspace/tmp/[project-name]
# Specify CLI 会自动初始化(90秒超时 + 降级方案)
# 2. 启动 Claude Code(bypassPermissions 模式)
tmux -S /tmp/openclaw-tmux-sockets/claude-code.sock new-session -d -s [session-name]
tmux -S /tmp/openclaw-tmux-sockets/claude-code.sock send-keys -t [session-name] 'cd [project-path] && claude --permission-mode bypassPermissions' Enter
# 3. 等待 Claude Code 启动
sleep 10
# 4. 逐阶段执行(用自然语言指令)
tmux send-keys '阅读并应用项目宪法规范' Enter
sleep 10
tmux send-keys '/speckit.specify [功能需求描述]' Enter
sleep 30
tmux send-keys '/speckit.clarify' Enter
sleep 30
tmux send-keys '/speckit.plan' Enter
sleep 30
tmux send-keys '/speckit.tasks' Enter
sleep 30
tmux send-keys '/speckit.analyze' Enter
sleep 30
tmux send-keys '/speckit.implement' Enter
sleep 60
# 5. 验收测试(直接执行)
python3 -m py_compile src/main.py
cd [project-path] && pytest tests/ -v
cd [project-path] && timeout 5 uvicorn src.main:app || true
\`\`\`
## 完成标准
- ✅ 代码已实现(不是文档)
- ✅ 测试已通过(至少 1 个核心测试)
- ✅ 功能可运行(服务能启动)
`,
agentId: "dev-agent",
runTimeoutSeconds: 7200
})
详见:references/autonomous-agent.md
长时间运行 Agent 面临的挑战:
| 挑战 | 说明 |
|---|---|
| 上下文丢失 | Context window 溢出,忘记之前的工作 |
| 进度中断 | 网络断开、服务重启导致任务中断 |
| 状态不可知 | 不知道任务执行到哪一步 |
| 无法恢复 | 中断后无法从断点继续 |
所有项目默认支持断点续传:
.task-context/
├── progress.json # 进度跟踪
├── checkpoint.md # 检查点快照
└── session-log.md # 会话日志(可选)
sessions_spawn({
task: "继续开发 [项目名],读取 .task-context/checkpoint.md 恢复上下文",
agentId: "dev-agent",
runTimeoutSeconds: 7200
})
Heartbeat 会自动检查所有 in_progress 任务的进度,发现异常时通知。
┌─────────────────────────────────────────┐
│ 质量门禁 │
├─────────────────────────────────────────┤
│ clarify → 连续2次无问题 │
│ analyze → 连续2次无问题 │
│ implement → 每阶段测试通过 │
└─────────────────────────────────────────┘
| 场景 | 处理方式 |
|---|---|
| 需求变更 | 开启新迭代周期,新建分支 |
| Bug 修复 | Agent 实现导致的 → 直接 prompt 修复<br>规范问题 → 新迭代 |
| 功能扩展 | 新迭代,MVP 先行 |
| 上下文丢失 | 规范文档是锚点,不依赖对话 |
标准 SDD 项目包含:.specify/memory/constitution.md(宪法)、specs/(规范)、src/(代码)、tests/(测试)
详见:references/constitution-guide.md
pip install <module>| 文档 | 用途 |
|---|---|
| installation.md | 安装与初始化 |
| autonomous-agent.md | 子 agent 模式 |
| constitution-guide.md | 宪法模板指南 |
| troubleshooting.md | 问题排查 |
本 skill 使用 bypassPermissions 模式(跳过权限检查),仅在受信任环境使用。
# 检查 session 状态
~/.openclaw/skills/sdd-dev-workflow/scripts/monitor-task.sh check <project> <session_id>
~/.openclaw/skills/sdd-dev-workflow/scripts/monitor-task.sh all # 检查所有
判断:✅ 正常 | 🐢 缓慢(<5行/分钟) | ⚠️ 卡住(10分钟无增长)
ZIP package — ready to use