Skill: java-immutability-modeling
Activation Contract
Use this skill when modeling Java data with records, value objects, immutable classes, defensive copies, collection ownership, equality, and state validation.
Do not use this skill for persistence mapping only, serialization-only configuration, generic DTO naming, or non-Java data modeling.
Responsibility
This skill teaches safe Java state modeling. It does not call other skills, impose immutability everywhere, or choose framework annotations unless context requires them.
Required Context
- Java version.
- Whether the type is domain model, value object, DTO, event, command, or persistence entity.
- Mutability requirements and ownership of collections.
- Equality/hashCode expectations.
Context Budget
- Keep this
SKILL.md focused on modeling decisions.
- Use
references/java-immutability.md for records and defensive-copy details.
Hard Rules
- Prefer immutable data for values, messages, events, and DTOs unless mutation is required.
- Validate invariants at construction time.
- Make defensive copies of mutable inputs and outputs when ownership is not transferred.
- Do not expose mutable internals accidentally.
- Use records for transparent immutable aggregates when they match the domain and Java version.
- Avoid records for entities that require identity, lazy mutation, or framework lifecycle constraints unless explicitly supported.
Decision Gates
| Condition |
Action |
| Data is a transparent immutable carrier |
Prefer record if Java version supports it. |
| Mutable component is stored |
Copy on construction and access, or document ownership transfer. |
| Domain invariant exists |
Enforce in constructor/canonical constructor. |
| Type has identity/lifecycle mutation |
Prefer class over record. |
| Collection is returned |
Return immutable copy/view based on ownership contract. |
Execution Steps
- Identify the data role and mutability needs.
- Choose record vs class based on invariants, identity, and framework constraints.
- Define construction validation.
- Protect mutable components.
- Clarify equality and serialization implications when relevant.
Output Contract
Return:
- Modeling choice: record, immutable class, mutable class, or other.
- Invariants and validation point.
- Mutability/ownership policy.
- Equality/hashCode implications.
- Example shape when useful.
References
references/java-immutability.md — Records, defensive copies, and modeling choices.
Assets
1---2name: java-immutability-modeling3description: Trigger: Java immutability, records, value objects, defensive copies, mutable collections, DTO modeling. Model Java data safely and clearly.4license: MIT5---67# Skill: java-immutability-modeling89## Activation Contract1011Use this skill when modeling Java data with records, value objects, immutable classes, defensive copies, collection ownership, equality, and state validation.1213Do **not** use this skill for persistence mapping only, serialization-only configuration, generic DTO naming, or non-Java data modeling.1415## Responsibility1617This skill teaches safe Java state modeling. It does not call other skills, impose immutability everywhere, or choose framework annotations unless context requires them.1819## Required Context2021- Java version.22- Whether the type is domain model, value object, DTO, event, command, or persistence entity.23- Mutability requirements and ownership of collections.24- Equality/hashCode expectations.2526## Context Budget2728- Keep this `SKILL.md` focused on modeling decisions.29- Use `references/java-immutability.md` for records and defensive-copy details.3031## Hard Rules3233- Prefer immutable data for values, messages, events, and DTOs unless mutation is required.34- Validate invariants at construction time.35- Make defensive copies of mutable inputs and outputs when ownership is not transferred.36- Do not expose mutable internals accidentally.37- Use records for transparent immutable aggregates when they match the domain and Java version.38- Avoid records for entities that require identity, lazy mutation, or framework lifecycle constraints unless explicitly supported.3940## Decision Gates4142| Condition | Action |43|---|---|44| Data is a transparent immutable carrier | Prefer record if Java version supports it. |45| Mutable component is stored | Copy on construction and access, or document ownership transfer. |46| Domain invariant exists | Enforce in constructor/canonical constructor. |47| Type has identity/lifecycle mutation | Prefer class over record. |48| Collection is returned | Return immutable copy/view based on ownership contract. |4950## Execution Steps51521. Identify the data role and mutability needs.532. Choose record vs class based on invariants, identity, and framework constraints.543. Define construction validation.554. Protect mutable components.565. Clarify equality and serialization implications when relevant.5758## Output Contract5960Return:6162- Modeling choice: record, immutable class, mutable class, or other.63- Invariants and validation point.64- Mutability/ownership policy.65- Equality/hashCode implications.66- Example shape when useful.6768## References6970- `references/java-immutability.md` — Records, defensive copies, and modeling choices.7172## Assets7374- None.
andresnator