SDD 开发工作流 Skill

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

🎯 核心理念

用规范驱动开发（SDD）把需求变成结构化的"规范文档"，让大语言模型在相对准确且完整的上下文中，收敛注意力，提供更符合预期的输出。

三大原则

规范优先（Spec First）：开发前先编写规范，确保方向一致
规范锚定（Spec Anchored）：规范持续演进，作为长期资产
规范作为源（Spec as Source）：规范是主要源文件，代码由规范驱动生成

⚡ 快速开始

环境检查

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

详见：references/installation.md

创建项目

# 正式项目
~/.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

Speckit 工作流

在 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 的角色

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`	人工监督开发	文件编辑自动批准，bash脚本需确认
`bypassPermissions`	自动化 agent	所有操作自动批准（谨慎使用）

最终目标

❌ 错误理解	✅ 正确理解
生成 spec.md	完成代码实现
生成 plan.md	通过测试验证
生成 tasks.md	功能可以运行

完成标准：

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

🚨 子 Agent 强制规则（CRITICAL）

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

绝对禁止

❌ 禁止使用 write 工具写代码文件（src/**/*.py, tests/**/*.py）
❌ 禁止使用 write 工具创建 constitution/spec/plan/tasks
❌ 禁止跳过 /speckit. 命令*
❌ 禁止直接实现代码

必须执行

✅ 必须通过 sdd-driver.sh 脚本操作
✅ 必须通过 tmux 驱动 Claude Code
✅ 必须监控脚本输出并判断意外情况
✅ 必须尝试自动修复常见错误

意外处理原则

情况	可恢复	子 agent 行动
429 rate limit	✅	等待 5 分钟后重试
timeout	✅	检查输出，重启会话或增加超时
stuck（输出无变化）	✅	重启会话
execution_error	✅	让 Claude Code 修复
template_missing	❌	通知人工
session_not_found	❌	通知人工
需要补充上下文	❌	通知人工

通知人工的条件

核心原则：尝试过且无法解决，或需要补充上下文 → 通知人工等待响应

只有在以下情况才通知人工：

无法自动修复（error.recoverable = false）
需要补充上下文（需求不明确、技术选型需决策）
多次重试失败（同类型错误超过 3 次）

不要：

❌ 在尝试前就通知
❌ 重复通知相同问题
❌ 等待人工响应时继续执行

详见：references/autonomous-agent.md

📋 Speckit 工作流

工作流概览

┌─────────────────────────────────────────────────────────────┐
│                    Speckit 工作流                            │
├─────────────────────────────────────────────────────────────┤
│  1. init          → 初始化项目结构                           │
│  2. constitution  → 建立项目宪法（工程原则）                  │
│  3. specify       → 编写功能规范（what & why）               │
│  4. clarify       → 需求澄清（消除歧义）⚠️ 强制执行 ≥1 次    │
│  5. plan          → 生成实现计划（how）                      │
│  6. tasks         → 拆分任务（可执行单元）                   │
│  7. analyze       → 一致性分析（质量门禁）⚠️ 强制执行 ≥1 次  │
│  8. implement     → 自动实施（代码生成）                     │
└─────────────────────────────────────────────────────────────┘

⚠️ 强制阶段（不可跳过）：

clarify：必须执行至少 1 次（推荐 2 次）
analyze：必须执行至少 1 次（推荐 2 次）

🤝 人类介入点（Human Checkpoints）

阶段	介入原因	介入方式
clarify	需求歧义需要澄清	发送问题 → 等待回复
analyze	一致性问题需要决策	发送报告 → 等待确认
implement	大规模代码变更	可选：发送摘要 → 等待确认

介入判断逻辑

clarify/analyze 发现问题
       │
       ▼
  信息是否完整？
       │
    ┌──┴──┐
  完整   不完整/疑义
    │       │
    ▼       ▼
 自己决策  转发用户
 补充规范  等待回复
 继续执行  收到后继续

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

信息完整，只是细节缺失
常规技术选择（如用 requests 还是 httpx）
宪法已有明确规定
clarify 连续 2 次无问题
简单项目，需求明确

需要介入的条件

多个方案各有优劣，需要业务决策
需求有明显矛盾或冲突
涉及外部依赖或资源
超出宪法规定的边界
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

🚀 使用子 Agent（推荐）

标准流程

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

核心问题

长时间运行 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/（测试）