# AdSpecs — AI 工程研发协同插件

[![npm version](https://img.shields.io/npm/v/adspecs)](https://www.npmjs.com/package/adspecs)
[![npm downloads](https://img.shields.io/npm/dt/adspecs)](https://www.npmjs.com/package/adspecs)
[![Platform](https://img.shields.io/badge/platform-Claude%20Code%20%7C%20Qoder%20%7C%20WorkBuddy-blueviolet)](#安装)

---

## 简介

AdSpecs 是一个支持 **Claude Code**、**Qoder** 和 **WorkBuddy** 三平台的 AI 工程研发协同插件，提供：

- **30 个 Skill**（Slash 命令） — 覆盖需求分析、架构规划、系统设计、任务拆解、单元测试、代码审查、原型生成、文档导出、Wiki 同步
- **CLI 工具** — `adspecs init` 一键脚手架、`adspecs plugin install` 插件注册、`adspecs doctor` 环境检查
- **21 个标准文档模板** — 需求 / 设计 / 任务 / 测试 / 评审 / 架构全覆盖
- **多技术栈参考** — Java 后端、Vue 3 前端、Ant Design React 前端、Python 后端等 9 套参考工程
- **三平台支持** — 原生兼容 Claude Code、Qoder 和 WorkBuddy，自动检测运行环境
- **npm 分发** — `npm install -g adspecs` 即装即用

> **平台依赖说明**：
> - **Claude Code**：需配合 [`superpowers`](https://github.com/anthropics/claude-plugins-official) 插件（提供 TDD、子代理驱动开发等通用 Skill）一起使用
> - **Qoder / WorkBuddy**：adspecs 的 Skills 可独立运行，无需额外依赖

---

## 项目结构

```
adspecs/
├── bin/adspecs.js                  # CLI 入口
├── src/                            # CLI 核心代码
│   ├── commands/                   #   init / plugin / doctor / update
│   └── lib/                        #   scaffolder / prompts / report 等
├── skills/                         # 30 个 Skill 定义
├── .claude-plugin/                 # Claude Code 插件清单
├── .qoder-plugin/                  # Qoder 插件清单
├── .codebuddy-plugin/              # WorkBuddy 插件清单（CodeBuddy 格式）
├── .workbuddy-plugin/              # WorkBuddy 插件清单（向后兼容）
├── .adspecs/
│   ├── templates/                  #   21 个标准文档模板
│   ├── extensions/                 #   扩展配置（git hooks 等）
│   ├── scripts/                    #   辅助脚本（bash/powershell/python）
│   ├── workflows/                  #   工作流定义
│   ├── feature.json                #   功能追踪模板（JSON，主数据源）
│   ├── feature.yml                 #   功能追踪人类可读视图（YAML，从 JSON 同步）
│   ├── session-logger.json         #   AI 会话日志触发器配置
│   ├── paths.json                  #   可自定义的输出路径配置
│   └── project.json                #   项目元数据模板
├── hooks/                          # Node.js 钩子脚本 + hooks.json
├── references/                     # 9 套参考工程与编码规范
├── assets/                         # README 配图资源
├── commands/                       # 保留（空）
├── scripts/                        # npm 生命周期脚本（postinstall/sync-version/prepublish-check）
├── package.json
├── CLAUDE.md
├── README.md
├── INSTALL.md
├── CHANGELOG.md
├── skill-help.md                   # Skill 详细使用说明
├── User-Manual.md                  # 用户手册
├── quickstar.md                    # 快速入门指南
├── help.md                         # 帮助文档
└── LICENSE
```

---

## 快速开始

## 安装与升级

详细安装说明见 [INSTALL.md](./INSTALL.md)。

### Claude Code

```bash
npm install -g adspecs
adspecs plugin install                    # 用户级（默认）
adspecs plugin install --scope project    # 项目级
```

### Qoder

```bash
npm install -g adspecs
adspecs plugin install --platform qoder              # 用户级
adspecs plugin install --platform qoder --scope project  # 项目级
```

### WorkBuddy

```bash
npm install -g adspecs
adspecs plugin install --platform workbuddy              # 用户级（推荐）
adspecs plugin install --platform workbuddy --scope project  # 项目级
```

> **说明**：WorkBuddy 通过 CodeBuddy 插件系统加载 adspecs。若未安装 codebuddy CLI，安装脚本会自动回退为手工配置方式（创建 marketplace 链接 + 写入 enabledPlugins）。

### 通用命令

```bash
# 升级
npm install -g adspecs@latest

# 卸载
adspecs plugin uninstall --scope user
adspecs plugin uninstall --scope project
```


### 初始化项目

```bash
# 交互式初始化
adspecs init
```

### 开始使用 Skill

```
/ads-new-requirement CRM 销售预测模块
/ads-prd docs/00-customer-requirements/...
/ads-plan docs/20-prd/crm/...
...
```


详细skill使用说明见 [skill-help.md](./skill-help.md)。

---

## CLI 工具

安装后提供 `adspecs` 命令行工具：

| 命令                       | 说明                                                  | 示例                                          |
| -------------------------- | ----------------------------------------------------- | --------------------------------------------- |
| `adspecs init`             | 交互式初始化项目结构（docs/、templates/、前端模板等） | `adspecs init --mode simple`                  |
| `adspecs plugin install`   | 注册为 AI 平台插件（自动检测或指定平台）              | `adspecs plugin install --platform workbuddy` |
| `adspecs plugin uninstall` | 从 AI 平台卸载插件                                    | `adspecs plugin uninstall --platform qoder`   |
| `adspecs doctor`           | 检查环境依赖（Node.js、git、Python 等）               | `adspecs doctor`                              |
| `adspecs update`           | 升级到最新版本                                        | `adspecs update --version 0.2.0`              |

### `adspecs init` 参数

| 参数                        | 说明                                                  | 默认值     |
| --------------------------- | ----------------------------------------------------- | ---------- |
| `--project-name <name>`     | 项目名称                                              | 交互输入   |
| `--project-dir <dir>`       | 项目目录（留空=当前目录）                             | 当前目录   |
| `--mode <mode>`             | 初始化模式：`simple` \| `classic` \| `full` \| `demo` | 交互选择   |
| `--front-demo <stack>`      | 前端演示技术栈：`vue` \| `antd`                       | `vue`      |
| `--company <name>`          | 公司名称                                              | —          |
| `--confidentiality <level>` | 文件密级：`公开` \| `内部资料` \| `机密` \| `绝密`    | `内部资料` |
| `--modules <list>`          | 后端模块列表（逗号分隔）                              | —          |
| `--non-interactive`         | 非交互模式，使用默认值                                | —          |
| `--force`                   | 已存在区域直接重建                                    | —          |
| `-y, --yes`                 | 自动确认执行                                          | —          |

---

## Skills 总览（30 个）

按职责分为六类：

### 一、项目初始化（CLI + Skill）

| 命令 / Skill    | 说明                                                                               |
| --------------- | ---------------------------------------------------------------------------------- |
| `adspecs init`  | CLI 交互式初始化项目结构：`docs/` 文档树、前端模板、后端模块、编码规范、标准模板等 |
| `/project-init` | Skill 版初始化（在 AI 会话中调用，等价于 `adspecs init`）                          |

初始化后生成：

- `docs/00-planning/` — 产品规划报告与路标
- `docs/00-customer-requirements/` — 业务需求分析文档
- `docs/10-architecture/` — 架构规划
- `docs/20-prd/` — 产品需求说明书
- `docs/30-system-design/` — 系统设计 + SQL + 前端设计 + 任务清单
- `docs/40-project_conventions/` — 编码规范（前端 + 后端）
- `docs/80-development/` — 开发日志、测试报告
- `docs/100-help/` — 帮助文档
- `docs/300-specs/` — 规格文档
- `wiki/` — Wiki 同步目标目录
- `.adspecs/templates/` — 21 个标准模板
- `.adspecs/paths.json` — 可自定义的输出路径配置

### 二、需求分析与架构规划（7 个）

| Skill                           | 说明                                             | 输入                | 输出                             |
| ------------------------------- | ------------------------------------------------ | ------------------- | -------------------------------- |
| `ads-new-requirement`       | 深度业务需求分析（六步结构 + 模拟评审）          | 业务需求描述        | `docs/00-customer-requirements/` |
| `ads-biz-blueprint`         | 将需求分析转化为 F1~F6 业务方案文件体系          | 业务需求分析文档    | `docs/00-customer-requirements/` |
| `ads-prd`                   | 从自然语言 / 调研材料生成 PRD                    | 调研材料 / 原始需求 | `docs/20-prd/`                   |
| `ads-clarify`               | 识别 PRD 模糊点（≤5 个）并澄清                   | 需求规格说明书      | 更新后的规格说明书               |
| `ads-architecture-planning` | 平台级架构规划（功能架构 → 模块依赖 → 数据建模） | 项目 / 业务描述     | `docs/10-architecture/`          |
| `ads-requirement-research`  | 需求溯源与调研，记录需求来源与关联               | 需求描述            | `docs/02-prd/`                   |
| `ads-constitution`          | 创建或更新项目章程，同步依赖模板                 | 项目原则 / 章程输入 | 项目章程文件                     |

### 三、SOW / 设计 / 任务 / 原型（7 个）

| Skill                     | 说明                                                | 输入               | 输出                                  |
| ------------------------- | --------------------------------------------------- | ------------------ | ------------------------------------- |
| `ads-write-sow`       | 根据项目 / 合同信息生成工作说明书                   | 项目 / 合同信息    | `docs/05-sow/`                        |
| `ads-plan`            | 后端统一系统设计（OOA+OOD）+ 建表 SQL               | PRD                | `docs/30-system-design/` design + SQL |
| `ads-front-spec`      | 前端功能设计（UI/交互规格）                         | PRD + 系统设计     | `docs/30-system-design/` 前端设计     |
| `ads-front-prototype` | 基于 PRD 生成可在 front-demo 中运行的完整页面原型   | PRD / 前端设计文档 | front-demo 可运行页面                 |
| `ads-prd-to-demo`     | 基于 PRD 输出可点击 Demo 设计方案（7 段式规划文档） | PRD / 需求分析     | Demo 设计规划文档                     |
| `ads-tasks`           | 后端 TDD 任务清单                                   | 系统设计文档       | `docs/30-system-design/` tasks.md     |
| `ads-front-tasks`     | 前端 TDD 任务清单                                   | 前端设计文档       | `docs/30-system-design/` tasks.md     |

### 四、质量保障与测试（4 个）

| Skill                        | 说明                                                                |
| ---------------------------- | ------------------------------------------------------------------- |
| `ads-analyze`            | 跨文档（PRD / 系统设计 / tasks）全链路 13 维一致性分析              |
| `ads-adversarial-review` | 对抗式审查：5 个红队角色挑战文档假设、缺失、矛盾与歧义              |
| `grill-me`                   | 深度追问与挑战，针对方案或设计进行尖锐提问                          |
| `ads-utest`              | 基于系统设计生成 Service / Controller 层 JUnit 5 单元测试代码及报告 |

### 五、交付与运维（9 个）

| Skill                    | 说明                                               |
| ------------------------ | -------------------------------------------------- |
| `ads-update-status`  | 更新 feature.json 功能状态 + 输出追踪矩阵          |
| `ads-export-word`    | Markdown 导出为 Word（.docx），自动生成封面 + 目录 |
| `ads-git-initialize` | 初始化 Git 仓库并完成首次提交                      |
| `ads-git-commit`     | 各阶段完成后自动提交变更                           |
| `ads-save-session`   | 保存当前 AI 会话为结构化 Markdown 日志             |
| `sie-front-code-review`  | 前端专项评审（React + TypeScript + Ant Design）    |
| `playwright-cli`         | 浏览器自动化交互、网页测试与 Playwright 测试       |
| `playwright-trace`       | 检查 Playwright trace 文件（操作、请求、截图等）   |
| `wiki-update`            | 将 docs/ 同步到 wiki/（全量 / 增量模式）           |

### 六、产品规划（2 个）

| Skill                           | 说明                                 |
| ------------------------------- | ------------------------------------ |
| `ads-write-planning-report` | 汇总调研期分析输出，生成产品规划报告 |
| `ads-write-roadmap`         | 版本路标维护，追写 roadmap.md        |

### 编码阶段依赖（superpowers 插件）

| 外部 Skill                       | 说明                             |
| -------------------------------- | -------------------------------- |
| `subagent-driven-development`    | 子代理驱动并行开发               |
| `test-driven-development`        | RED → GREEN → REFACTOR TDD 循环  |
| `verification-before-completion` | 完成前最终验证                   |
| `finishing-a-development-branch` | 分支收尾（PR / merge / cleanup） |

---

## 模板体系（21 个）

初始化后位于 `.adspecs/templates/`：

| 模板                         | 用途                        | 阶段 |
| ---------------------------- | --------------------------- | ---- |
| `01-业务需求分析模板.md`     | 业务需求分析（六步结构）    | 需求 |
| `02-产品需求说明书模板.md`   | 产品需求说明书（PRD）       | 需求 |
| `03-系统设计模板.md`         | 后端统一系统设计（OOA+OOD） | 设计 |
| `04-前端功能设计模板.md`     | 前端功能规格（UI/交互）     | 设计 |
| `05-后端任务清单模板.md`     | 后端 TDD 任务清单           | 任务 |
| `05b-前端任务清单模板.md`    | 前端 TDD 任务清单           | 任务 |
| `06-代码评审报告模板.md`     | 代码评审报告                | 审查 |
| `07-单元测试报告模板.md`     | 单元测试报告                | 测试 |
| `08-系统集成测试报告模板.md` | 集成测试报告                | 测试 |
| `09-性能测试报告模板.md`     | 性能测试报告                | 测试 |
| `10-安全检查清单.md`         | 安全检查清单                | 审查 |
| `11-代码质量标准.md`         | 代码质量标准                | 审查 |
| `13-测试用例模板.md`         | 测试用例                    | 测试 |
| `14-需求追溯矩阵模板.md`     | 需求 → 实现追溯矩阵         | 审查 |
| `15-业务功能架构文档模板.md` | 业务功能架构规划            | 架构 |
| `16-系统架构设计模板.md`     | 系统架构设计                | 架构 |
| `17-子模块依赖关系模板.md`   | 子模块依赖关系              | 架构 |
| `18-统一数据模型模板.md`     | 统一数据建模（含 ER 图）    | 架构 |
| `19-项目目录结构模板.md`     | 项目目录结构规划            | 架构 |
| `20-工作说明书SOW模板.md`    | 工作说明书（SOW）           | 需求 |
| `21-业务方案模板.md`         | 业务方案（F1~F6 文件体系）  | 需求 |

> **约定**：所有模板通过对应 Skill 调用生成，不建议直接手工填写。

---

## 参考工程（9 套）

`references/` 目录包含 `adspecs init` 时按需复制到目标项目的参考代码和规范：

| 目录                       | 说明                                           |
| -------------------------- | ---------------------------------------------- |
| `front-demo/`              | Vue 3 前端演示项目（Vite + TS + Element Plus） |
| `antd-front-demo/`         | Ant Design React 前端演示项目                  |
| `ant6-front-standard/`     | Ant Design 6 前端编码规范（12 篇）             |
| `vue3-front-standard/`     | Vue 3 前端编码规范                             |
| `python-end-standard/`     | Python 后端参考                                |
| `yudaocloud-end-standard/` | 芋道 Cloud 后端集成参考                        |
| `tools/`                   | 辅助工具集                                     |

---

## 推荐开发流程

```
[adspecs init]                        →  项目脚手架
         ↓
[ads-architecture-planning]       →  平台架构规划（功能架构→依赖→数据模型）
         ↓
[ads-new-requirement]             →  深度业务需求分析
         ↓
[ads-biz-blueprint]               →  业务方案（F1~F6 文件体系）
         ↓
[ads-prd + ads-clarify]       →  产品需求说明书 + 澄清迭代
         ↓
[ads-plan / ads-front-spec]   →  后端设计+SQL / 前端设计
         ↓
[ads-tasks / ads-front-tasks] →  后端 / 前端 TDD 任务清单
         ↓
[ads-analyze + adversarial-review]→  一致性与质量审查
         ↓
[TDD + subagent-driven-development]   →  编码实现（依赖 superpowers）
         ↓
[ads-utest]                       →  单元测试 + 报告
         ↓
[sie-front-code-review]               →  前端代码审查
         ↓
[ads-update-status]               →  功能状态追踪
         ↓
[ads-export-word / wiki-update]   →  文档导出 + Wiki 同步
```

### 完整示例：销售预测从零到交付

```txt
# 1. 初始化项目
adspecs init --project-name my-crm --mode classic

# 2. 平台架构规划
/ads-architecture-planning 华峰铝业CRM，覆盖销售全生命周期

# 3. 深度需求分析
/ads-new-requirement CRM 销售预测模块

# 4. 业务方案
/ads-biz-blueprint docs/00-customer-requirements/...

# 5. 生成 PRD
/ads-prd 预测单需求调研.md

# 6. 澄清 + 评审（2~3 轮）
/ads-clarify docs/20-prd/crm/sales-forecast/M06-01_销售预测需求规格说明书.md

# 7. 后端系统设计 + SQL
/ads-plan docs/20-prd/crm/sales-forecast/M06-01_销售预测需求规格说明书.md

# 8. 前端设计
/ads-front-spec docs/20-prd/crm/sales-forecast/M06-01_销售预测需求规格说明书.md

# 9. 生成任务清单
/ads-tasks docs/30-system-design/crm/M06-01-销售预测_system-design.md
/ads-front-tasks docs/30-system-design/crm/M06-01_销售预测_前端设计.md

# 10. 一致性与对抗审查
/ads-analyze docs/20-prd/... docs/30-system-design/...
/ads-adversarial-review M06-01_*.md

# 11. 编码实现（TDD）
/subagent-driven-development

# 12. 单元测试 + 审查
/ads-utest docs/30-system-design/crm/M06-01-销售预测_system-design.md
/sie-front-code-review

# 13. 状态追踪 + 导出
/ads-update-status
/ads-export-word docs/30-system-design/
/wiki-update
```

---

## 路径配置

Skill 支持通过 `.adspecs/paths.json` 自定义输出目录：

```json
{
  "paths": {
    "biz_analysis_dir": "docs/00-customer-requirements",
    "architecture_dir": "docs/10-architecture",
    "research_output_dir": "docs/02-prd",
    "sow_dir": "docs/05-sow",
    "prd_dir": "docs/20-prd",
    "design_dir": "docs/30-system-design",
    "test_report_dir": "docs/80-development/802-test",
    "export_dir": "docs/90-export",
    "front_demo_dir": "front-demo",
    "front_prototype_dir": "web-ui",
    "wiki_dir": "wiki"
  }
}
```

`adspecs init` 自动生成此文件，可直接编辑修改。

---


## 常见问题

**Q1：adspecs 与 superpowers 的关系？**
adspecs 提供领域专属 Skill（需求、设计、模板、规范），superpowers 提供通用 AI 工程 Skill（TDD、子代理、调试）。
- **Claude Code**：两者分工协作，编码阶段必须同时安装
- **Qoder / WorkBuddy**：adspecs 可独立运行，无需 superpowers

**Q2：用户级和项目级安装可以共存吗？**
可以，项目级优先于用户级（就近原则）。个人开发选用户级，团队协作选项目级。

**Q3：Claude Code、Qoder 和 WorkBuddy 可以同时使用吗？**
可以。adspecs 通过 `.claude-plugin/`、`.qoder-plugin/`、`.codebuddy-plugin/` 分别提供三个平台的插件配置，互不干扰。使用 `--platform` 参数指定目标平台即可。

**Q4：安装后 Skill 未生效？**
1. 检查 adspecs 是否在已加载插件列表中
2. 重启对应平台（Claude Code / Qoder / WorkBuddy）
3. WorkBuddy 用户：确认 `~/.workbuddy/plugins/marketplaces/local/.codebuddy-plugin/marketplace.json` 存在
4. 重新执行 `adspecs plugin install --platform <平台名>` 刷新注册

**Q5：如何升级？**
```bash
npm install -g adspecs@latest
adspecs plugin install --platform <平台名>   # 刷新插件注册（WorkBuddy 建议执行）
# Skill 定义随 npm 包更新，Claude Code / Qoder 通常无需重新注册
```

**Q6：前端测试框架？**
Vue 项目使用 Vitest + @vue/test-utils；React 项目使用 Jest + React Testing Library。

**Q7：init 模式区别？**
- `simple`：仅 docs + wiki
- `classic`：+ front-demo（默认）
- `full`：所有目录 + 参考工程
- `demo`：Python+SQLite+React+AntD6 全栈 demo

---

## License

[Apache-2.0](./LICENSE)