kld-sdd

KLD SDD OpenSpec 项目初始化工具 - 一键初始化 AI 编辑器命令与技能，支持完整的 SDD（规格驱动开发）研发工作流。

这是什么？

SDD（Specification-Driven Development） 是一种以文档链驱动 AI 编码的研发方法：先写清楚"要做什么"，再让 AI 去实现，避免 AI 乱猜、反复返工。

kld-sdd 帮你在项目中一键配置好这套工作流所需的全部 AI 命令和技能，支持 Cursor、Claude Code、CodeBuddy 三种编辑器。

快速开始

# 在你的项目目录下执行
npx kld-sdd

初始化完成后，打开你的 AI 编辑器，就能用 /opsx:* 命令开始工作了。

核心工作流：5 个命令

初始化后，你会得到以下 6 个 /opsx:* 命令，按顺序使用：

propose → spec → design → task → check
                                    ↓
                              skill（独立使用）

第一步：/opsx:propose <变更名称>

做什么：创建业务意图文档，明确"为什么要做这件事"。

适合场景：需求评审后，把产品需求转化为结构化的业务意图文档。

AI 会做什么：

• 如果你没说清楚，AI 会主动问你 4 个问题（痛点/目标/影响模块/约束）
• 推导出变更的 kebab-case 名称，如 add-user-auth
• 生成 propose.md 并展示摘要让你确认

产出：openspec/changes/<name>/propose.md

第二步：/opsx:spec <变更名称>

做什么：创建技术契约文档，明确"要实现什么 API 和规范"。

这是代码生成的唯一依据，必须精确无歧义。

AI 会做什么：

• 读取 propose.md，检查上下文是否完整
• 发现模糊描述时主动追问（如"高性能"→ 具体 QPS/RT 是多少？）
• 向你确认 API 范围、性能指标、安全要求后，生成 spec.md

质量红线（AI 自检）：

• 所有参数有类型、必填标记、范围约束、示例值
• 性能指标是具体数字（如 < 100ms P99）
• 边界场景覆盖正常流程 + 所有异常流程

产出：openspec/changes/<name>/spec.md

第三步：/opsx:design <变更名称>

做什么：创建技术实现方案，明确"怎么做"（聚焦本业务，不写全局架构）。

AI 会做什么：

• 读取 propose.md + spec.md，分析约束和设计难点
• 若存在多种实现方案，列出方案让你选择
• 生成 design.md（包含时序图、模块设计、数据表结构、异常处理）

质量红线（AI 自检）：

• 不写全局中间件或框架选型（那是项目级别的事）
• 接口调用明确到具体接口名和调用方式
• 数据库表结构到字段级别（类型、长度、索引）

产出：openspec/changes/<name>/design.md

第四步：/opsx:task <变更名称>

做什么：将 design.md 拆解为 AI 可执行的原子任务列表。

每个任务的标准：AI 能在 5 分钟内完成。

AI 会做什么：

• 统计需要覆盖的实现点（API 数量、模块数量、数据表数量）
• 预估任务总数，确认拆解策略后再执行
• 发现任务风险（循环依赖、复杂算法）时主动告知

质量红线（AI 自检）：

• 100% 覆盖 spec.md 的每个 API 和约束
• 100% 覆盖 design.md 的每个模块和接口
• 每个任务有明确验收标准和单测要求

产出：openspec/changes/<name>/task.md

第五步：/opsx:check <变更名称>

做什么：质量门禁检查，验证文档链的完整性、一致性和可执行性。

在让 AI 写代码之前，先运行这个命令。

检查内容： | 检查项 | 说明 | |-------|------| | 完整性 | 4 个文档是否存在，每个文档章节是否完整 | | 一致性 | spec 的 API 在 design 中是否有对应方案；各文档字段命名是否一致 | | 可执行性 | task 的每个任务是否可独立执行；验收标准是否可验证 |

发现问题时，AI 会列出严重问题和警告，并提供三种处理方式供你选择。

独立使用：/opsx:skill <文档路径>

做什么：把你的团队规范文档（代码规范、API 设计规范等）转化为标准的 Claude Skills 格式技能文件，让 AI 每次都遵守你的团队规范。

适合场景：

• 把公司 Java 编码规范文档 → 生成 java-code-style 技能
• 把 API 设计规范文档 → 生成 api-design-rules 技能
• 把架构规范文档 → 生成 arch-guidelines 技能

AI 会做什么：

1. 读取你的规范文档，提炼四类规则（必须/禁止/推荐/例外）
2. 识别规则模糊或冲突时，向你澄清
3. 生成带 YAML frontmatter 的标准 SKILL.md
4. 你确认输出路径后写入

预置技能：opsx-sdd

初始化后，opsx-sdd 技能会自动部署到你的编辑器技能目录（.*/skills/opsx-sdd/）。

激活后，AI 会化身 SDD 工作流专家，检测当前项目的文档状态，引导你从当前进度继续：

"当前项目变更：

• add-user-auth：propose✓ spec✓ design○ task○（建议下一步：design）

请选择：A. 继续 / B. 创建新变更 / C. 质量检查"

安装与初始化

方式一：npx（推荐，无需全局安装）

cd your-project
npx kld-sdd

方式二：全局安装

npm install -g kld-sdd
cd your-project
kld-sdd-init

初始化选项

kld-sdd-init                    # 完整初始化（推荐）
kld-sdd-init --skip-openspec    # 跳过 openspec 安装
kld-sdd-init --tool cursor      # 仅配置 Cursor
kld-sdd-init --tool claude      # 仅配置 Claude Code
kld-sdd-init --tool codebuddy   # 仅配置 CodeBuddy

初始化后的目录结构

your-project/
├── openspec-templates/              # openSpec 四文档参考模版
│   ├── propose.md
│   ├── spec.md
│   ├── design.md
│   └── task.md
├── team-configs/                    # 团队共享配置（纳入版本控制）
│   ├── cursor-commands/
│   ├── claude-commands/
│   └── codebuddy-commands/
├── .cursor/
│   ├── commands/opsx/               # opsx 命令（6个）
│   └── skills/opsx-sdd/             # 预置 SDD 技能
├── .claude/
│   ├── commands/opsx/               # opsx 命令（6个）
│   └── skills/opsx-sdd/             # 预置 SDD 技能
└── .codebuddy/
    ├── commands/opsx/               # opsx 命令（6个，JSON格式）
    └── skills/opsx-sdd/             # 预置 SDD 技能

支持的 AI 编辑器

| 编辑器 | 命令格式 | 技能支持 | 自动创建目录 | |-------|---------|---------|------------| | Cursor | .md | ✅ | 已存在时 | | Claude Code | .md | ✅ | 已存在时 | | CodeBuddy | .json | ✅ | 自动创建 |

CodeBuddy 的命令使用 JSON 格式，内容与 Cursor/Claude 完全一致，初始化时自动创建目录无需预先配置。

团队协作流程

架构师 / TL

1. 在项目中运行 kld-sdd-init 一次
2. 将团队规范文档放入 team-configs/ 目录
3. 用 /opsx:skill 把规范转为技能，放入 team-configs/skills/
4. 提交到 Git

新成员 onboarding

git clone <project>
npm install
npx kld-sdd   # 一键配置好所有 AI 工具

之后直接在编辑器中使用 /opsx:propose 开始工作。

.gitignore 配置

初始化时自动添加：

# KLD SDD 个人配置 (保留团队配置)
.cursor/commands/personal-*
.claude/commands/personal-*
.codebuddy/commands/personal-*

# 但保留团队配置的占位目录
!.cursor/commands/team-*
!.claude/commands/team-*
!.codebuddy/commands/team-*

常见问题

Q：openspec 是什么，必须安装吗？

A：openspec 是管理 SDD 变更目录的 CLI 工具（负责创建变更目录和读取指导规则）。初始化时会自动安装，如果安装失败也可以跳过（--skip-openspec），手动创建 openspec/changes/<name>/ 目录后命令仍然可用。

Q：我用 CodeBuddy，目录不存在怎么办？

A：不用担心，kld-sdd-init 会自动创建 .codebuddy/commands/opsx/ 和 .codebuddy/skills/opsx-sdd/ 目录。

Q：/opsx:propose 和直接让 AI 写代码有什么区别？

A：直接让 AI 写代码，AI 会凭空假设很多细节，导致返工。SDD 流程强制先把"要做什么"写清楚，AI 按契约实现，减少歧义和返工。

Q：团队规范已经有了，怎么让 AI 每次都遵守？

A：用 /opsx:skill <规范文档路径> 把规范文档转成技能文件，部署到 .*/skills/ 目录后，AI 编辑器激活该技能时会自动遵守这些规范。

License

MIT