Proposal: Claude Skill — Null-Safety Best Practices

[sisimomo]

Create a Claude Skill to guide null-safe Java coding using Error prone, NullAway, and JSpecify for compile time validation, and Jakarta Validation for runtime validation.

NullPointerExceptions (NPEs) are the most common and costly errors in Java, widely considered a “billion-dollar mistake”. Preventing them using improves reliability and maintainability.

---

Core Principle

RUNTIME validation at boundaries. COMPILE-TIME null-safety internally. Prefer non null when possible.

Zone	Components	Strategy
Boundary	Controllers, DTOs, API clients	Runtime validation (@Validated, @Valid ,@NotNull) AND Compile-time safety (@NullMarked / @Nullable + NullAway)
Internal	Services, Domain, Mappers	Compile-time safety (@NullMarked + NullAway)

Validate external inputs; trust internal data to be runtime safe.

---

Class-Specific Guidelines

Class Type	Rules
Controller / Request DTO	@NotNull on required fields, @Nullable on optional fields, runtime + compile validation
Response DTO	Use annotations for API contract, prefer records
Internal Services	No validation, no defensive null checks, use @Nullable only if needed
API Client DTOs	Request DTO: no validation; Response: @NotNull on required fields, @Nullable on optional fields, runtime + compile validation
Kafka / DB Entities	@NotNull on required fields, @Nullable on optional fields, runtime + compile validation

---

Skill Capabilities

• Detect missing or inconsistent nullability annotations
• Suggest @NullMarked / @Nullable placement
• Suggest @Validated / @Valid / @NotNull placement
• Flag missing boundary validation or redundant null checks
• Provide incremental migration guidance
• Utilize Error Prone for static analysis validation (JSpecify annotations), which greatly enhances the skill's ability to detect issues easily.

---

Benefits

• Fewer NPEs
• Cleaner internal logic
• Clear API contracts

---

This skill would helps teams follow robust null-safe practices.