Overview
When using this skill, treat the Alibaba Java Development Manual as the default quality baseline for Java code generation, refactoring, and review. Handle mandatory rules first, then recommended rules; if local project conventions conflict with the guidelines, explain the conflict and defer to the user or project conventions.
See the detailed rule summary in references/alibaba-java-rules.md. When exact sources or complete clauses are needed, open the official page:https://alibaba.github.io/Alibaba-Java-Coding-Guidelines/。
Compatibility
This is a general Agent Skill and is not tied to a single application or runner. Claude Code, Codex, and other tools that support the Agent Skills directory specification should rely only on SKILL.md and the references/ content read on demand.
agents/openai.yaml is only OpenAI/Codex UI metadata and is an optional enhancement; it should not be a prerequisite for Claude Code or other agents to use this skill.
The validation entry point provides three equivalent implementations in Python, Node.js, and Go:scripts/validate_skill.py、scripts/validate_skill.mjs、scripts/validate_skill.go. Users can choose any one according to their local runtime; when the three need to be verified as consistent, run tests/test_validators.sh。
Use Cases
- Review changes related to Java, Spring, MyBatis, Maven, SQL, DDL, logging, exception handling, or security.
- Generate new classes, interfaces, DTOs, VOs, DOs, enums, exception classes, test classes, Mappers, Services, DAOs, or SQL.
- Refactor naming, constants, collections, concurrency, control flow, logging, exceptions, and database access code.
- Provide code review comments, remediation checklists, specification compliance reports, or automated fix suggestions.
Workflow
- First identify the task type: code generation, code review, refactoring, SQL/DDL review, dependency governance, security check.
- Read the current project's existing style, package structure, testing framework, and persistence layer approach to avoid rigidly applying only general guidelines.
- Handle by severity level:
- Mandatory: must be pointed out or fixed when a violation is found.
- Recommended: follow by default; if not adopted, explain the tradeoff.
- Reference: serves as a design suggestion and does not block delivery.
- For relevant modules, read the corresponding subsection in
references/alibaba-java-rules.md. - When outputting results, sort by impact: correctness and security, stability and performance, maintainability, style consistency.
Code Generation Rules
- Naming must be clear and accurate: class names use UpperCamelCase, methods, parameters, member variables, and local variables use lowerCamelCase, and constants use uppercase with underscores.
- Code comments use Chinese; public APIs, complex business rules, exception meanings, and null-value semantics must be clearly stated.
- Do not use magic values; for fixed-range values, prefer enums.
- Logging uses the SLF4J facade and does not directly bind to a specific logging implementation; low-level logging uses placeholders or level checks.
- For resource closing, prefer try-with-resources; do not return or throw new exceptions in finally.
- MyBatis parameters use
#{}by default, and it is forbidden to concatenate user input into SQL. - Web, Open API, SQL, HTML output, and user input must undergo permission, parameter validation, escaping, or masking.
Code Review Output
When reviewing, prioritize giving actionable comments. Each comment includes:
- Level: mandatory, recommended, or reference.
- Location: file and line number; locate it if possible.
- Issue: which category of rules was violated.
- Risk: the possible errors, security, performance, or maintenance costs it may cause.
- Suggestion: give a practical fix.
If no issues are found, explain the scope that was checked, and point out the risks that are still not covered, such as not running tests, not seeing database index information, not having online log configuration, etc.
Common Misconceptions
- Do not check only formatting; naming, null values, exception boundaries, log context, transactions, SQL injection, and permission validation are equally important.
- Do not package recommended rules as mandatory defects; for recommended items, clearly explain the benefits and costs.
- Do not sacrifice project consistency for the sake of rules; look first at the local architecture layering, package names, and framework constraints before changing anything.
- Do not rely on the exclusive tools, paths, or configurations of a particular agent product; treat them only as optional enhancements.
- Do not repeat large sections of official documentation; load only the rule summaries relevant to the task.