Claude Skill

creating-springboot-projects

Use when starting a new Spring Boot project or service: scaffolding or bootstrapping a backend, REST API, microservice or modular monolith; choosing how to structure it (layered, package-by-module, modular monolith, tomato, DDD-hexagonal); selecting Spring Boot 4 features; genera

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download a-pavithraa-springboot-skills-marketplace-plugins_springboot-architecture_skills_creating-springboot-projects-b2358f9.zip · 58 KB

Install

skills CLI npx skills add https://github.com/a-pavithraa/springboot-skills-marketplace/tree/main/plugins/springboot-architecture/skills/creating-springboot-projects
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install a-pavithraa-springboot-skills-marketplace@llmmart
Git git clone https://github.com/a-pavithraa/springboot-skills-marketplace.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole a-pavithraa/springboot-skills-marketplace collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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.

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.

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
Files (springboot-skills-marketplace)
  • assets
    • api-versioning-config.java 9.2 KB · in bundle
    • base-entity.java 1.2 KB · in bundle
    • controller.java 2.9 KB · in bundle
    • docker-compose.yml 2 KB
      Loading…
    • exception-handler.java 3.3 KB · in bundle
    • flyway-migration.sql 5.5 KB · in bundle
    • http-service-client.java 6.2 KB · in bundle
    • modularity-test.java 5.5 KB · in bundle
    • package-info-jspecify.java 9.4 KB · in bundle
    • pom-additions.xml 7.7 KB · in bundle
    • repository.java 3 KB · in bundle
    • resilience-service.java 3.6 KB · in bundle
    • resttestclient-test.java 10.7 KB · in bundle
    • rich-entity.java 4.9 KB · in bundle
    • service-cqrs.java 4.3 KB · in bundle
    • spring-converter.java 2.9 KB · in bundle
    • testcontainers-test.java 5.6 KB · in bundle
    • value-object.java 3.8 KB · in bundle
  • references
    • architecture-guide.md 9 KB
      Loading…
    • java-version-policy.md 3.1 KB
      Loading…
    • progen-integration.md 9.9 KB
      Loading…
    • spring-boot-4-features.md 19 KB
      Loading…
  • scripts
    • align_progen_project.py 3.9 KB
      Loading…
    • check_new_project.py 7.1 KB
      Loading…
    • progen_config.py 12.4 KB
      Loading…
  • SKILL.md 10.6 KB
    ---
    name: creating-springboot-projects
    description: "Use when starting a new Spring Boot project or service: scaffolding or bootstrapping a backend, REST API, microservice or modular monolith; choosing how to structure it (layered, package-by-module, modular monolith, tomato, DDD-hexagonal); selecting Spring Boot 4 features; generating the base project with progen or Spring Initializr; or applying the bundled templates and references in this skill. Not for migrating existing projects or for isolated JPA/repository work without broader project-creation context."
    ---
    
    # 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.
    
    | 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:
    
    ```bash
    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:
    
    ```bash
    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:
    
    ```markdown
    ## 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
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.