Skip to content

Commit 92b3395

Browse files
committed
docs(readme): 更新仓库结构、能力清单与个性化配置说明
1 parent dd0c5ea commit 92b3395

1 file changed

Lines changed: 30 additions & 2 deletions

File tree

README.md

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44
55
`码出高效,码出质量。`
66

7+
---
8+
![version](https://img.shields.io/badge/version-1.1.0-blue) ![license](https://img.shields.io/badge/license-MIT-green) ![Alibaba](https://img.shields.io/badge/Alibaba-黄山版-orange)
79
---
810

911
## 一、为什么需要这个 Skill
@@ -22,8 +24,12 @@
2224

2325
- 📚 **完整收录**黄山版 7 大维度(编程规约 / 异常日志 / 单元测试 / 安全规约 / MySQL / 工程结构 / 设计规约)共 2000+ 行条文
2426
- 🧭 **按需路由**——`SKILL.md` 只做导航,命中场景时才读取对应 `data/*.md`,节省 token
27+
- 🎯 **触发词精准定位**——18 条精确关键词映射,AI 无需推理即可直达对应章节
2528
- 🏷️ **保留分级**——每条规约标注【强制】/【推荐】/【参考】,AI 能区分优先级
2629
-**正例 + 反例**——条文附带提倡写法与真实故障雷区,AI 修复时有的放矢
30+
- ⚖️ **冲突解决策略**——安全优先 > 强制优先 > 业务豁免 > 渐进改进,规约冲突时有据可依
31+
- 👁️ **视角区分**——编写视角(即时决策)与审查视角(全局判断)分流,按任务类型推荐阅读路径
32+
- 🎛️ **个性化配置**——通过 `memory.md` 覆盖手册规约或补充团队自有规范
2733

2834
## 二、规约来源
2935

@@ -34,14 +40,19 @@
3440
3541
黄山版是阿里 Java 开发手册的最新公开版本,在其前身(嵩山版、泰山版等)基础上修订而成,是**中文 Java 社区影响力最大、被广泛采纳的工程规约**之一。手册以 Java 开发者视角划分为七个维度,并附三张参考表(版本历史、专有名词解释、错误码全量列表)。
3642

37-
> ⚠️ **版权说明**:手册原文版权归阿里巴巴所有。本项目仅以 Skill 形式做工程化封装与便捷分发,便于开发者团队在 AI 辅助编码中统一遵循。如需官方原版,请参考阿里巴巴官方发布渠道。
43+
> ⚠️ **版权说明**:手册原文版权归阿里巴巴所有。本项目仅以 Skill 形式做工程化封装与便捷分发,便于开发者团队在 AI 辅助编码中统一遵循。
3844
3945
## 三、仓库结构
4046

4147
```
4248
alibaba-java-development-guide/
43-
├── SKILL.md # 路由入口(AI 据此按需检索)
49+
├── SKILL.md # 路由入口 + 增强导航(触发词映射/冲突策略/视角区分/场景推荐)
50+
├── memory.md # 个人编码偏好配置(跨项目)
4451
├── README.md # 本文件
52+
├── project/
53+
│ ├── README.md # project/ 使用说明
54+
│ ├── _template.md # 新建项目规范模板
55+
│ └── <项目名>.md # 按项目名隔离的规范文件
4556
└── data/
4657
├── 01-coding-standards.md # 一、编程规约(命名/OOP/集合/并发/注释...)
4758
├── 02-exception-logging.md # 二、异常日志(错误码/try-catch/NPE/日志)
@@ -163,6 +174,23 @@ EOF
163174
| "Service 抛异常该怎么处理" | `02-exception-logging.md`(错误码、try-catch) |
164175
| "DTO 和 VO 怎么分层" | `06-project-structure.md`(应用分层) |
165176
| "帮我写这个方法的单测" | `03-unit-testing.md`(AIR、BCDE、Mock) |
177+
| "金额字段要不要用 BigDecimal" | 触发 `memory.md` + `01-coding-standards.md`(优先读团队偏好覆盖) |
178+
| "这个 JWT Token 设计安全吗" | 触发词 `JWT/Token``04-security-standards.md` |
179+
| "方法超 80 行了但单一职责拆不动" | 触发 `SKILL.md` 冲突策略 → 安全豁免 + 加注释说明 |
180+
181+
### 个性化配置
182+
183+
本 skill 提供两层个性化配置,按优先级合并生效:
184+
185+
```
186+
memory.md (个人偏好)→ project/<项目名>.md (项目规范)→ 手册原文(基线)
187+
```
188+
189+
- **`memory.md`** — 你的个人编码习惯(金额类型、Lombok 偏好等),跨项目通用
190+
- **`project/<项目名>.md`** — 项目团队规范(技术栈、命名约定、规约覆盖等),按项目隔离
191+
192+
**初始化**:首次使用时 AI 自动扫描项目 + 提问,生成对应文件
193+
**持续更新**:日常编码中 AI 发现新规范时询问是否加入
166194

167195
## 七、许可证与贡献
168196

0 commit comments

Comments
 (0)