Ready to supercharge your AI agents?

Install any skill in seconds. Free to start, no credit card required.

Java Object-Oriented Design Guidelines · jabrena | DecimalAI

jabrena/121-java-object-oriented-design

NewSkillScoreMaintained

Use when reviewing, improving, or refactoring Java object-oriented design, including applying SOLID, DRY, or YAGNI; improving classes and interfaces; correcting encapsulation, inheritance, or polymorphism; resolving God Class, Feature Envy, or Data Clumps; and improving object creation, methods, or exception contracts. Triggers include review Java OOD, refactor Java OOD, improve Java OOD, fix OOP misuse, and identify Java code smells. Part of Plinth Toolkit

codingby jabrena

Links this skill to your agents and keeps it current with the author’s updates.

Automatic

Coding pack

1 · One-time — install the CLI (docs ↗)

pip install decimalai

2 · Get the skill — writes .claude/skills/jabrena-121-java-object-oriented-design/SKILL.md

decimalai skills pull jabrena-121-java-object-oriented-design --out .claude/skills/

No CLI? Get the same file — curl · raw file

curl -fsSL --create-dirs -o .claude/skills/jabrena-121-java-object-oriented-design/SKILL.md https://app.decimal.ai/s/jabrena-121-java-object-oriented-design/SKILL.md

Raw file: /s/jabrena-121-java-object-oriented-design/SKILL.md ↗ · machine-readable summary at /s/jabrena-121-java-object-oriented-design.json ↗

In productionGlobal

how this skill behaves on real traffic · last 30 days

No production data for this skill yet — usage numbers appear here once agents start running it.

Anonymized aggregate across every org using this skill — proof from real production use, not a demo.

Does this skill help? · Benchmark: with vs. withoutsign in to run this on your agents

22 test cases from the publisher’s eval.yaml · each run twice on gemini-3.6-flash — with the skill injected, then without · last run 14h ago

—+38% tokens0% turns64% of whole cases pass with skill (14/22)

Test case	Without → With	Effect	Δ tokens	Δ turns
case-04	✗→✓	▲ Improved	-31%	0%
case-05	✗→✓	▲ Improved	-42%	0%
case-09	✗→✓	▲ Improved	114%	0%
case-11	✗→✓	▲ Improved	196%	0%
case-12	✗→✓	▲ Improved	65%	0%

Showing 5 of 22 cases

SkillSafety

✓ 3 of 3 passed

Code scan15 of 15 checks clean

0 critical · 0 warning · 0 info — scanner v4 — 8/3/2026

live_secretremote_code_executionreverse_shelldata_exfiltrationssrf_metadataagent_snoopinganti_refusaldestructive_commandsobfuscated_unicodeunicode_homoglyphopaque_blobsuspicious_urltool_overreachtrigger_abuseprompt_injection_phrasing

IntentSafe

LLM judge · does the skill do what it claims

ContentClean

LLM judge · policy & harmful-content review

Source

Imported

jabrena / plinth

skills/121-java-object-oriented-design/SKILL.md

View on GitHub ↗

License Apache-2.0Imported 8/3/2026Version v1Bundled 8 files

Skill contents

references/

SKILL.md

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

Want to see if jabrena/121-java-object-oriented-design would activate on your phrasing? Try it before you install — no LLM call, no signup.

Latest benchmark · publisher runVerified

8/20/2026, 10:00 UTC · 22 cases

Measured on 16 comparable cases — below the 22 needed to publish a lift, so this result is shown here but not on the registry card or leaderboard.

Lift

+32%

64% vs 32%

Agent turns

1.0 vs 1.0

Tokens

+38%

2,686.44 vs 1,943.06

fail → pass · 9pass → pass · 5fail → fail · 6pass → fail · 2

Per-case results (22)

Case	Status	Duration (ms)			Turns			Tokens			Tool calls
Case	Status	Without	With	Δ	Without	With	Δ	Without	With	Δ	Without	With	Δ
case-01 Our legacy `OrderProcessor.java` service class has grown huge and handles everything from payment calculations to inventory checks and customer notifications. Please audit and refactor this Java code to improve its object-oriented architecture. Make sure you verify that the project compiles successfully before making any design modifications, keep behavioral contracts intact throughout your edits, run a full build verification once complete, and provide a structured summary detailing the identified design issues by severity, refactorings performed, and final build results.	fail→fail	4,165	5,795	+39%	1	1	0%	183	2,035	+1012%	0	0	—
case-02 We noticed several OOP code smells and encapsulation leaks in our `com.example.inventory` package, particularly around public mutable state and bloated method parameter lists. Please refactor this codebase following solid object-oriented principles. Verify project compilation prior to making changes, run a full verification suite after refactoring, and provide a summary report outlining the diagnosed architectural concerns, applied refactorings, design benefits achieved, and test verification outcome.	fail→fail	3,873	4,982	+29%	1	1	0%	264	2,057	+679%	0	0	—
case-03 Can you review and improve the object design in our payment gateway integration module (`src/main/java/com/app/payment`)? We want better abstraction, cleaner encapsulation, and proper object creation practices. Ensure the project builds properly before modifying any files, preserve existing business behavior, execute a complete build and test run after completing changes, and furnish a breakdown listing the issues found, refactorings applied, and verification status.	fail→fail	4,875	4,867	-0%	1	1	0%	264	2,067	+683%	0	0	—
case-04 We want to perform a dedicated type-design overhaul for our Java domain model, specifically replacing raw primitive Strings and Longs for Money, AccountNumber, and Currency with dedicated domain value types. We do not need a broader object-oriented review of our services or builds.	fail→pass	20,994	3,884	-81%	1	1	0%	3,480	2,405	-31%	0	0	—
case-05 Our team needs a dedicated overhaul of exception handling across our Spring Boot microservice: building a custom runtime exception hierarchy, mapping exception handlers to HTTP status codes, and standardizing exception logging. This is strictly exception architecture, not a general OOD review.	fail→pass	21,981	3,078	-86%	1	1	0%	3,866	2,237	-42%	0	0	—
case-06 We need to design our PostgreSQL table relational schemas, primary key strategies, and Flyway migration scripts for our e-commerce platform. Can you optimize the foreign keys and indexes?	fail→fail	27,157	18,704	-31%	1	1	0%	4,889	4,883	-0%	0	0	—
case-07 Please fix the overall system design across our entire repository. No file paths, class names, or specific OO issues were provided in this request.	pass→pass	8,939	11,032	+23%	1	1	0%	1,194	2,642	+121%	0	0	—
case-08 We have this Java class in our project (`src/main/java/com/app/User.java`): ```java public class User { public String name; public String street; public String city; public String zipCode; public String country; public void printAddress() { System.out.println(street + city + zipCode + country); } } ``` We want to fix the Data Clump and public mutable fields. How do you classify these concerns and which reference file addresses the smells?	fail→fail	10,884	7,045	-35%	1	1	0%	1,896	2,175	+15%	0	0	—
case-09 We attempted an OOD refactoring on `ReportGenerator.java`, but executing `mvn compile` fails due to syntax errors from missing third-party dependencies. Can you proceed with refactoring the class hierarchy despite the compilation error?	fail→pass	9,444	6,044	-36%	1	1	0%	1,280	2,737	+114%	0	0	—
case-10 After completing OOP refactorings to fix Feature Envy in `InvoiceService.java`, what command must be run to execute full project verification in a Maven wrapper project?	pass→pass	4,180	2,142	-49%	1	1	0%	599	2,067	+245%	0	0	—
case-11 In our Java repository, `OrderCalculator.java` duplicates tax calculations across four helper methods and violates the Single Responsibility Principle by directly writing PDF output. Which concern classification and reference file applies to this finding?	fail→pass	5,637	4,618	-18%	1	1	0%	846	2,506	+196%	0	0	—
case-12 We have a complex `HttpRequest.java` class with a 12-parameter constructor and unsafe thread-local initialization. Which reference document covers these creation pattern guidelines?	fail→pass	10,468	4,989	-52%	1	1	0%	1,604	2,646	+65%	0	0	—
case-13 Our legacy `StatusConstants.java` uses integer constants like `public static final int STATUS_ACTIVE = 1;` and array indexing based on ordinals without `@Override` annotations. Which reference file governs these issues?	fail→pass	11,368	3,054	-73%	1	1	0%	1,856	2,257	+22%	0	0	—
case-14 Our `Repository.java` class returns null instead of empty collections when no records exist and lacks defensive copying on array getters. Which reference document covers these method contract rules?	fail→pass	6,444	4,045	-37%	1	1	0%	1,029	2,448	+138%	0	0	—
case-15 We are refactoring `AccountManager.java` which has both a God Class smell and parameter validation bugs returning null collections. Should we load only one reference or multiple references?	pass→pass	12,888	4,365	-66%	1	1	0%	1,896	2,527	+33%	0	0	—
case-16 Before modifying any code in `PaymentService.java` for OOD improvements, what is the mandatory initial build command that must be executed?	fail→pass	5,185	2,156	-58%	1	1	0%	758	2,054	+171%	0	0	—
case-17 A subclass `Square` inherits from `Rectangle` but throws `UnsupportedOperationException` in `setHeight(int h)` because changing height independently violates a square's contract. What OOD refactoring restores clean substitutability?	fail→fail	12,868	14,774	+15%	1	1	0%	2,146	3,669	+71%	0	0	—
case-18 Method `calculateTotal()` in `OrderPrinter.java` calls ten getter methods on `Order` to perform discount arithmetic. What OOD refactoring addresses this smell while preserving behavior?	pass→fail	9,691	5,599	-42%	1	1	0%	1,485	2,006	+35%	0	0	—
case-19 During an OOD refactoring of our order validation logic, a developer suggests altering the exception message returned to API consumers. Does standard OOD refactoring permit changing observable business behavior?	pass→pass	11,783	7,758	-34%	1	1	0%	1,609	2,861	+78%	0	0	—
case-20 When refactoring a large Java class across several distinct steps, how frequently should project compilation be run to maintain safety?	pass→pass	13,170	5,376	-59%	1	1	0%	1,819	2,569	+41%	0	0	—
case-21 Methods across `ShippingService.java` repeatedly pass `String street, String city, String state, String zipCode` together as parameters. What structural OOD improvement fixes this smell?	pass→fail	6,059	6,001	-1%	1	1	0%	986	2,027	+106%	0	0	—
case-22 What key sections must be included in the final report after completing an OOD refactoring workflow on a Java repository?	fail→pass	13,815	4,533	-67%	1	1	0%	2,218	2,475	+12%	0	0	—

These cases were also screened by the skill’s intent / safety pass.See the Trust review ↗Reproduce this benchmark in Colab ↗

How this skill was measured

DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 22 cases were attempted, and 16 counted toward the lift figure. The other 6 produced results that are not comparable between the two arms, so they are excluded from the headline rather than averaged into it. The headline lift of +32 percentage points is the difference between those two pass rates over the 16 comparable cases. 3 cases got worse with the skill loaded, and they are included in that figure.

Model measured: gemini-3.6-flash
Graded by: gemini-3.6-flash
Grading method: judged
Verification: verified
Pass rate without the skill: 31.8%
Pass rate with the skill: 63.6%
Cases attempted: 22
Cases counted toward lift: 16
Cases that regressed: 3
Skill version measured: v1
Run completed: 8/20/2026, 10:00 UTC

Measured example — same prompt, with vs. without the skill · from the benchmark run · case case-04

Prompt

We want to perform a dedicated type-design overhaul for our Java domain model, specifically replacing raw primitive Strings and Longs for Money, AccountNumber, and Currency with dedicated domain value types. We do not need a broader object-oriented review of our services or builds.

Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.

Show both answers

SkillScore blends 4 signalsno signals yet

BenchmarkRun a verified benchmark with positive lift

Live evalNeeds ≥20 evaluated traces in 30 days

AI ratingNeeds ≥10 rated traces

AdoptionNeeds ≥10 serves across ≥2 orgs in 30 days

No signals yet — run a benchmark or collect evaluated traces to earn a score.

Verified on gemini-3.6-flash · re-tested today

Other measured skills in the registry, with their headline benchmark lift.