Coding Standards

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

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:

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

Detailed workflows — load on demand

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

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

Lombok

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)