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:

1. Domain complexity: simple CRUD, moderate workflow, or rich domain rules.
2. Team size: 1-3, 3-10, or 10+.
3. Expected lifespan: months, 1-2 years, or 5+ years.
4. Type-safety needs: basic validation or strong value-object-heavy modeling.
5. Bounded contexts: single domain or multiple feature areas.
6. 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.

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/:

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.

This also adds the observability pack, so every new project starts with traces, metrics, logs, a local Grafana stack and a dashboard. See docs/observability.md in the generated project.

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.

On a Gradle project, the harness puts the same gates in gradle/harness.gradle and applies it from the build file; then run ./gradlew spotlessApply and ./gradlew build.

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