6.3 KiB
6.3 KiB
name, description
| name | description |
|---|---|
| java-coding-style | 面向 Vibe Coding Agent 的 Java 编写、修改、重构、审查与验证规范，以《阿里巴巴 Java 开发手册》为质量基线并适配现代 JDK 与项目既有约定。凡任务涉及 Java、Spring、Jakarta、Quarkus、MyBatis、JPA、Maven、Gradle、单元测试、并发、异常日志、数据库访问或 Java 代码 Review 时使用。 |
Java 代码风格
将本 Skill 作为 Java 任务的语言级质量规范；将项目的任务治理 Skill 作为流程级规范。两者同时触发时，先执行任务分级与门禁，再在实现、Review 和验证阶段执行本 Skill。
规则优先级
按以下顺序解决冲突：
平台安全规则与用户本次明确要求
→ 已确认的需求、接口和验收标准
→ 作用域最近的 AGENTS.md、项目规范、构建配置与 formatter
→ 相邻代码中稳定且合理的架构惯例
→ 本 Skill 的必须项
→ 本 Skill 的推荐项
不得以“遵循阿里规范”为由破坏兼容性、绕过项目门禁或批量改写无关代码。发现项目惯例存在明显缺陷、安全问题或与必须项冲突时，说明证据、影响和建议，不得静默复制缺陷。
规则等级
- 必须：默认不可违反。仅在更高优先级规则明确要求时例外，并记录原因。
- 推荐：无冲突时采用；不采用时应有可说明的工程理由。
- 参考：根据 JDK、框架、性能数据和业务上下文选择。
规则等级用于约束 Agent，不代表已配置静态检查。只有实际运行的检查才能报告为通过。
开始实现前
- 查找并读取作用域内的
AGENTS.md、README、构建文件、formatter、Checkstyle、PMD、SpotBugs、Error Prone 和测试配置。 - 确认 Java/JDK 版本、框架版本、模块边界、包结构、依赖管理方式及相邻实现惯例。
- 从用户需求或已确认文档提取可观察行为、边界条件、异常语义、兼容性约束和验收证据。
- 检查工作区已有改动，避免覆盖、格式化或修复任务范围外的代码。
- 按任务内容加载本 Skill 的参考文件：
- 命名、格式、常量、注释：读取 references/01-命名格式与注释.md。
- 类型、OOP、API、空值：读取 references/02-类型OOP与API设计.md。
- 集合、并发、日期时间：读取 references/03-集合并发与时间.md。
- 异常、日志、安全：读取 references/04-异常日志与安全.md。
- 分层、持久化、依赖：读取 references/05-工程分层与数据访问.md。
- 测试、Review、验证：实现和审查阶段读取 references/06-测试审查与验证.md。
只加载与任务相关的规则；进行完整 Java Review 时加载全部参考文件。
编写代码
遵循以下顺序：
确认行为与边界
→ 找到最小改动点
→ 先写或调整能失败的测试
→ 实现最小充分代码
→ 清理命名、结构和重复
→ 执行静态审查
→ 运行相关验证
必须：
- 保持单一职责和清晰依赖方向，不为了“更优雅”引入无需求支撑的抽象、框架或设计模式。
- 优先复用项目内已验证的组件；新增公共工具前确认没有等价实现。
- 把校验放在信任边界，把业务不变量放在领域或服务边界；不要依赖控制器校验保护所有调用路径。
- 维持 API、序列化、数据库和异常契约兼容；任何破坏性变化都必须显式列出并获得相应确认。
- 仅修改任务需要的代码。不要顺手全局格式化、升级依赖或清理无关告警。
- 对非显然的业务决策写“为什么”的注释；不要用注释复述代码。
- 不生成凭据、真实个人信息、生产数据或可被误用的安全绕过代码。
Java 专项审查
实现后逐项检查：
- 正确性：空值、边界、溢出、精度、时区、编码、异常路径和资源释放。
- 契约：参数、返回值、异常、幂等性、事务、序列化和向后兼容。
- 并发：共享可变状态、原子性、可见性、锁范围、线程池和
ThreadLocal清理。 - 数据：参数绑定、查询规模、索引假设、批量操作、事务边界和 N+1 查询。
- 安全：认证与授权、对象级权限、注入、反序列化、路径/URL、敏感信息和重放。
- 可维护性：命名、职责、重复、嵌套、隐藏副作用和测试可读性。
发现问题时按严重性报告：阻断、严重、一般、建议。给出文件、位置、触发条件、影响和最小修复建议；不得只报风格偏好。
验证
优先使用项目已有命令和 CI 等价检查。按改动范围选择：
- 运行目标单元测试，再运行受影响模块测试。
- 运行编译、格式、静态分析和集成测试中与风险相称的部分。
- 项目已配置 Alibaba P3C/PMD 时运行其既有任务；未配置时不要擅自安装插件或新增构建依赖。
- 对并发、事务、时区、序列化或安全变更补充针对性验证，不能只依赖 happy path。
报告每个实际命令、结果和未执行项。不得把“代码看起来正确”写成测试通过，不得用全量构建失败掩盖目标测试结果。
交付格式
最终说明至少包含：
- 完成的行为与主要代码位置；
- 与需求直接相关的设计决定；
- 实际执行的测试和静态检查；
- 未验证内容、遗留风险和明确例外。
若仅做 Review，不修改代码；若用户要求实现，则完成实现、Review 和验证后再交付。
规范来源与适配
本 Skill 以阿里巴巴公开的 Java 开发规约及 P3C 工具规则为基线，并将其改写为 Agent 可执行指令：
阿里规约按“强制、推荐、参考”分级；本 Skill 对应为“必须、推荐、参考”。历史性规则不得脱离项目 JDK、框架、序列化协议和工具链机械套用。