# ai-sdd

**Repository Path**: wujunyu111/ai-sdd

## Basic Information

- **Project Name**: ai-sdd
- **Description**: 一个 Spec-Driven Development（规格驱动开发）工具包
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-07-22
- **Last Updated**: 2026-10-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# ai-sdd

**先想清楚要做什么，再让 AI 动手写。**

面向 Cursor、Codex 与 Claude Code 的 Spec-Driven Development（规格驱动开发）工具包：安装一组 skills / agents，把「探索 → 设计 → 实现 → 验收 → 归档」变成可重复的流程，而不是每次靠聊天临时发挥。

| 你需要 | 用这个 |
|--------|--------|
| 在 Cursor 里跑完整 SDD | `sdd init --host cursor` |
| 在 Codex 里跑完整 SDD | `sdd init --host codex` |
| 在 Claude Code 里跑完整 SDD | `sdd init --host claude-code` |
| 三宿主都装（cursor + codex + claude-code） | `sdd init --host all` |

---

## 解决什么问题

直接让 AI 写代码很容易，但常常会遇到：

- 目标没谈清就开写，做到一半才发现理解偏了
- 约定只活在某次对话里，换机器、换会话就断了
- 审查靠感觉，没有稳定的 diff / 证据可复现
- skill、脚本路径写死在本机，别人装不上

ai-sdd 把流程收成一个 npm 包：**规格落盘、阶段可重复、Cursor / Codex / Claude Code 对等安装。**

变更写在业务仓的 `design-docs/<功能名>/`；仓级行为真源在 `design-docs/specs/`；做完后整夹移到 `archive/`——**目录在哪，状态就在哪。**

---

## 快速开始

**环境：** Node.js ≥ 18、Git、Cursor 和 / 或 Codex 和 / 或 Claude Code。

### 1. 安装 CLI

```bash
npm i -g ai-sdd --registry https://npm.wujunyu.top/
```

### 2. 注册到编辑器

```bash
# Cursor（用户级）
sdd init --host cursor --scope user --yes

# 或 Codex
sdd init --host codex --scope user --yes

# 或 Claude Code
sdd init --host claude-code --scope user --yes

# 或三者都装（cursor + codex + claude-code）
sdd init --host all --scope user --yes --force
```

新开一个对话，应能看到 `/ai-explore` 等 skill。

### 3. 在业务仓库里跑一轮

打开**你的业务项目**（不是必须在本仓库），按阶段触发。下面用「给应用加一个相册功能」举例：

**探索** — 先把目标和现状聊清楚（这一步不写文件）：

```text
/ai-explore
我想给应用加相册：按日期分组，可拖拽整理，相册不能嵌套。
帮我摸清现有代码，并列出还没想清楚的问题。
```

**设计** — 问清之后，写出三件套（有行为变更时再加 delta）：

```text
/ai-design photo-albums
```

会在 `design-docs/photo-albums/` 生成 `proposal.md` / `design.md` / `task.md`（`task` 含「合格标准」列）。若有用户可见行为变更，另写可选 `specs/<domain>/spec.md`（行为 delta）。**新变更包不再写根 `spec.md`。**

**实现** — 按任务清单改代码：

```text
/ai-apply photo-albums
```

**验收** — 对照 task「合格标准」做交付检查：

```text
/ai-review photo-albums
```

**归档** — 通过后：若有 delta 则经 specs-merge agent 预览并确认写入（或 skip）进仓级活 specs，再整夹搬走：

```text
/ai-archive photo-albums
```

每一阶段结束，agent 只会**建议**下一步，需要你自己触发下一个命令。探索阶段若还有未决问题，先别进 design。

---

## 工作流一览

```text
/ai-explore  →  澄清目标、摸现状（只对话）
     ↓
/ai-design   →  写入 design-docs/<slug>/ 三件套（+ 可选 delta）
     ↓
/ai-apply    →  按 task.md 实现
     ↓
/ai-review   →  按 task「合格标准」交付验收
     ↓
/ai-archive  →  （可选）specs-merge agent 写 design-docs/specs/
                 再移到 design-docs/archive/<slug>/
```

| 命令 | 做什么 | 产物 |
|------|--------|------|
| `/ai-explore` | 澄清目标与现状，问清未决问题 | 对话结论（不写 `design-docs/`） |
| `/ai-design <slug>` | 写规格并审查产物 | `proposal` / `design` / `task`（+ 可选 `specs/` delta） |
| `/ai-apply <slug>` | 按任务实现（可并行 worktree） | 代码变更 |
| `/ai-review <slug>` | 完整性 / 正确性 / 一致性验收 | 验收报告（主输入：合格标准） |
| `/ai-archive <slug>` | 确认后由 specs-merge agent 写活 specs，再归档 | `design-docs/specs/` + `archive/<slug>/` |

`sdd-review` 一般由验收相关 agent 自动调用，日常主路径不用手跑。  
工具向：`sdd specs list` 枚举仓级 domain（供 agent）；合并由 `/ai-archive` 的 specs-merge agent 完成（已无 merge/dry-run 命令）。

---

## 三种「规格」别混

| 是什么 | 路径 | 干什么 |
|--------|------|--------|
| **合格标准** | `design-docs/<slug>/task.md` 的「合格标准」列 | **本次变更交卷验收**（review 主输入） |
| **行为 delta** | `design-docs/<slug>/specs/<domain>/spec.md` | 相对仓级真源的增量，**只供 archive merge** |
| **活行为真源** | `design-docs/specs/<domain>/spec.md` | 跨功能累积的**长期行为约定** |

- 新变更包最低集：`proposal` + `design` + `task`（含合格标准）；**无根 `spec.md`**。
- 无用户可见行为变更时，可省略 `<slug>/specs/`。
- 写 delta 前先 `sdd specs list`：语义相符的 domain **必须复用**；没有相符的才新建（建议小写 kebab-case）。归档时由 specs-merge agent 做语义合并。
- 旧 archive / 历史夹里可能仍有根 `spec.md`，仅作备查，新流程不再创建、不再作验收真源。

---

## 设计怎么做的

四块拼在一起：

```text
  npm 包 ai-sdd
  ├─ templates/     skills + agents（流程真源）
  ├─ sdd            安装 / 更新 / 卸载 / specs
  └─ sdd-review     收集 diff + 扫描提示作审查证据
         │
         ▼  sdd init
  Cursor / Codex / Claude Code 里出现 /ai-* 
         │
         ▼  在业务仓执行
  design-docs/<slug>/     ← 活跃变更包（三件套 + 可选 delta）
  design-docs/specs/      ← 仓级活行为真源
  design-docs/archive/    ← 已归档
  ~/.ai-sdd/              ← 本机配置、状态、临时证据
```

Cursor、Codex 与 Claude Code **能力对等**：同一套阶段与角色；差异只在宿主适配（Cursor：Markdown agents + Task；Codex：TOML agents + spawn；Claude Code：Markdown skills/agents）。

---

## `sdd` 命令参考

| 命令 | 作用 |
|------|------|
| `sdd init` | 把 templates 注册到 Cursor / Codex / Claude Code |
| `sdd update` | 从配置的 npm 源更新包，并刷新已装模板 |
| `sdd uninstall` | 卸载 skills/agents；`--mode all` 可连同本机数据与全局包 |
| `sdd clean` | 清理 `~/.ai-sdd/temp` |
| `sdd specs list` | 工具向：枚举 `design-docs/specs/<domain>/`（供 agent；非 init/update 级用户主路径） |
| `sdd review …` | `sdd-review` 的别名 |
| `sdd help` | 帮助 |

`init` 常用参数：`--host cursor|codex|claude-code|all`、`--scope user|project`、`--yes`、`--force`。  
`specs list` 常用参数：`--repo <path>`。  
无参数时进入交互菜单。

**装到哪里：**

| Host | Scope | Skills | Agents |
|------|-------|--------|--------|
| cursor | user | `~/.cursor/skills/` | `~/.cursor/agents/` |
| cursor | project | `.cursor/skills/` | `.cursor/agents/` |
| codex | user | `~/.agents/skills/` | `~/.codex/agents/` |
| codex | project | `.agents/skills/` | `.codex/agents/` |
| claude-code | user | `~/.claude/skills` | `~/.claude/agents` |
| claude-code | project | `.claude/skills` | `.claude/agents` |

请勿把本机生成的 `.cursor/` / `.agents/` / `.codex/` / `.claude/` 提交进业务仓。

```bash
sdd update
sdd uninstall --mode skills --yes
```

---

## 项目结构

```
ai-sdd/
├── bin/
│   └── sdd.js                 # CLI 入口
├── src/
│   ├── cli/main.js            # CLI 主调度
│   ├── commands/              # 命令实现
│   │   ├── init.js            # 初始化
│   │   ├── update.js          # 更新
│   │   ├── uninstall.js       # 卸载
│   │   ├── clean.js           # 清理
│   │   └── specs.js           # specs 列表
│   ├── host/                  # 宿主适配
│   │   ├── cursor.js          # Cursor 安装
│   │   ├── codex.js           # Codex 安装
│   │   ├── detect.js          # 路径探测
│   │   └── uninstall.js       # 卸载
│   ├── registry.js            # 安装登记
│   ├── paths.js               # 路径管理
│   ├── config.js              # 配置管理
│   └── npmPkg.js              # npm 包操作
├── review/
│   ├── cli.js                 # review CLI
│   ├── diff.js                # diff 收集
│   ├── render.js              # 证据渲染
│   ├── schema.js              # 证据包 schema
│   └── scan/                  # 扫描规则
│       ├── index.js           # 扫描入口
│       ├── javaSpring.js      # Java Spring 规则
│       ├── jsVue.js           # JS/Vue 规则
│       ├── pythonRules.py     # Python 规则
│       └── secrets.js         # 密钥检测
├── templates/
│   ├── cursor/
│   │   ├── skills/            # Cursor skills
│   │   │   ├── ai-apply/
│   │   │   ├── ai-archive/
│   │   │   ├── ai-design/
│   │   │   ├── ai-explore/
│   │   │   └── ai-review/
│   │   └── agents/            # Cursor agents
│   └── codex/
│       ├── skills/            # Codex skills
│       └── agents/            # Codex agents
├── design-docs/
│   ├── specs/                 # 仓级活规格
│   │   ├── sdd-cli/spec.md
│   │   ├── sdd-docs/spec.md
│   │   ├── sdd-review/spec.md
│   │   ├── workflow-skills/spec.md
│   │   └── npm-registry/spec.md
│   └── archive/               # 已归档变更
├── fixtures/
│   └── sample-repo/           # 测试用迷你仓库
├── deploy/
│   └── npm-registry/          # 私有 npm 源部署
└── scripts/
    ├── smoke-specs.js         # specs 冒烟测试
    ├── smoke-temp-clean.js    # temp 清理测试
    ├── smoke-update-uninstall.js # 更新卸载测试
    └── smoke-global-isolated.js # 全局隔离测试
```

---

## 附录：贡献者

从源码试用：

```bash
git clone <本仓库>
cd ai-sdd
npm link
sdd init --host cursor --scope user --yes --force
npm run smoke
```

**开发命令：**

```bash
npm run test        # 单元测试
npm run smoke       # 冒烟测试
npm run lint        # 代码检查
```

发布文件面见 `package.json` → `files`。  
私有源搭建见 [`deploy/npm-registry/README.md`](deploy/npm-registry/README.md)。