alibaba-java-development-guide
《阿里巴巴Java开发手册(黄山版)》Claude Code / Codex Skill —— 极致优雅的Java代码实现，让你拒绝屎山代码堆积。
Install with your AI
Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.
Install and set up alibaba-java-development-guide (claude-skill project) into my current project. Found on https://claudeers.com/alibaba-java-development-guide Repo: https://github.com/Sxuan-Coder/alibaba-java-development-guide Homepage/docs: — Detected install method: claude-skill → # copy this skill into .claude/skills/alibaba-java-development-guide/ Category: skills. Platforms: cli. Read the repo's README for exact setup and env vars, then install it and wire it into my project. Claudeers Health Verdict: active; community-verified: false. Confirm the source before running anything.
# copy the skill dir into your project: # .claude/skills/alibaba-java-development-guide/ (or ~/.claude/skills/alibaba-java-development-guide/ for all projects)
git clone https://github.com/Sxuan-Coder/alibaba-java-development-guide
// compatibility
| Platforms | cli |
|---|---|
| Operating systems | — |
| AI compatibility | claude |
| License | — |
| Pricing | open-source |
| Language | — |
Alibaba Java Development Guide Skill
《阿里巴巴 Java 开发手册（黄山版）》的 Claude Code / Codex 的Skill —— 让 AI 编码助手在写 Java 代码时自动遵循阿里Java开发规约。
码出高效，码出质量。
一、为什么需要这个 Skill
大模型写 Java 代码时，常见三类问题：
| 问题 | 表现 | 后果 |
|---|---|---|
| 命名随意 | List<Map<String,Object>> 满天飞、布尔值叫 flag、常量不全大写 | 可读性差、团队风格不统一 |
| 隐患代码 | Date 而非 LocalDateTime、== 比字符串、try-catch 吞异常、SQL 字符串拼接 | 线上故障、SQL 注入、NPE |
| 架构混乱 | DAO 直接返回给前端、Service 越层调用、缺少 DTO/VO 分层 | 难维护、难扩展 |
根因：模型缺少一份权威、结构化、可按需检索的工程规约上下文。把整本手册塞进 prompt 会爆上下文窗口；让模型"凭记忆"遵循阿里规约又会丢失条文细节和【强制/推荐/参考】分级。
本 Skill 的解法：
- 📚 完整收录黄山版 7 大维度（编程规约 / 异常日志 / 单元测试 / 安全规约 / MySQL / 工程结构 / 设计规约）共 2000+ 行条文
- 🧭 按需路由——
SKILL.md只做导航，命中场景时才读取对应data/*.md，节省 token - 🎯 触发词精准定位——18 条精确关键词映射，AI 无需推理即可直达对应章节
- 🏷️ 保留分级——每条规约标注【强制】/【推荐】/【参考】，AI 能区分优先级
- ✅ 正例 + 反例——条文附带提倡写法与真实故障雷区，AI 修复时有的放矢
- ⚖️ 冲突解决策略——安全优先 > 强制优先 > 业务豁免 > 渐进改进，规约冲突时有据可依
- 👁️ 视角区分——编写视角（即时决策）与审查视角（全局判断）分流，按任务类型推荐阅读路径
- 🎛️ 个性化配置——通过
memory.md覆盖手册规约或补充团队自有规范
二、规约来源
本 Skill 内容完整来源于：
《Java 开发手册（黄山版）》 v1.7.1，2022.02.03 发布 作者：阿里巴巴集团 / 阿里云飞天诚信
黄山版是阿里 Java 开发手册的最新公开版本，在其前身（嵩山版、泰山版等）基础上修订而成，是中文 Java 社区影响力最大、被广泛采纳的工程规约之一。手册以 Java 开发者视角划分为七个维度，并附三张参考表（版本历史、专有名词解释、错误码全量列表）。
⚠️ 版权说明：手册原文版权归阿里巴巴所有。本项目仅以 Skill 形式做工程化封装与便捷分发，便于开发者团队在 AI 辅助编码中统一遵循。
三、仓库结构
alibaba-java-development-guide/
├── SKILL.md # 路由入口 + 增强导航（触发词映射/冲突策略/视角区分/场景推荐）
├── memory.md # 个人编码偏好配置（跨项目）
├── README.md # 本文件
├── project/
│ ├── README.md # project/ 使用说明
│ ├── _template.md # 新建项目规范模板
│ └── <项目名>.md # 按项目名隔离的规范文件
└── data/
├── 01-coding-standards.md # 一、编程规约（命名/OOP/集合/并发/注释...）
├── 02-exception-logging.md # 二、异常日志（错误码/try-catch/NPE/日志）
├── 03-unit-testing.md # 三、单元测试（AIR/BCDE/Mock/覆盖率）
├── 04-security-standards.md # 四、安全规约（脱敏/SQL注入/XSS/CSRF）
├── 05-mysql-database.md # 五、MySQL 数据库（建表/索引/ORM/分页）
├── 06-project-structure.md # 六、工程结构（分层/DO-DTO-VO/二方库）
├── 07-design-standards.md # 七、设计规约（UML/弱依赖/SOLID/DRY）
└── 08-appendix.md # 附录（版本历史/名词/错误码）
每条规约的内部结构：规约编号 + 级别 + 说明 + 正例 + 反例。
四、安装到 Claude Code
把整个目录放到 Claude Code 的 skills 目录下。
方式 A：用户级（全局生效，推荐）
适用于你希望在所有项目里都让 Claude 遵循阿里规约。
# 1. 进入用户 skills 目录（不存在则创建）
mkdir -p ~/.claude/skills
cd ~/.claude/skills
# 2. 克隆本仓库（目录名即为 skill 名）
git clone https://github.com/Sxuan-Coder/alibaba-java-development-guide.git
# 3. 验证：应能看到 SKILL.md
ls alibaba-java-development-guide/SKILL.md
Windows (PowerShell) 等价命令：
mkdir "$env:USERPROFILE\.claude\skills" -Force
cd "$env:USERPROFILE\.claude\skills"
git clone https://github.com/Sxuan-Coder/alibaba-java-development-guide.git
完成后，重启 Claude Code，输入 / 即可在 skill 列表中看到 alibaba-java-development-guide。
方式 B：项目级（仅当前仓库生效）
适用于团队希望把规约随仓库一起分发（提交进版本库，团队成员 clone 后即生效）。
# 在你的业务项目根目录下
cd /path/to/your-java-project
mkdir -p .claude/skills
git clone https://github.com/Sxuan-Coder/alibaba-java-development-guide.git .claude/skills/alibaba-java-development-guide
建议把 .claude/skills/alibaba-java-development-guide 加入业务仓库的版本管理，方便全团队共享。
验证安装
在 Claude Code 中任意 Java 项目里提问，例如：
"帮我 review 这个 Service 类，对照阿里规约"
Claude 会自动加载本 Skill，按需读取 data/02-exception-logging.md、data/06-project-structure.md 等章节并给出条文级反馈。
五、安装到 Codex (OpenAI Codex CLI)
Codex CLI 使用 ~/.codex/ 作为配置根目录，支持通过 prompts/ 注入 slash 命令、并通过 AGENTS.md 让 AI 引用规约文件。本 Skill 的 data/ 章节是纯 Markdown，可被 Codex 直接读取引用。
方式 A：作为可引用的知识库（推荐）
mkdir -p ~/.codex/alibaba-java-guide
cd ~/.codex/alibaba-java-guide
git clone https://github.com/Sxuan-Coder/alibaba-java-development-guide.git .
然后在你的 Java 项目根目录创建 AGENTS.md，让 Codex 在编码时主动参考规约：
# Codex Agent 指引
编写或审查 Java 代码时，必须对照《阿里巴巴 Java 开发手册（黄山版）》。
完整条文位于：~/.codex/alibaba-java-guide/
按场景读取对应章节：
- 命名 / OOP / 集合 / 并发 → data/01-coding-standards.md
- 异常 / 日志 / NPE → data/02-exception-logging.md
- 单元测试 → data/03-unit-testing.md
- 安全（脱敏/SQL注入/XSS） → data/04-security-standards.md
- 建表 / 索引 / ORM → data/05-mysql-database.md
- 分层 / DTO/VO → data/06-project-structure.md
- 设计 / UML / SOLID → data/07-design-standards.md
- 名词 / 错误码 → data/08-appendix.md
方式 B：封装为 slash 命令
把规约入口做成一个可复用的 prompt：
mkdir -p ~/.codex/prompts
cat > ~/.codex/prompts/java-review.md <<'EOF'
请对照《阿里巴巴Java开发手册（黄山版）》审查当前 Java 代码。
按需读取 ~/.codex/alibaba-java-guide/data/ 下对应章节，
逐条指出违反的【强制】/【推荐】规约，并给出正例写法。
EOF
之后在 Codex CLI 中输入 /java-review 即可触发。
六、使用示例
安装完成后，无需手动调用——AI 会在命中场景时自动加载。也可显式触发：
| 你的指令 | Skill 会命中的章节 |
|---|---|
| "这段 SQL 有没有问题" | 05-mysql-database.md（索引、分页、ORM） |
| "这个接口要做脱敏吗" | 04-security-standards.md（敏感数据） |
| "Service 抛异常该怎么处理" | 02-exception-logging.md（错误码、try-catch） |
| "DTO 和 VO 怎么分层" | 06-project-structure.md（应用分层） |
| "帮我写这个方法的单测" | 03-unit-testing.md（AIR、BCDE、Mock） |
| "金额字段要不要用 BigDecimal" | 触发 memory.md + 01-coding-standards.md（优先读团队偏好覆盖） |
| "这个 JWT Token 设计安全吗" | 触发词 JWT/Token → 04-security-standards.md |
| "方法超 80 行了但单一职责拆不动" | 触发 SKILL.md 冲突策略 → 安全豁免 + 加注释说明 |
个性化配置
本 skill 提供两层个性化配置，按优先级合并生效：
memory.md （个人偏好）→ project/<项目名>.md （项目规范）→ 手册原文（基线）
memory.md— 你的个人编码习惯（金额类型、Lombok 偏好等），跨项目通用project/<项目名>.md— 项目团队规范（技术栈、命名约定、规约覆盖等），按项目隔离
初始化：首次使用时 AI 自动扫描项目 + 提问，生成对应文件 持续更新：日常编码中 AI 发现新规范时询问是否加入
七、许可证与贡献
- 规约原文版权归 阿里巴巴集团 所有，本项目仅做工程封装。
- Skill 封装代码（
SKILL.md、路由结构、README 等）按 MIT 协议开源，欢迎 PR 补充条文解读、修复转换噪声、增加实战案例。 - 如发现 PDF 转换残留的排版噪声，欢迎提 Issue 和 PR。
码出高效，码出质量。 让每一次 AI 生成的 Java 代码，都经得起 review。
// faq
What is alibaba-java-development-guide?
《阿里巴巴Java开发手册(黄山版)》Claude Code / Codex Skill —— 极致优雅的Java代码实现，让你拒绝屎山代码堆积。. It is open-source on GitHub.
Is alibaba-java-development-guide free to use?
alibaba-java-development-guide is open-source, so it is free to use.
What category does alibaba-java-development-guide belong to?
alibaba-java-development-guide is listed under skills in the Claudeers registry of Claude-compatible tools.
// embed badge
[](https://claudeers.com/alibaba-java-development-guide)
// retro hit counter
[](https://claudeers.com/alibaba-java-development-guide)
// reviews
// guestbook
// related in Claude Skills
🔓An agentic skills framework & software development methodology that works.
🔓
🔓💫 Toolkit to help you get started with Spec-Driven Development
🔓AI coding assistant skill (Claude Code, Codex, OpenCode, Cursor, Gemini CLI, and more). Turn any folder of code, SQL schemas, R scripts, shell scripts, docs,…