coding-standards

name	coding-standards
description	Unified Java code review + coding standards skill (alias "code-review"). Enforces ALL six rule sets — CORE-*, MVC-*, RX-*, WFL-*, XCT-*, JKS-* — across BUILD (REFACTOR self-check) and REVIEW (Stage 2 findings). Every finding cites [<P0-P4>][<RULE-ID>]. Also encodes Java 17+ patterns (records, sealed, pattern matching), naming, Lombok, immutability, Optional/Stream rules. Use whenever Claude writes new Java code, reviews a diff, refactors, or audits style. MANDATORY TRIGGERS — Java, Spring Boot, Spring MVC, Spring WebFlux, Project Reactor, Jackson, ObjectMapper, @JsonProperty, @JsonCreator, @JsonTypeInfo, @JsonFormat, JSON, BigDecimal, money, @Transactional, R2DBC, JpaRepository, Mono, Flux, WebClient, code review, audit, refactor, REFACTOR step, /dc-review, /build.
triggers	{"natural":["naming convention","java pattern","code style","immutability","records","code review","rule citation","jackson","json","ObjectMapper"],"code":["*.java"],"command":["/dc-review","/build"]}
applicability	{"always":true,"triggers":{"files_match":["**/*.java"],"code_patterns":["@Value","@RequiredArgsConstructor","record","@Builder","ObjectMapper","@JsonProperty","@JsonFormat","@JsonCreator"],"task_keywords":["coding style","code review","immutability","naming","records","Lombok","jackson","json","BigDecimal"],"related_rules":["rules/common/coding-style.md","rules/java/coding-style.md","rules/java/code-review-core.md","rules/java/code-review-mvc.md","rules/java/code-review-reactor.md","rules/java/code-review-webflux.md","rules/java/code-review-crosscut.md","rules/java/code-review-jackson.md"]}}
relevance_assessment	Always 100% when project has Java files. Applies to every code change and every review.

Coding Standards + Code Review — Unified Enforcement

One skill, two phases. BUILD: self-check critical rule IDs during REFACTOR. REVIEW: surface findings tagged [<severity>][<RULE-ID>]. Detailed workflows live in references/.

Rule sets enforced

Prefix	File	Domain	Count
CORE-*	rules/java/code-review-core.md	Null · equality · money · exceptions · resources · immutability · collections · concurrency · logging · API design	~41
MVC-*	rules/java/code-review-mvc.md	Controller · validation · response · service · repository · transaction · config · exception · security (servlet stack)	~31
RX-*	rules/java/code-review-reactor.md	Operators · schedulers · context · subscription · pitfalls · testing	~22
WFL-*	rules/java/code-review-webflux.md	Reactive controller · R2DBC · transaction · WebClient · server · security · error handling	~24
XCT-*	rules/java/code-review-crosscut.md	Idempotency · observability · testing · docs · deps. + PR checklist + severity P0-P4 + full ID catalog	~15
JKS-*	rules/java/code-review-jackson.md	ObjectMapper · modules · annotations · polymorphism · date/time · BigDecimal · streaming · security · perf · Spring · records · testing · versioning	~65

Total: ~198 rules. Full catalog: rules/java/code-review-crosscut.md §8 (+ JKS §17 in jackson file).

Conditional load per stack

Stay token-efficient — load only relevant rule sets:

Stack signal	Rule sets to load
Any Java diff	CORE + XCT (always)
spring-boot-starter-web + JpaRepository	+ MVC
Mono< / Flux< in diff	+ RX
spring-boot-starter-webflux	+ RX + WFL
ObjectMapper / @JsonProperty / DTO with date or BigDecimal	+ JKS (+ load references/jackson-review-workflow.md)
io.f8a.summer dep	+ rules/summer/*

skills/preflight/references/gate-mappings.md drives the selection at variants 4 (execute) and 5 (review).

Detailed workflows — load on demand

Reference	When to load	Content
references/review-workflow.md	Stage 2 review · BUILD REFACTOR self-check · /dc-review invocation	Priority-ordered scan across ALL 6 rule sets · output format · verdict logic · severity policy
references/jackson-review-workflow.md	Diff touches Jackson (ObjectMapper, @Json*, DTO with BigDecimal/date)	Jackson-specific priority scan · output format · context-specific guidance (payment / SIMO / Kafka / REST) · workflow examples
references/java-patterns.md	Writing new Java code · refactoring patterns	Immutability (records, builders, defensive copies) · null safety (Optional patterns) · concurrency · collections · streams. Pattern → rule ID map.

Read these only when needed — keep main context clean.

BUILD phase — REFACTOR self-check

Slice-executor verifies these critical IDs before declaring a slice done. Full priority-ordered scan in references/review-workflow.md.

Always (any Java)

• CORE-NUM-001 — no double/float for money. BigDecimal only.
• CORE-LOG-002 — no sensitive data in logs (password, OTP, full PAN, CVV, JWT, full national ID).
• CORE-EXC-004 — service boundary wraps IOException/SQLException to business exception.
• CORE-API-001 — method ≤ 50 LOC, class ≤ 400 LOC (800 abs max).

MVC stack

• MVC-TX-001 — no HTTP call inside @Transactional.
• MVC-TX-002 — Kafka publish uses outbox pattern (same TX as DB).
• MVC-VAL-001 — @Valid on @RequestBody.
• MVC-REP-004 — N+1 query check (entity graph / fetch join).

Reactive

• RX-FND-001 — no .block() in reactive chain.
• RX-OPS-002 — switchIfEmpty(Mono.defer(...)), not direct Mono.error().
• WFL-WC-002 — explicit timeouts on WebClient.

Jackson (load references/jackson-review-workflow.md for full scan)

• JKS-OBJ-001 — no new ObjectMapper() in service body. Inject from Spring.
• JKS-MOD-001 — JavaTimeModule registered when using java.time.*.
• JKS-MNY-001 — BigDecimal serialized as string (@JsonFormat(shape = STRING) or WRITE_BIGDECIMAL_AS_PLAIN). Fintech-critical.
• JKS-POL-002 / JKS-POL-003 — no JsonTypeInfo.Id.CLASS; no enableDefaultTyping() without validator. RCE prevention.
• JKS-ANN-003 — passwords/secrets @JsonIgnore or WRITE_ONLY.
• JKS-PRF-002 — TypeReference for generic deserialize.

Cross-cutting

• XCT-IDM-001 — Idempotency-Key for mutation endpoint.

Cite enforced IDs in the slice result report and commit body (see agents/slice-executor.md).

REVIEW phase — Stage 2 findings

Every finding has format [<P0-P4>][<RULE-ID>]. Missing rule ID = invalid output, orchestrator rejects and re-dispatches.

Common citation patterns

Pattern	Rule	Severity
double for money	CORE-NUM-001	P0
Sensitive data in log	CORE-LOG-002	P0
JsonTypeInfo.Id.CLASS (RCE)	JKS-POL-002	P0
enableDefaultTyping() (RCE)	JKS-POL-003	P0
BigDecimal as JSON number	JKS-MNY-001	P0
Password serialized	JKS-ANN-003	P0
HTTP inside @Transactional	MVC-TX-001	P1
.block() in reactive	RX-FND-001	P1
new ObjectMapper() per call	JKS-OBJ-001	P1
N+1 query	MVC-REP-004	P1
Silent swallow JsonProcessingException	JKS-ERR-001	P2
Unstructured log	CORE-LOG-004	P3

Verdict logic (per rules/java/code-review-crosscut.md §7)

• Any P0, or P1 without ADR → Block
• P1 with ADR, or P2 only → Approve with caveats
• P3/P4 only → Approve

Detailed dispatch and output format live in references/review-workflow.md.

Coding patterns — quick reference

Apply when writing code. The same patterns drive REFACTOR self-check (citing the corresponding rule IDs).

Java 17+

• Records — DTO, value objects, events. Compact constructor for validation. Not for JPA entities or Spring beans. Records work natively with Jackson 2.12+ (JKS-REC-001).
• Sealed classes — exhaustive type hierarchies. Combine with Jackson sealed support (JKS-POL-004, JKS-REC-004).
• Pattern matching instanceof — if (event instanceof OrderCreatedEvent e).
• Switch expressions, text blocks — prefer over chained if-else and string concat.

Naming

Element	Convention	Example
Class	PascalCase	OrderService
Method	camelCase, verb-first	createOrder()
Test	shouldDoXWhenY	shouldReturnOrderWhenIdExists()
Constant	UPPER_SNAKE_CASE	MAX_RETRY_ATTEMPTS
Boolean	is/has/can prefix	isActive()
Exception	Descriptive + Exception suffix	OrderNotFoundException

Lombok

Annotation	Use	Avoid
@RequiredArgsConstructor	Spring beans	DTOs (records are better)
@Value	Immutable non-record (JPA entities)	Where record fits
@Builder(toBuilder=true)	≥3-field construction	1-2 field objects
@Slf4j	Any class that logs	—

Never @Data — generates setters and violates immutability.

public record CreateOrderRequest(@NotBlank String productId, @Positive int quantity) {}

@Service @RequiredArgsConstructor @Slf4j
public class OrderService {
    private final OrderRepository orderRepository;
}

Immutability (CORE-IMM-001..003)

• Final fields by default.
• Records + @Builder(toBuilder = true) + @With for new-instance updates.
• Defensive copies: List.copyOf(items) in constructor and getter.
• Never mutate inside reactive chains — transform with .map().

Optional & streams

• Optional: return type only. Never field, parameter, or collection element (CORE-NUL-002).
• Streams: filter early. Primitive streams for numerics. No side effects in map/filter (CORE-COL-002). Collect to unmodifiable (CORE-COL-004). Never parallelStream() without benchmark (CORE-COL-003).

Error handling

• Domain exception extends RuntimeException with an ErrorCode enum (CORE-EXC-004 / CORE-EXC-005).
• Specific exceptions: OrderNotFoundException, InsufficientStockException.
• Never generic RuntimeException. No empty catch blocks (CORE-EXC-002).
• Reactive: switchIfEmpty(Mono.error(...)), onErrorMap(), onErrorResume() (RX-OPS-002 / RX-OPS-003).

Code-pattern depth lives in references/java-patterns.md.

Skill announcement

When loading this skill, announce:

Skill loaded: coding-standards (unified code-review enforcement)
Rule sets active: CORE, XCT [+ MVC if MVC] [+ RX/WFL if reactive] [+ JKS if Jackson DTO/ObjectMapper]
References ready: review-workflow.md, jackson-review-workflow.md (if Jackson), java-patterns.md
Total rule IDs available: ~198
Citation format: [<P0-P4>][<RULE-ID>]

Related rules

• rules/java/code-review-core.md — CORE-* foundation (always for Java)
• rules/java/code-review-mvc.md — MVC-* (servlet stack)
• rules/java/code-review-reactor.md — RX-* (reactive)
• rules/java/code-review-webflux.md — WFL-* (WebFlux)
• rules/java/code-review-crosscut.md — XCT-* + PR checklist §6 + severity P0-P4 §7 + rule catalog §8
• rules/java/code-review-jackson.md — JKS-* (Jackson — fintech BigDecimal + RCE prevention)
• rules/java/coding-style.md — Lombok, DI, error handling shorthand
• rules/common/coding-style.md — common style conventions

Related skills

• spring-mvc-patterns — servlet stack patterns
• spring-webflux-patterns — reactive patterns
• architecture — hexagonal layer rules
• testing-workflow — TDD cycle, test naming
• pentest — OWASP scanning (pairs with JKS-POL-* / JKS-SEC-* for deserialization CVE)