Creating Spring Boot Projects

Purpose

Use this skill to create new Spring Boot 4 projects or define their structure before implementation. The skill adds value when the user needs an architecture decision, Spring Boot 4 feature selection, or the bundled templates in assets/.

Critical rules

Never jump straight to implementation before assessing project complexity.
Default to the simplest architecture that fits the domain.
Treat Spring Boot 4 as the target. Default new projects to Java 25 (LTS). Accept 21 or 17 when the user asks. Read references/java-version-policy.md before you pick a newer, non-LTS Java.
Read the reference files before choosing a higher-complexity architecture or optional framework feature.
Reuse the templates in assets/ instead of rewriting the same scaffolding from scratch.

Workflow

Step 1: Assess project shape

Collect the project constraints first:

Domain complexity: simple CRUD, moderate workflow, or rich domain rules.
Team size: 1-3, 3-10, or 10+.
Expected lifespan: months, 1-2 years, or 5+ years.
Type-safety needs: basic validation or strong value-object-heavy modeling.
Bounded contexts: single domain or multiple feature areas.
Persistence and infrastructure needs: database choice, migration tool, local development setup.

Step 2: Choose the architecture

Use this matrix as the default decision aid. If the choice is not obvious, read references/architecture-guide.md before proceeding.

Pattern	Use when	Complexity
`layered`	CRUD services, prototypes, MVPs	Low
`package-by-module`	3-5 distinct features with moderate growth	Low-Medium
`modular-monolith`	Module boundaries matter and Spring Modulith is justified	Medium
`tomato`	Rich domain modeling, value objects, stronger type safety	Medium-High
`ddd-hexagonal`	Complex domains, CQRS, strong infrastructure isolation	High

tomato is a value-object-heavy modular monolith: JPA entities embed VOs, validation lives in VO constructors, and Spring converters bind VOs at the request boundary. See references/architecture-guide.md for the full definition.

Step 3: Generate the base project

Pick the generator:

Progen (preferred when installed): check with command -v progen. Read references/progen-integration.md before you use it, and run it with JDK 25: on JDK 27 its output doesn't compile. Progen deletes ./<app-name>/ if it exists, so always run it through scripts/progen_config.py, which validates values and refuses to overwrite.
Spring Initializr: use it when progen is not installed and the user does not want it, or the project does not fit progen (see the reference).

For Spring Initializr, capture the baseline:

Project: Maven or Gradle
Language: Java
Spring Boot: 4.1.x
Java: 25 (LTS). See references/java-version-policy.md.

Baseline dependencies for most projects:

Spring Web MVC
Validation
Spring Data JPA if persistence is required
Flyway or Liquibase
database driver
Spring Boot Actuator
Testcontainers for integration tests

Optional dependencies based on architecture or features:

Spring Modulith for modular monolith or tomato designs
ArchUnit rules (CodeRulesTests, Step 6) for every project
Additional Spring Boot 4 features only when the use case needs them

Read references/spring-boot-4-features.md before selecting:

RestTestClient
HTTP Service Clients
API versioning
JSpecify null-safety
resilience features

Step 4: Apply the matching assets

Use the bundled templates from assets/ and replace placeholders only after the package and module names are settled. If progen generated the project, skip the assets it already covers (see references/progen-integration.md).

Placeholder convention

Every template uses {{TOKEN}} placeholders. Resolve all of them before applying. The templates do not compile until every placeholder is replaced. The full set used across assets/:

Placeholder	Replace with	Example
`{{PACKAGE}}`	Base Java package	`com.acme.shop`
`{{MODULE}}`	Feature/module name (lowercase)	`orders`
`{{NAME}}`	Domain type name (PascalCase)	`Order`, `ProductSKU`
`{{TYPE}}`	Wrapped scalar type inside a value object	`String`, `Long`, `BigDecimal`
`{{FIELD}}`	Record field name (camelCase)	`code`, `amount`
`{{TABLE_NAME}}`	Database table name (used in JPA `@Table`)	`orders`
`{{TABLE}}`	Same meaning as `{{TABLE_NAME}}`. A legacy variant, used only in `flyway-migration.sql`	`orders`
`{{PROJECT_NAME}}`	Project artifactId / docker prefix (used only in `docker-compose.yml`)	`shop-api`
`{{name}}`	HTTP service group identifier, not a lowercase variant of `{{NAME}}`. Appears only in commented `@ImportHttpServices(group = "...")` examples.	`orders`

If a template uses a placeholder not listed here, treat it as a typo and confirm the intended value before applying.

Core project templates:

assets/controller.java
assets/repository.java
assets/base-entity.java
assets/rich-entity.java
assets/value-object.java
assets/spring-converter.java
assets/service-cqrs.java
assets/exception-handler.java
assets/flyway-migration.sql
assets/docker-compose.yml

Boot 4 and modularity templates:

assets/http-service-client.java
assets/api-versioning-config.java
assets/resttestclient-test.java
assets/package-info-jspecify.java
assets/modularity-test.java
assets/resilience-service.java
assets/pom-additions.xml
assets/testcontainers-test.java

Step 5: Fill in architecture-specific pieces

Read references/architecture-guide.md for package structure and apply the matching templates:

layered: keep modules simple and avoid premature DDD abstractions
package-by-module: group by feature and keep shared code minimal
modular-monolith: add Modulith verification and explicit module APIs
tomato: add value objects and rich domain entities where they protect important invariants
ddd-hexagonal: separate application, domain, and infrastructure explicitly

Step 6: Add the build rules

Maven projects get the shared agent setup from the spring-boot-team-harness skill: AGENTS.md, .claude/settings.json with its hooks, project skills, the ./mvnw verify gates, and a CI workflow. Its CodeRulesTests is the project's architecture test: ArchUnit rules for proxied methods called from their own class, controllers that start transactions, use repositories or expose entities, @Retryable that nothing switches on, @Autowired fields, System.out, Jackson 2 and disabled tests. BuildSetupTests checks the pom and properties. Pass --no-modules for layered and ddd-hexagonal, whose subpackages are layers, not modules:

python3 "${CLAUDE_SKILL_DIR}/../spring-boot-team-harness/scripts/apply_harness.py" /path/to/project [--no-modules]

${CLAUDE_SKILL_DIR} is this skill's folder. Codex doesn't set it, so there use the folder this SKILL.md is in.

On a progen project, it keeps what progen already set up (Spotless, Spring Modulith, ModularityTests, ArchUnitTests, AGENTS.md) and adds only what's missing. See references/progen-integration.md for the ArchUnitTests rules that conflict with some architectures. Then run ./mvnw spotless:apply and ./mvnw verify. Expect NullAway to flag progen methods that return null without @Nullable: annotate them and handle the null at the callers. Then draft the Modules, Run and test and Team conventions sections of AGENTS.md from the code, as the harness skill's step 4 describes, and go through them with the user.

The harness supports Maven only. For a Gradle project, copy ../spring-boot-team-harness/assets/tests/CodeRulesTests.java to src/test/java/<package>/CodeRulesTests.java, replace {{TEST_PACKAGE}} and {{BASE_PACKAGE}} with the base package, and add testImplementation 'com.tngtech.archunit:archunit:1.5.1'.

For ddd-hexagonal, also add the onionArchitecture() test from assets/pom-additions.xml.

Step 7: Check the project

Fix every FAIL before you hand the project over:

python3 "${CLAUDE_SKILL_DIR}/scripts/check_new_project.py" /path/to/project

It fails on unresolved {{PLACEHOLDER}} tokens, a Spring Boot version before 4.x, a missing ArchUnit test or dependency, and Boot 3 starter or Testcontainers 1 names. It warns on an older 4.x line and on H2. Then run the build (./mvnw verify or ./gradlew build).

Step 8: Hand off specialized concerns when needed

Use springboot-migration for upgrades of existing applications rather than new-project setup.
Use writing-springboot-tests for tests at the service's edges (HTTP clients, messaging, published events): it has verified Boot 4 templates and the traps that make such tests pass without proving anything.

Reference loading guide

Package structures, anti-patterns, and upgrade paths: references/architecture-guide.md
Spring Boot 4 feature-specific guidance: references/spring-boot-4-features.md
Java version choice, preview-API changes, JDK 26/27 runtime changes: references/java-version-policy.md
Generating the base project with progen: references/progen-integration.md

Available script

scripts/progen_config.py: builds and validates .progen.json, and runs progen with --run.
scripts/check_new_project.py: checks the finished project against this skill (Step 7). Exit 1 means at least one failure.

Output format

When the user asks for a plan or scaffold recommendation, return:

## Recommended architecture
- Pattern:
- Why:

## Initial setup
- Generator: progen or Spring Initializr
- Build tool:
- Java version:
- Spring Boot version:
- Core dependencies:

## Assets to apply
- `assets/...`

## Next implementation steps
1. ...
2. ...
3. ...

When not to use this skill

Migrating an existing Boot project
Deep repository and query tuning without broader project-creation work
Generic Spring Boot feature Q&A with no need for the bundled templates