v0.15.0-SNAPSHOT to v0.15.0

---

name: 122-java-type-design

description: Use when you need to review, improve, or refactor Java code for type design quality — including establishing clear type hierarchies, applying consistent naming conventions, eliminating primitive obsession with domain-specific value objects, leveraging generic type parameters, creating type-safe wrappers, designing fluent interfaces, ensuring precision-appropriate numeric types (BigDecimal for financial calculations), and improving type contrast through interfaces and method signature alignment. This should trigger for requests such as Review Java code for type design; Improve type design in Java code; Fix primitive obsession in Java code; Create value objects in Java code. Part of cursor-rules-java project

license: Apache-2.0

metadata:

author: Juan Antonio Breña Moral

---

# Type Design Thinking in Java

Review and improve Java code using comprehensive type design principles that apply typography concepts to code structure and organization for maximum clarity and maintainability.

**What is covered in this Skill?**

- Clear type hierarchies: nested static classes, logical structure

- Consistent naming conventions: domain-driven patterns, uniform interface/implementation naming

- Strategic whitespace for readability

- Type-safe wrappers: value objects replacing primitive obsession (EmailAddress, Money)

- Generic type parameters: flexible reusable types, bounded parameters

- Domain-specific fluent interfaces: builder pattern, method chaining

- Type weights: conceptual importance — core domain vs supporting vs utility

- Type contrast through interfaces: contract vs implementation separation

- Aligned method signatures: consistent parameter and return types across related classes

- Self-documenting code: clear descriptive names

- BigDecimal for precision-sensitive calculations (financial/monetary operations)

- Strategic type selection: Optional, Set vs List, interfaces over concrete types

**Scope:** The reference is organized by examples (good/bad code patterns) for each core area. Apply recommendations based on applicable examples.

## Constraints

Before applying any type design 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

- **BEFORE APPLYING**: Read the reference for detailed examples, good/bad patterns, and constraints

- **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 type design

- Improve type design in Java code

- Fix primitive obsession in Java code

- Create value objects in Java code

- Create type hierarchies in Java code

- Create fluent interfaces in Java code

## Workflow

1. **Compile project before type-design changes**

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

2. **Read type-design reference and inspect code**

Read `references/122-java-type-design.md` and identify type hierarchy, naming, and value-object improvements.

3. **Apply type-design refactorings**

Implement selected type-safety and readability improvements based on applicable patterns.

4. **Verify with full build**

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

## Reference

For detailed guidance, examples, and constraints, see [references/122-java-type-design.md](references/122-java-type-design.md).