# Spring Boot Plugin for Claude Code (v1.2)
A Claude Code plugin with production-ready skills and agents for building Spring Boot 4.x / Java 21+ applications. Install the plugin and start generating your app — the skills and agents guide Claude to follow best practices for REST APIs with Problem Details errors, JPA, Flyway database migrations, security, testing, cloud-native deployment, and Kubernetes.
## Installation
Install from Anthropic marketplace
```bash
claude plugin install spring-boot-template@piomin
```
Or install directly from repository
```
claude plugin marketplace add https://github.com/piomin/claude-ai-spring-boot.git
claude plugin install spring-boot-template@piomin
```
To test locally during development:
```bash
claude --plugin-dir /path/to/claude-ai-spring-boot
```
## What's Included
### Agents (`agents/`)
Specialized agents that Claude Code can invoke for specific tasks:
| Agent | Purpose |
|-------|---------|
| `spring-boot-engineer` | Build Spring Boot 4.x apps with layered architecture and Problem Details errors; adds the OpenAPI contract rules when the API is built for a UI |
| `code-reviewer` | Review code for correctness, security, Spring Boot conventions, and API contract quality for APIs built for a UI |
| `kubernetes-specialist` | K8s deployments, probes, ConfigMap/Secret, Prometheus, Skaffold |
| `devops-engineer` | CI/CD pipelines, Paketo Buildpacks, Skaffold |
| `docker-expert` | Multi-stage Dockerfiles, Paketo Buildpacks, image optimization |
| `security-engineer` | Spring Security, OWASP, input validation, SSL Bundles |
### Skills (`skills/`)
Reusable knowledge that Claude loads contextually:
| Skill | What it teaches |
|-------|-----------------|
| `conventions` | Mandatory project rules: No Lombok, constructor injection, RestClient, testing standards, conditional Flyway for relational databases, Problem Details, conditional OpenAPI contract rules for APIs built for a UI |
| `spring-boot` | Core Spring Boot development with 6 reference guides (web incl. Problem Details and paging, OpenAPI with springdoc 3, data incl. Flyway migrations, security, cloud, testing) |
| `code-quality` | Clean code principles, API contracts, null safety, exception handling |
| `design-patterns` | Classic patterns (Factory, Builder, Strategy) + enterprise (Saga, Outbox, CQRS) |
| `testing-patterns` | JUnit 5, Mockito, MockMvc, RestTestClient, Testcontainers with @ServiceConnection, relation and status-endpoint integration tests, Podman |
| `java-modern` | Java 21+ features: records, sealed classes, pattern matching, virtual threads |
| `jpa-patterns` | JPA/Hibernate pitfalls (N+1, lazy loading), Hibernate 6/7, optimistic locking across HTTP requests, relation writes with OSIV off, schema drift |
| `logging-patterns` | Structured JSON logging, SLF4J, MDC, AI-friendly formats |
### Key Conventions
The plugin enforces these rules via the `conventions` skill:
- **No Lombok** — explicit constructors, getters/setters, `LoggerFactory.getLogger()`
- **Constructor injection** — no `@Autowired` on fields
- **RestClient** over RestTemplate/WebClient for blocking HTTP calls
- **RestTestClient** with `@AutoConfigureRestTestClient` for integration tests
- **Testcontainers** with `@ServiceConnection` (not `@DynamicPropertySource`)
- **Jakarta Persistence** (not `javax.persistence`)
- **Problem Details** (RFC 9457) for every error; **paged lists** as `PagedModel`; **optimistic locking** with `@Version` and 409
- **OpenAPI contract rules**, only when the API is built for a UI (see below)
- **Flyway** owns the schema (`ddl-auto: validate`) when the API persists to a Flyway-supported relational database; skipped for APIs without persistence, NoSQL-only APIs, or projects already using Liquibase
- **Maven** with `pl.piomin.services` group ID
- **CI pipeline** — auto-detected from existing project config
- **Docker Compose** for local dependencies
### Cloud-Native Coverage
The `cloud.md` reference covers:
- Spring Cloud (Config Server, Eureka, Gateway, Resilience4j, LoadBalancer)
- Distributed tracing with OpenTelemetry (OTLP) and Micrometer Observation API
- Virtual Threads, HTTP Interface Clients (`@HttpExchange`), GraalVM Native Image
- Kubernetes: ConfigMap/Secret with `envFrom`, Prometheus annotations, startup/liveness/readiness probes, `preStop` hook, graceful shutdown
- TLS: cert-manager (Ingress TLS + pod-level mTLS), SSL Bundles with hot reload
- Config Tree for reading mounted secrets from files
- Paketo Buildpacks via `spring-boot:build-image`
- Skaffold for local K8s development loop
## Usage
After installing, describe what you want to build — Claude will use the skills and agents automatically:
```bash
cd my-project
claude
> "Build a REST API for managing orders with PostgreSQL"
```
For a relational database like PostgreSQL, the generated app includes Flyway migrations in `src/main/resources/db/migration`, `ddl-auto: validate`, and Testcontainers tests that verify all migrations were applied. APIs without persistence or with NoSQL stores get no Flyway configuration.
### APIs built for a UI
Some rules are **required only when the API is built for a UI** (or another client generated from its OpenAPI contract), for example a UI made from [crud-ui-blueprint](https://github.com/mmartofel/crud-ui-blueprint). Say so in your prompt ("the API backs a web UI generated from its OpenAPI contract") or in the project's `CLAUDE.md`. The `conventions` skill then loads `skills/spring-boot/references/ui-contract.md`, the single source of these rules:
- `/api` base path, same origin (no CORS), operationIds the UI's generated client relies on
- an OpenAPI contract generated by springdoc 3, exported to `contract/openapi.json` by a test and checked in CI, with `info.version` from the build
- Problem Details field errors with a fixed set of codes the UI translates, `PUT` with a required `version`
- typed list filters, relations as `{id, label}` summaries, 409 `in-use` instead of cascading deletes
- the Keycloak realm layout the UI logs in with, public `/actuator/health` and `/actuator/info`, and a README "Connect a UI" section
Without a UI, none of this is required: the generated API keeps Problem Details, paging and optimistic locking, and skips the contract export.
You can also invoke skills and agents directly:
```bash
# Invoke a skill
> /spring-boot-template:jpa-patterns
# Use an agent
> @agent-spring-boot-template:code-reviewer
```
## Directory Structure
```
.
├── .claude-plugin/
│ └── plugin.json
├── agents/
│ ├── code-reviewer.md
│ ├── devops-engineer.md
│ ├── docker-expert.md
│ ├── kubernetes-specialist.md
│ ├── security-engineer.md
│ └── spring-boot-engineer.md
├── skills/
│ ├── conventions/SKILL.md
│ ├── code-quality/SKILL.md
│ ├── design-patterns/SKILL.md
│ ├── java-modern/SKILL.md
│ ├── jpa-patterns/SKILL.md
│ ├── logging-patterns/SKILL.md
│ ├── spring-boot/
│ │ ├── SKILL.md
│ │ └── references/
│ │ ├── cloud.md
│ │ ├── data.md
│ │ ├── ui-contract.md
│ │ ├── security.md
│ │ ├── testing.md
│ │ └── web.md
│ └── testing-patterns/SKILL.md
├── README.md
└── LICENSE
```
## Blog Post
You can find a detailed explanation of this plugin in the post: [Claude Code Template for Spring Boot](https://piotrminkowski.com/2026/03/24/claude-code-template-for-spring-boot/).
## License
Apache License 2.0