Spring Boot Full-Stack Developer

Use this skill for Spring Boot project creation and implementation. It includes a Spring Initializr project generator, environment checker, setup assets, domain guides, frontend integration guides, deployment instructions, and a CRUD workshop. All instructions and assets needed by this skill are contained in this directory.

Core Rules

1. Determine the versions before giving version-sensitive guidance. Read the build configuration and establish the exact Spring Boot version, Java version, and build tool. Do not infer them from the installed JDK or from another project.
2. Preserve existing project choices. For existing projects, keep the detected Boot line, build tool, package structure, API contract, and migration strategy unless the requested change requires an update. Do not silently upgrade dependencies or migrate Boot 3.5.x to 4.x.
3. Use Boot 4.x for new projects by default. Boot 3.5.x is supported for existing projects and realistic upgrades; the generator cannot create 3.5.x projects because Spring Initializr no longer offers them. Consult Spring Boot version compatibility and migration before changing versions, starters, or APIs.
4. Read the focused guide for the task. Use the reference map below to select only the relevant guidance. The topic guides describe Boot 4 / Spring Framework 7 / Jackson 3. In a Boot 3.5.x project, first read Working in an existing Boot 3.5.x project and translate topic-guide code with it.
5. Follow the project's dependency management. Prefer the Spring Boot parent or BOM. Check compatibility before overriding managed versions or adding third-party libraries.
6. Keep boundaries clear. Organize new code by business feature where practical. Use request and response DTOs at HTTP boundaries; do not expose persistence entities as API representations.
7. Do not introduce Lombok by default. Prefer explicit constructors, accessors, and logging in new projects and new code. If the existing project uses Lombok, follow its conventions; add Lombok to a project only when the user requests it or the project explicitly requires it.
8. Use Spring MVC by default for server-side web work. Preserve an existing WebFlux stack, or use WebFlux when the requirement explicitly calls for a reactive server. Do not choose WebFlux solely to make outbound HTTP calls non-blocking; use the appropriate HTTP client. Do not guess at WebFlux-specific configuration when the focused guidance does not cover it.
9. Prefer Spring Boot's built-in support and avoid optional infrastructure. Use managed starters, auto-configuration, validated @ConfigurationProperties, configuration binding tests, and the narrowest relevant test slice before adding custom bootstrapping or bespoke test infrastructure. Add authentication, messaging, caching, cloud services, or other optional systems only when the request requires them; preserve established project choices.
10. Choose the narrowest test that proves the behavior. Use unit tests for framework-free logic, Spring slice tests for framework behavior, and the production database through Testcontainers for persistence behavior. Keep full-context tests to a small number of startup smoke and representative request tests. Keep test data and time deterministic; see testing strategy.
11. Verify implementation changes. Use the project's wrapper and established checks. Compile and run relevant tests after code changes; validate Compose configuration after container changes. For generated projects and changes spanning multiple layers, run the best-practices checklist, including its Security section whenever authentication or authorization changes. Report the commands run and their actual results, including checks not run.
12. Use Long primary keys and omit foreign keys by default. Use String identifiers when opaque or externally supplied IDs are a stated requirement. Do not use UUID primary keys or add foreign-key constraints to generated DDL by default. Represent relationships with ID fields and enforce reference existence and lifecycle rules in application code. Follow UUID and database foreign-key guidance only when the user or project explicitly chooses it; retain primary-key, unique, and other approved constraints.
13. Generate MyBatis-Plus persistence SQL through Mapper APIs. Use BaseMapper<T> and MyBatis-Plus Wrapper APIs; keep Mapper interfaces declarative and free of SQL text. Do not define SQL in MyBatis annotations or mapper XML.
14. Use Lambda Wrappers for entity fields. Build entity filters and updates with LambdaQueryWrapper<T> and LambdaUpdateWrapper<T> method references. Use string-based QueryWrapper only for map projections or when no mapped entity property is available.
15. Close the feature boundary before delivery. A feature may access its own Mapper and persistence model only. Cross-feature calls go through the owning feature's public service/facade and exchange commands, results, or read DTOs, never another feature's Mapper or entity. Enforce the dependency direction with package visibility, Modulith, or ArchUnit; see code organization.
16. Keep rate limiting cross-cutting. Prefer a servlet filter, MVC interceptor, or service AOP boundary chosen for the policy's timing and available identity; keep counters and storage in a dedicated limiter component. Do not put limiter branches in controllers or business methods except when a quota must be atomically reserved with a business transaction. See rate limiting.

Version and Environment Discovery

Inspect the repository before implementation:

• Maven: check the parent version or imported Spring Boot BOM in pom.xml, properties, and profiles.
• Gradle: check the Spring Boot plugin and dependency management in the build files and version catalog.
• Java: check the toolchain, compiler release, Maven properties, CI configuration, and project wrapper settings.
• Also read repository instructions, application configuration, existing tests, and relevant neighboring code.

For a new project, use versions.json as the generator's compatibility baseline and defaults. Respect explicit user choices and project constraints. Use node scripts/check-environment.mjs --help and node scripts/create-project.mjs --help for supported options.

Project Workflow

Create a project

Run the bundled scripts from this skill directory and set the output directory to the intended workspace. Do not generate a project inside the skill directory.

node scripts/check-environment.mjs --docker
node scripts/create-project.mjs \
  --name inventory-api \
  --group-id com.example \
  --docker \
  --output-dir /absolute/path/to/workspace

The generator downloads a Boot 4.x project from Spring Initializr and applies this skill's setup assets. Check --help for all arguments and versions.json for version choices.

• Options: --persistence jpa|mybatis-plus|none (default jpa), --database postgresql|none (default postgresql), and --license apache2|mit|none (default apache2). apache2 is the generator option name for Apache License 2.0. Use --copyright-holder when the copyright owner is known; otherwise the generated LICENSE contains a visible placeholder that must be replaced before distribution. --database none implies --persistence none. --docker requires Maven and PostgreSQL.
• Runtime checks: project generation needs the Docker CLI only when adding Docker-specific assets. Before running PostgreSQL Compose, Testcontainers, or a Docker build, check that the daemon is active with node scripts/check-environment.mjs --docker-daemon; --docker checks only for the CLI.
• Always generated: A root LICENSE with the selected license unless --license none is specified; a root renovate.json that leaves Renovate's manifest autodetection enabled, uses the generator host's IANA timezone, adds no broad dependency grouping, leaves major and 0.x updates for human review, and enables PR-based automerge for stable non-major patch/minor/pin updates after checks pass; Spotless formatting (applied once, so the first verify passes); a mise.toml with wrapper-backed format, test, and verify tasks and the selected Java major; and server.port=${SERVER_PORT:8080} so the port variable in .env.sample and Compose takes effect.
• When Docker image/build files are generated: ensure the project has a root .dockerignore merged with the skill template, excluding build output, dependency directories, .git, and local secrets such as .env.
• With PostgreSQL: a local compose.yaml and a Testcontainers configuration pinned to the same PostgreSQL image; Maven projects also run *IT tests through Failsafe.
• Not generated: front-end, VS Code, and Dev Container files, unless their workflow is requested. The generator does not overwrite an existing target, install global tools, or initialize Git.

For changes to generated project defaults or repository files, read project setup. For local PostgreSQL and Compose workflows, read local development.

Change an existing project

1. Identify the requested outcome and scope. Inspect repository instructions, the working tree, build files, configuration, related code, and tests before choosing an approach.
2. Identify the behavior and constraints to preserve. For CRUD or REST work, establish fields, validation, pagination and ordering, status codes, error behavior, persistence changes, and client states. Do not turn unrelated observations into extra work.
3. Read only the applicable topic guides and implement the smallest coherent change in the existing conventions. Add optional infrastructure only when the requirement calls for it.
4. Add or update tests at the narrowest layer that proves the behavior. Use the real database or the project's established integration setup for database-specific behavior.
5. Run relevant checks and review the final diff for unintended changes. For project generation or a change spanning multiple application layers, run the best-practices checklist against the generated or changed code before calling it complete. Report any exception with its evidence and reason; do not describe an unchecked convention as compliant.
6. After all approved implementation slices meet their acceptance criteria, do one bounded cleanup pass against the same checklist. Fix verified deviations and simplify duplicated or needlessly indirect code without changing behavior; avoid speculative abstractions or unrelated rewrites. Re-run the affected checks after cleanup and report any remaining deviation.

If a requirement is ambiguous and affects the API, data model, security, or deployment behavior, state the assumption or ask for the missing decision before locking in the implementation.

Debug a failure

Start from the observed symptom. Inspect the failing code path, configuration, logs, and recent changes; reproduce with the narrowest useful command; test the leading cause; then verify the affected path. If the cause is uncertain, compare plausible causes against evidence instead of changing unrelated code.

Implementation Guidance

• Keep controllers focused on HTTP binding and response mapping. Put business rules and transaction coordination in an appropriate application service; avoid pass-through layers without a clear responsibility.
• For blocking outbound HTTP, prefer Spring's HTTP Service Client (@HttpExchange), which uses RestClient by default in Boot 4. Use RestClient directly when the call is dynamic or needs imperative control. Use WebClient when the application genuinely uses reactive Mono/Flux flows; do not select it just to make blocking calls non-blocking. Set finite connect and read timeouts. See HTTP clients.
• Validate untrusted input at the boundary. Return useful client errors without exposing stack traces, internal details, or secrets.
• Use database migrations for deployed schema changes. Treat automatic schema generation as a local-development aid, not a production migration strategy.
• Use constructor injection for required dependencies; prefer a single constructor and avoid field injection. Follow the project's established Java conventions and the guidance in Java in Spring.
• For new API errors, prefer RFC 9457 ProblemDetail unless the project already has a required error contract.
• Keep credentials outside source control. Use documented environment variables and placeholder values in example environment files.
• For frontend integration, align browser calls with backend routes, validation, pagination, JSON wire types, and error responses. Keep generated wire types at the API boundary; handle loading, empty, success, HTTP-error, and no-response states. Prefer a same-origin API contract when suitable. See OpenAPI, JSON and Jackson, and Error handling.
• Keep operational endpoints and metrics limited to the intended management boundary. Never log credentials, access tokens, or sensitive request payloads.

Testing and Verification

Choose tests according to the behavior under test; the levels complement one another:

Use Testcontainers for PostgreSQL-specific integration behavior unless the project already provides an equivalent real-database environment. See testing strategy, the specific testing guides, and Testcontainers. Run the build tool's wrapper and report actual outcomes; do not claim verification that was not performed.

Java Code Intelligence

Generated projects include .github/lsp.json for JDTLS integration. When a Java language server is available, use semantic navigation for code changes: go to definition, find references before changing a signature, inspect symbols and types, rename symbols with LSP rename, and check diagnostics. Use the JDTLS guide for setup and troubleshooting. If language-server support is unavailable, use Java-scoped search and inspect the relevant call sites.

Reference Guide

Load the guide that matches the task. The focused guides contain implementation details and version-specific caveats; this file defines the workflow and routes requests to those guides.

Spring Boot versions and project setup

• Version selection, changes in a Boot 3.5.x project, or Boot 3.5.x to 4.x migration: Spring Boot version compatibility and migration
• Project generation, defaults, or repository setup assets: Project setup
• Maven build configuration: Maven
• Gradle build configuration: Gradle
• Local development, PostgreSQL/Redis Compose, or DevTools: Local development and Docker
• mise tasks: mise tasks
• Git branches, commits, review, or undo: Git workflow
• Java navigation and JDTLS: JDTLS

Architecture and Java

• Package and feature boundaries: Code organization
• Choosing Strategy, Adapter, events, Outbox, Saga, or CQRS: Design patterns for Spring applications
• Domain model, aggregates, and domain events: Domain modelling
• Java language choices in Spring-managed code: Java in Spring
• Ports and adapters: Hexagonal architecture
• Spring Modulith boundaries and events: Spring Modulith
• Dependency injection, proxies, and self-invocation: Spring proxies and dependency injection
• Architecture tests: ArchUnit

Web and API

• REST endpoints, HTTP semantics, pagination, and idempotent API commands: REST controllers
• Validation: Validation
• Error responses: Error handling
• JSON serialization and Jackson: JSON and Jackson
• API versioning: API versioning
• OpenAPI and API documentation: OpenAPI
• HATEOAS: HATEOAS
• Internationalization: Internationalization
• WebSocket and STOMP: WebSocket
• Thymeleaf views: Thymeleaf
• Serving frontend files and SPA routes: Static resources

Persistence and configuration

• Spring Data JPA entities, repositories, and queries: Spring Data JPA
• MyBatis-Plus: MyBatis-Plus
• Transaction boundaries and propagation: Transactions
• Schema changes and Flyway: Flyway
• SQL, indexes, and schema design: Database schema and SQL
• Backup and recovery objectives, database restore, or recovery drills: Backup and recovery
• Concurrency, locking, and uniqueness races: Database concurrency
• Auditing: Auditing
• Caching, Redis, cache consistency/failure behavior, or Redis Compose: Caching and Docker
• Multi-tenant data isolation: Multi-tenancy
• Profiles, properties, environment variables, and secrets: Configuration

Security

• Filter chains, authorization, passwords, CORS, and CSRF: Security fundamentals
• Multi-factor authentication, WebAuthn/passkeys, staged JWT login, and recovery: MFA
• External OAuth2/OIDC login, SAML SSO, account mapping, and provisioning: OAuth2 login and SSO
• Issuing JWTs for local accounts and token response conventions: JWT authentication
• Validating tokens from an identity provider: OAuth2 resource server

Testing

• Test levels, context caching, and build setup: Testing strategy
• Unit tests: Unit testing
• MVC, JSON, and web client tests: Web slice testing
• JPA and database tests: Persistence slice testing
• Focused application integration, full REST API, outbound HTTP, or provider contract tests: Integration testing
• Containers and service connections (PostgreSQL, Redis, and other dependencies): Testcontainers

Integration and runtime

• HTTP service clients: HTTP clients
• Embedded local developer console: BootUI
• Retries, concurrency limits, and resilience: Resilience
• Kafka, RabbitMQ, JMS, and outbox patterns: Messaging
• Async work and scheduled tasks: Async and scheduling
• Email delivery: Mail
• File upload and storage: File storage
• Rate limiting and resource protection: Rate limiting
• Batch jobs: Spring Batch
• Spring AI applications: Spring AI
• MCP servers: MCP server

Observability and performance

• Logging, health, metrics, tracing, and alerts: Observability and logging
• HTTP server and application performance settings: Performance
• AI and token usage signals: AI observability

Frontend integration

Choose the requested client. For a single-page application packaged into the jar, read the framework guide together with Frontend integration with Spring Boot, which covers the Maven build, SPA route forwarding, and API client rules shared by all of them. Next.js has its own packaging model:

• Vue
• React
• Next.js
• Angular
• Vanilla JavaScript

Containers and deployment

• Dockerfiles, Compose, and container workflows: Docker
• Kubernetes workload manifests, probes, runtime configuration, and rollout behavior: Kubernetes
• Native images and AOT: GraalVM Native Image
• Azure Container Apps deployment: Azure
• CI/CD and release practices: CI/CD and releases
• Guided full-stack implementation: Spring Boot Full-Stack Workshop
• Review an application against the collected conventions: Best practices checklist