robsonkades/agent-skills/spring-boot-jpa

Spring Boot JPA

Scope and activation

Own the integration between Spring Boot 4, Spring Data JPA, the resolved persistence provider and the database. Activate for repository implementation, surprising SQL, lost updates, lazy-loading failures, type/identifier mismatches, transaction failures, or datasource/property reviews. For a new maintained service, deliver the requested persistence path with migrations and shared database invariants; read persistence delivery. In-memory storage is a delivery choice for an explicitly disposable scope; isolated test fixtures remain appropriate.

Preserve the requested mode: a review produces findings; diagnosis produces supported explanations and the next discriminating check; implementation changes only authorized code/configuration/schema. An adequate JDBC query is a valid outcome. Do not introduce JPA merely because this skill was selected, migrate Boot 3 automatically, or treat JPA as reactive persistence. Distributed delivery, API documentation and deep execution-plan tuning belong to their specialists.

Establish the persistence contract

1. Read the build and resolved dependencies, compiler/runtime, CI image, datasource

configuration, active profiles and migrations. Record exact Boot, Spring Data, provider, pool, JDBC driver and database versions. Boot 4.x is the scope, not a promise that all its releases manage identical APIs. Use Java 25 for this skill's recommendations and new examples. The fixture uses Boot 4.1.1, Java 25, Hibernate 7.4.5.Final and BOM-managed dependencies. If an existing target uses an older Java baseline, identify the compatibility boundary before applying examples; do not silently upgrade that project. Hibernate annotations require Hibernate. Use the official Spring Data JPA reference for repository contracts and Spring Boot documentation for auto-configuration and test integration. Select versions matching the resolved project, not simply the documentation's default release. When authorization or an auditing principal affects the persistence path, consult the matching Spring Security reference for that boundary; query filtering alone is not an authentication policy. Hibernate and database primary sources complement these contracts where provider behavior matters.

1. Trace one operation through repository, persistence unit, transaction manager and

physical datasource. Inspect component/entity/repository scanning and custom beans before adding configuration that may make auto-configuration back off. With multiple datasources, prove the repository's entity-manager factory and transaction manager bindings; @Primary alone does not establish the intended atomicity.

1. Establish required rows, fields, ordering, pagination, updates, tenant/authorization

checks, uniqueness and concurrency rules. Inspect actual DDL, constraints, indexes, sequence definitions and existing writers. An annotation is not proof of deployed DDL. Trace the callers too: absence versus required lookup, returned shape and lifetime, read freshness, result size, conflicting edits and whether success means committed work or participation in an outer transaction. Read tests and ADRs before changing those contracts. Existing jobs and rolling application versions are consumers too. For entity creation or mapping review, inventory every persistent attribute, including optional, inherited, embedded, relationship, generated and version attributes. Establish its complete applicable storage, null, validation and write-ownership contract; do not stop at nullable=false or only inspect required fields. Deliberate defaults are valid; copying every annotation argument is not completeness.

1. Separate explicit requirements and documented rules from recurring conventions,

isolated examples and assumptions. Follow the existing package/bean style when adequate. New code uses a single constructor or bean-method parameters without @Autowired; do not add both scanning and a factory for the same bean. Prefer Boot-managed persistence and concrete Spring Data repositories. When the project uses domain ports and persistence adapters, retain that boundary instead of injecting Spring Data into the domain; the delivery reference explains the naming and translation. Keep entities free of interfaces or factories introduced solely to share test code; retain mapping overrides only when the storage contract requires them. Adapt an example only for the operation being implemented: a normal update needs neither a provider-probe harness nor failure methods in the production service. Add auditing, custom entity equality, pessimistic locks or generator tuning only for an identified consumer requirement.

1. Ask only for unresolved facts that change correctness after inspecting the evidence.

For example: "Can a deleted company's identifier be reused, and do the existing jobs follow that rule? This determines the unique constraint and lookup predicate; retain the established behavior if it is documented." Do not invent deletion, retention or conflict policy. Group decisive questions, state a recommendation when supported, and continue independent work with explicit reversible assumptions for low-impact details. Without database access, review contracts and compile examples, but leave dialect, lock, plan and load claims explicitly unverified.

For material choices, identify what to apply for the invariant, reuse from the project, clarify before dependent work, defer with a trigger, or reject as unnecessary. Record only decisions that affect the delivered contract; do not produce five labels for every annotation. Use persistence delivery when changing a repository consumer contract or planning a maintained schema/use-case path.

Essential decisions