121 Java Object Oriented Design Agent Skill

Java Object-Oriented Design Guidelines

Review and improve Java code using focused object-oriented design references selected after assessing the request and affected code.

What is covered in this Skill?

• Fundamental design principles (SOLID, DRY, YAGNI)
• Class and interface design: composition over inheritance, immutability, accessibility minimization, accessor methods
• Core OOP concepts: encapsulation, inheritance, polymorphism
• Object creation patterns: static factory methods, Builder, Singleton, dependency injection, avoiding unnecessary objects
• OOD code smells: God Class, Feature Envy, Inappropriate Intimacy, Refused Bequest, Shotgun Surgery, Data Clumps
• Method design: parameter validation, defensive copies, careful signatures, empty collections over nulls, Optional usage
• Exception handling: checked vs. runtime exceptions, standard exceptions, failure-capture messages, no silent ignoring

Scope: Classify the applicable OOD concerns first, then load only the focused references needed for those concerns. Load multiple references when a refactoring crosses concern boundaries.

Constraints

Before applying any OOD changes, ensure the project compiles. If compilation fails, stop immediately — do not proceed until resolved. After applying improvements, run full verification.

• MANDATORY: Run ./mvnw compile or mvn compile before applying any change
• SAFETY: If compilation fails, stop immediately and do not proceed — compilation failure is a blocking condition
• VERIFY: Run ./mvnw clean verify or mvn clean verify after applying improvements
• PROGRESSIVE DISCLOSURE: Classify the applicable OOD concerns before reading references, then read only the references mapped to those concerns
• MULTI-CONCERN CHANGES: Read multiple focused references only when the request or diagnosed code problems cross concern boundaries
• PRESERVE BEHAVIOR: Apply focused, incremental refactorings without changing observable business behavior
• INCREMENTAL SAFETY: Compile after each significant refactoring and keep changes easy to revert if validation reveals a regression
• DEPENDENCY SAFETY: Confirm refactoring does not break imports, dependencies, class relationships, or established contracts
• ADJACENT SKILLS: Use skill 122 for dedicated type-design work and skill 126 for dedicated exception-handling work; use the overlapping skill 121 references only when those topics are part of a broader OOD review
• EDGE CASE: If request scope is ambiguous, stop and ask a clarifying question before applying changes
• EDGE CASE: If required inputs, files, or tooling are missing, report what is missing and ask whether to proceed with setup guidance

When to use this skill

• Review Java code for object-oriented design
• Refactor Java code for object-oriented design
• Improve Java code for object-oriented design
• Fix OOP concept misuse in Java code
• Identify and resolve code smells in Java code
• Improve object creation patterns in Java code
• Improve method design in Java code
• Improve exception handling in Java code

Workflow

• Compile project before OOD changes

Run ./mvnw compile or mvn compile and stop immediately if compilation fails.

• Assess code and classify OOD concerns

Analyze the request and affected Java code before reading implementation guidance. Classify each relevant problem into one or more concerns:

• Fundamental principles: SOLID, DRY, or YAGNI violations.
• Core OOP concepts: encapsulation, inheritance, or polymorphism misuse.
• Code smells: God Class, Feature Envy, Inappropriate Intimacy, Refused Bequest, Shotgun Surgery, or Data Clumps.
• Object creation: factories, builders, singletons, dependency injection, or unnecessary object creation.
• Classes and interfaces: accessibility, public fields, mutability, composition, or inheritance design.
• Enums and annotations: int constants, ordinals, bit fields, ordinal indexing, or missing @Override.
• Methods: parameter validation, defensive copies, signatures, null collections, or Optional.
• Exceptions: exception contracts that are part of the broader OOD review.

If the request is dedicated type-design work, use skill 122. If it is dedicated exception-handling work, use skill 126.

• Read only applicable OOD references

Map the classified concerns to focused references:

• For SOLID, DRY, or YAGNI, read references/121-java-object-oriented-design-principles.md.
• For encapsulation, inheritance, or polymorphism, read references/121-java-object-oriented-design-oop-concepts.md.
• For object-oriented code smells, read references/121-java-object-oriented-design-code-smells.md.
• For factories, builders, singletons, dependency injection, or unnecessary objects, read references/121-java-object-oriented-design-object-creation.md.
• For class and interface boundaries, accessibility, mutability, composition, or inheritance design, read references/121-java-object-oriented-design-classes-interfaces.md.
• For enums, ordinals, bit fields, enum lookup, or @Override, read references/121-java-object-oriented-design-enums-annotations.md.
• For method contracts, validation, defensive copies, signatures, collection returns, or Optional, read references/121-java-object-oriented-design-methods.md.
• For exception contracts within a broader OOD review, read references/121-java-object-oriented-design-exceptions.md.

Read every reference required by a cross-concern refactoring, but do not read unrelated references.

• Apply focused refactorings

Prioritize findings by impact: CRITICAL, MAINTAINABILITY, FLEXIBILITY, or CODE_QUALITY. Apply the smallest suitable refactoring for each diagnosed concern while preserving observable behavior:

• Extract classes or methods to restore focused responsibilities.
• Introduce or refine abstractions for extension, interface segregation, and dependency inversion.
• Correct inheritance hierarchies to preserve substitutability, or replace inheritance with composition.
• Move behavior to eliminate Feature Envy and improve encapsulation.
• Introduce cohesive value or parameter objects for Data Clumps.
• Hide exposed state and reduce unnecessary coupling.

Apply changes incrementally and compile after each significant refactoring.

• Verify with full build

Run ./mvnw clean verify or mvn clean verify after applying improvements.

• Report applied OOD improvements

Report findings by impact and concern, focused references used, refactorings applied, maintainability/flexibility/testability benefits, behavior-preservation evidence, and the final compilation and test result.

Reference

For detailed guidance, examples, and constraints, see:

• references/121-java-object-oriented-design-principles.md
• references/121-java-object-oriented-design-oop-concepts.md
• references/121-java-object-oriented-design-code-smells.md
• references/121-java-object-oriented-design-object-creation.md
• references/121-java-object-oriented-design-classes-interfaces.md
• references/121-java-object-oriented-design-enums-annotations.md
• references/121-java-object-oriented-design-methods.md
• references/121-java-object-oriented-design-exceptions.md