# java-spec-skills

**Repository Path**: zrclass/java-spec-skills

## Basic Information

- **Project Name**: java-spec-skills
- **Description**: Java Spec Skills 是一套面向 AI 编码助手（OpenCode、Claude Code 等）的 Java 开发规约技能包。它将《阿里巴巴Java开发手册（黄山版）》拆解为 7 个专项 skill，通过一个智能主编排器在 AI 编码的不同阶段自动加载对应的规范，确保 AI 生成的每一行代码都符合业界最佳实践。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2026-05-08
- **Last Updated**: 2026-05-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: skills, sdd, java规范开发, AI

## README

# Java Spec Skills

> 让 AI 编码助手写出符合《阿里巴巴Java开发手册》规范的代码。

**Java Spec Skills** 是一套面向 AI 编码助手（OpenCode、Claude Code 等）的 Java 开发规约技能包。它将《阿里巴巴Java开发手册（黄山版）》拆解为 7 个专项 skill，通过一个**智能主编排器**在 AI 编码的不同阶段自动加载对应的规范，确保 AI 生成的每一行代码都符合业界最佳实践。

---

## 目录

- [为什么需要它](#为什么需要它)
- [项目架构](#项目架构)
- [技能清单](#技能清单)
- [AI 驱动机制](#ai-驱动机制)
- [快速开始](#快速开始)
- [工作原理](#工作原理)
- [平台支持](#平台支持)
- [项目结构](#项目结构)
- [贡献指南](#贡献指南)
- [许可证](#许可证)

---

## 为什么需要它

### AI 编码的痛点

```
开发者: "帮我写一个订单服务的下单方法"
AI:     [生成代码，但...]
        - 类名用的 camelCase 而不是 PascalCase ❌
        - 异常直接 printStackTrace() 了事 ❌
        - SQL 拼接没做参数绑定 ❌
        - 数据库表名用了复数 ❌
        - 没有写单元测试 ❌
```

**问题根源：AI 缺乏领域知识。** AI 模型训练数据中混杂着各种风格、各种质量的代码，没有明确的规范约束时，生成结果参差不齐。

### 解决方案

**Java Spec Skills** 将《阿里巴巴Java开发手册》变成 AI 可以直接理解和执行的指令。当你进行 Java 开发时，主编排器自动识别你在做什么（设计、编码、测试、数据库操作），然后加载对应的专项规约，**像一位资深 Code Reviewer 一样全程指导 AI**。

### 核心优势

| 特性 | 说明 |
|------|------|
| **阶段智能路由** | 设计阶段自动加载设计规约，编码阶段加载编码规约，不浪费 token |
| **强制执行** | `[强制]` 级别的规则 AI 必须遵守，`[推荐]` 级别强烈建议 |
| **即装即用** | 一行命令初始化，无需配置 |
| **多平台支持** | OpenCode、Claude Code 统一体验 |
| **源码开放** | 可定制、可扩展，适配团队私有规范 |

---

## 项目架构

```
                          ┌──────────────────────────────────┐
                          │     java-spec-orchestrator       │
                          │          (主编排器)               │
                          │   描述: Java任务时自动加载         │
                          └────────────┬─────────────────────┘
                                       │ 意图识别 → 阶段路由
           ┌───────────────────────────┼───────────────────┐
           ▼                           ▼                   ▼
   ┌──────────────┐           ┌──────────────┐    ┌──────────────┐
   │  设计阶段      │           │  编码阶段      │    │  测试阶段      │
   │              │           │              │    │              │
   │ design       │           │ coding(基础)  │    │ testing      │
   │ structure    │           │ exception*    │    │              │
   └──────────────┘           │ security*     │    └──────────────┘
                              │ [mysql]*      │
                              └──────────────┘
                              * 按需智能加载
```

**设计原则：**

1. **阶段驱动，按时加载** — 不同开发阶段加载不同 skill，避免一次性加载全部规范浪费 token
2. **名称引用，无路径依赖** — skill 之间通过名称互相引用，不依赖文件路径，可移植
3. **编码基础必加载** — `coding-standards` 是所有编码任务的基础，始终加载
4. **智能附加** — `exception`、`security`、`mysql` 根据任务上下文智能判断是否加载

---

## 技能清单

### 主编排器

| Skill | 描述 |
|-------|------|
| `java-spec-orchestrator` | Java 开发任务总调度器。分析用户意图，判断开发阶段，自动加载对应子 skill |

### 7 个专项规约

| Skill | 内容 | 规则数 | 触发场景 |
|-------|------|--------|---------|
| `java-coding-standards` | 命名风格、常量定义、代码格式、OOP规约、日期时间、集合处理、并发处理、控制语句、注释规约、前后端规约 | 150+ | **所有编码任务（基础必加载）** |
| `java-design-standards` | 设计评审规范、用例图/状态图/时序图/类图/活动图规范、设计原则（单一职责、开闭原则、依赖倒置等） | 20 | 软件设计、架构决策 |
| `java-exception-logging` | 错误码规范、异常处理规范、日志规约（SLF4J、级别判断、日志格式） | 40 | 异常处理、日志记录 |
| `java-mysql-database` | 建表规范、索引规范、SQL语句规范、ORM映射规范 | 50 | 数据库设计、SQL编写 |
| `java-project-structure` | 应用分层、二方库依赖管理、服务器JVM配置 | 24 | 项目结构设计 |
| `java-security-standards` | 权限控制、数据脱敏、SQL注入防护、XSS/CSRF防护、文件上传安全 | 11 | 安全功能实现 |
| `java-unit-testing` | AIR原则、BCDE设计、覆盖标准、测试最佳实践 | 16 | 单元测试编写 |

---

## AI 驱动机制

### 如何让 AI 遵守规约？

传统方式是把规约文档喂给 AI 作为上下文，但这种方式有严重缺陷：

| 传统方式 | Java Spec Skills |
|---------|-----------------|
| 每次对话都要粘贴规范 | 初始化一次，永久生效 |
| 全部规范一股脑塞入，浪费 token | 阶段路由，只加载当前需要的规范 |
| AI 容易忽略冗长的文档 | 结构化 skill，AI 逐条执行 |
| 无法区分强制/推荐/参考 | `[强制]` `[推荐]` `[参考]` 三级约束 |
| 每次换项目都要重新配置 | `javaspec init` 一行命令 |

### 工作流程详解

```
1. 开发者在项目中执行: javaspec init --platform opencode
   → 在项目根目录创建 .opencode/skills/，部署全部 8 个 skill

2. 开发者对 AI 说: "帮我设计一个订单系统"
   → AI 平台自动加载 java-spec-orchestrator（描述匹配触发）
   → 主编排器分析: 关键词"设计" → 设计阶段
   → 主编排器加载: java-design-standards + java-project-structure
   → AI 在设计规约的约束下进行系统设计

3. 开发者对 AI 说: "实现下单接口"
   → 主编排器分析: 关键词"实现"、"接口" → 编码阶段
   → 主编排器加载: java-coding-standards（基础）
   → 判断上下文: 涉及支付 → 加载 java-security-standards
   → AI 在编码+安全规约的约束下生成代码

4. 开发者对 AI 说: "给刚才的代码写单元测试"
   → 主编排器分析: 关键词"单元测试" → 测试阶段
   → 主编排器加载: java-unit-testing
   → AI 按照 AIR 原则和 BCDE 设计编写测试用例
```

### 约束分级

```
[强制] — 必须遵守，违反会导致系统风险或安全问题
        例: "用户输入的 SQL 参数严格使用参数绑定"
[推荐] — 强烈建议遵守，提升代码质量和可维护性
        例: "谨慎使用继承，优先使用组合"
[参考] — 可选参考，根据实际情况决定
        例: "代码即文档的观点是错误的"
```

---

## 快速开始

### 安装

> **注意：** 项目尚未发布到 npm，暂不支持 `npm install -g` 全局安装。请使用以下方式：

**方式一：克隆后本地链接（推荐）**

```bash
# 克隆仓库
git clone https://github.com/your-org/java-spec-skills.git
cd java-spec-skills

# 创建全局链接
npm link
```

**方式二：直接运行 CLI**

```bash
git clone https://github.com/your-org/java-spec-skills.git
cd java-spec-skills

# 用 node 直接运行
node bin/javaspec.js init --platform opencode
```

### 初始化项目

```bash
# 进入你的 Java 项目目录
cd my-java-project

# 为 OpenCode 初始化
javaspec init --platform opencode

# 或为 Claude Code 初始化
javaspec init --platform claudecode
```

初始化后，项目目录会多出 `.opencode/skills/`（或 `.claude/skills/`），包含全部 8 个 skill：

```
my-java-project/
├── .opencode/
│   └── skills/
│       ├── java-spec-orchestrator/
│       │   └── SKILL.md
│       ├── java-coding-standards/
│       │   └── SKILL.md
│       ├── java-design-standards/
│       │   └── SKILL.md
│       ├── java-exception-logging/
│       │   └── SKILL.md
│       ├── java-mysql-database/
│       │   └── SKILL.md
│       ├── java-project-structure/
│       │   └── SKILL.md
│       ├── java-security-standards/
│       │   └── SKILL.md
│       └── java-unit-testing/
│           └── SKILL.md
├── src/
├── pom.xml (或 build.gradle)
└── ...
```

### 使用

初始化完成后，直接用 AI 编码助手开始 Java 开发即可。主编排器会在你开始任何 Java 任务时自动激活，无需额外的命令或配置。

```bash
# 示例对话
你: "帮我创建一个订单表"
AI: [自动加载 java-mysql-database + java-coding-standards]
    [按照建表规范生成 DDL: 小写表名、is_xxx 命名、必备三字段、逻辑删除...]

你: "实现一个用户注册接口"
AI: [自动加载 java-coding-standards + java-security-standards]
    [按照规范生成: 参数校验、密码加密、敏感信息脱敏、异常处理...]
```

---

## 工作原理

### 主编排器的意图识别

主编排器通过关键词匹配来判断开发阶段：

| 关键词 | 识别为 | 加载 Skill |
|--------|--------|-----------|
| 设计、架构、方案、类图、重构 | 设计阶段 | design-standards + project-structure |
| 实现、代码、方法、接口、Controller、Service | 编码阶段 | coding-standards |
| 异常、日志、错误码 | 编码 + 异常 | coding + exception-logging |
| 权限、脱敏、SQL注入、XSS | 编码 + 安全 | coding + security-standards |
| 数据库、建表、索引、DAO、Mapper | 编码 + 数据库 | coding + mysql-database |
| 测试、单元测试、JUnit、覆盖率 | 测试阶段 | unit-testing |

### 降级策略

当意图识别不明确时：
1. 默认为**编码阶段**
2. 至少加载 `java-coding-standards` 作为兜底
3. 随着任务展开，按需加载其他 skill

---

## 平台支持

| 平台 | 安装目录 | Skill 加载方式 |
|------|---------|--------------|
| **OpenCode** | `.opencode/skills/` | `skill` tool |
| **Claude Code** | `.claude/skills/` | `Skill` tool |

两种平台使用完全相同的 SKILL.md 内容，仅部署目录不同。

---

## 项目结构

```
java-spec-skills/
├── skills/                         # 开发源文件（提交到 git）
│   ├── java-spec-orchestrator/     # 主编排器
│   ├── java-coding-standards/      # 编码规约（完整手册）
│   ├── java-design-standards/      # 设计规约
│   ├── java-exception-logging/     # 异常日志规约
│   ├── java-mysql-database/        # MySQL 数据库规约
│   ├── java-project-structure/     # 工程结构规约
│   ├── java-security-standards/    # 安全规约
│   └── java-unit-testing/          # 单元测试规约
├── bin/
│   └── javaspec.js                 # CLI 工具
├── scripts/
│   └── sync-assets.js              # prepublishOnly 同步脚本
├── package.json                    # npm 包配置
└── assets/skills/                  # 分发包（prepublishOnly 自动生成，不提交）
```

---

## 贡献指南

### 规约来源

本项目的规约内容源自 **[《阿里巴巴Java开发手册（黄山版）》v1.7.1](https://github.com/alibaba/p3c)**，版权归阿里巴巴集团所有。

### 如何贡献

1. **反馈问题** — 提交 Issue 报告规约错误或改进建议
2. **定制规约** — Fork 项目，修改或新增 skill 适配团队规范
3. **平台扩展** — 为更多 AI 编码平台添加支持

### 开发

```bash
git clone https://github.com/your-org/java-spec-skills.git
cd java-spec-skills

# 修改 skills/ 下的 SKILL.md 文件
# 然后本地测试
node scripts/sync-assets.js
node bin/javaspec.js init --platform opencode
```

### 发布

```bash
npm publish  # prepublishOnly 钩子自动同步 skills/ → assets/skills/
```

---

## 许可证

本项目为基于《阿里巴巴Java开发手册》的技术实现，遵循 MIT License。

规约内容版权归阿里巴巴集团所有，详见 [《阿里巴巴Java开发手册（黄山版）》](https://github.com/alibaba/p3c)。

---

## 致谢

- [阿里巴巴Java开发手册](https://github.com/alibaba/p3c) — 业界最权威的 Java 编码规范
- [OpenCode](https://github.com/anomalyco/opencode) — 终端 AI 编码助手
- [Claude Code](https://claude.ai) — Anthropic 的 AI 编码助手