kld-sdd

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

这是什么？

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

kld-sdd 帮你在项目中一键配置好这套工作流所需的全部 AI 技能，支持 Cursor、Claude Code、CodeBuddy、Qoder、OpenCode、KunlunZhima、WorkBuddy、Codex 等编辑器。

快速开始

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

初始化完成后，打开你的 AI 编辑器，激活 opsx-* skills 开始工作。

核心工作流：5 个 skills

初始化后，你会得到以下 SDD skills，按顺序使用：

opsx-propose → opsx-spec → opsx-design → opsx-task → opsx-check
                                                          ↓
                                                    opsx-knowledge（独立使用）

第一步：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 写代码之前，先激活这个 skill。

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

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

独立使用：opsx-knowledge

做什么：查询 MM/CO 业务知识库，辅助理解业务名词和领域规则。

预置技能

初始化后，SDD 全套 skill 部署为 扁平一层（Claude Code 识别规则）：

.claude/skills/opsx-propose/SKILL.md   → /opsx-propose
.claude/skills/opsx-spec/SKILL.md      → /opsx-spec
...

模板源码组织在 kld-sdd/templates/skills/kld-sdd/（仅用于打包维护，不是 Claude 的识别路径）。

Claude Code 只识别 .claude/skills/<skill-name>/SKILL.md 这一层。嵌套在 skills/kld-sdd/opsx-* 下不会被 / 菜单发现。GitNexus 能识别是因为 npx gitnexus analyze 同时安装了 ~/.claude/skills/gitnexus-*/ 扁平 skill。

安装与初始化

方式一：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
kld-sdd-init --tool codex       # 仅配置 Codex

初始化后的目录结构

your-project/
├── openspec-templates/              # openSpec 四文档参考模版
│   ├── propose.md
│   ├── spec.md
│   ├── design.md
│   └── task.md
├── .cursor/
│   └── skills/opsx-*/               # SDD skills（扁平一层）
├── .claude/
│   └── skills/opsx-*/               # SDD skills（扁平一层）
├── .codebuddy/
│   └── skills/opsx-*/               # SDD skills（扁平一层）
└── .agents/
    └── skills/opsx-*/               # Codex 项目级 skills

支持的 AI 编辑器

| 编辑器 | 技能格式 | 技能支持 | 自动创建目录 | |-------|---------|---------|------------| | Cursor | SKILL.md | ✅ | 已存在时 | | Claude Code | SKILL.md | ✅ | 已存在时 | | CodeBuddy | SKILL.md | ✅ | 自动创建 | | Qoder | SKILL.md | ✅ | 自动创建 | | OpenCode | SKILL.md | ✅ | 自动创建 | | KunlunZhima | SKILL.md | ✅ | 自动创建 | | WorkBuddy | SKILL.md | ✅ | 自动创建 | | Codex | SKILL.md（.agents/skills/） | ✅ | 自动创建 |

Codex 初始化会创建 .agents/skills/opsx-*/，用于项目级技能。

团队协作流程

架构师 / TL

1. 在项目中运行 kld-sdd-init 一次
2. 将团队规范文档放入 team-configs/ 目录
3. 将自定义 skills 放入 .*/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-*
.agents/commands/personal-*

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

常见问题

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

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

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

A：不用担心，kld-sdd-init 会自动创建 .codebuddy/skills/、.agents/skills/ 等目录。

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

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

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

A：将规范文档转为 skill 文件，部署到 .*/skills/ 目录后，AI 编辑器激活该 skill 时会自动遵守这些规范。

License

MIT