Enterprise standards for Java 17 or newer and Spring Boot 3 or 4, on Maven or Gradle. Maintainer: Emerson Lima — https://github.com/Emersondll
This package tells a person or a coding agent how to write, review, and change a Spring Boot service. It does not generate a sample product. It does not add a class, a dependency, or a pattern that the repository does not already use and that the task does not ask for.
Quarkus, Micronaut, and Jakarta EE application servers are out of scope. Optional stacks (WebFlux, Batch, Spring Integration, Kafka, Redis, Liquibase, Keycloak, Helm, a second CI system) are documented for a service that already has them, or for a task that asks for them.
SKILL.mdis the contract: conduct, rules, the router, and precedence.references/01-versions.mdis the only place for Java, Spring Boot, starter, JaCoCo, SpotBugs, and image-major numbers. A version written in another file is a token to fill from that matrix.- Open one topic file for the task. Do not load the whole tree.
- When two files disagree, follow
SKILL.mdfor behavior andreferences/01-versions.mdfor versions.references/workflows/practices.mddoes not override a numbered reference.
The short map is references/00-index.md. The one-page rules are references/02-rules.md. Conduct is references/03-conduct.md.
java-spec/
├── SKILL.md contract and router
├── README.md this file
├── scripts/
│ └── audit_java.py mechanical checks (tree-sitter)
└── references/
├── 00-index.md … 39-refactor-checklist.md
└── workflows/ procedures, not extra rules
Numbers are unique. There is no 01b, 06b, or 20c. The two digits are the file id. The slug is the subject. Workflows stay in workflows/ so a procedure is not confused with a topic of the same name (17-openapi.md is the contract shape; workflows/generate-openapi.md is how to write the file).
| File | Subject |
|---|---|
SKILL.md |
Rules, router, precedence |
references/00-index.md |
File list |
references/01-versions.md |
Java 17+, Boot 3 and Boot 4, starters, tool floors |
references/02-rules.md |
One-page rules |
references/03-conduct.md |
How to work: no unused type, no new pattern, JavaDoc, OpenAPI from real mappings |
| File | Subject |
|---|---|
references/workflows/generate-openapi.md |
Write openapi.yaml from the controllers. JavaDoc in the same change |
references/workflows/rest.md |
Resource URLs, verbs, status codes |
references/workflows/run-tests.md |
Unit, slice, integration, end-to-end, coverage, mutation |
references/workflows/refactor.md |
Change structure without changing behavior |
references/workflows/write-docs.md |
README, JavaDoc, runbooks |
references/workflows/practices.md |
Design choices that lose to a numbered reference |
| File | Subject |
|---|---|
references/04-architecture.md |
Packages, layering, API version in the path |
references/05-hexagonal.md |
Ports and adapters, only when the project is already hexagonal |
references/06-quality.md |
Style, null-safety, Lombok, Checkstyle, SpotBugs, Sonar |
references/07-java.md |
Records, sealed types, pattern matching, JavaDoc |
references/15-imports.md |
Import order. No wildcards |
references/16-annotations.md |
Spring stereotypes |
references/39-refactor-checklist.md |
Tick list used with the refactor workflow |
| File | Subject |
|---|---|
references/17-openapi.md |
Shape of the OpenAPI document. Not a catalog of endpoints |
references/19-errors.md |
One RFC 9457 body (ErrorResponse, application/problem+json) |
references/21-pagination.md |
List contract |
references/28-idempotency.md |
Idempotency-Key on unsafe creates |
references/13-sync-async.md |
A result the caller needs now stays synchronous. Later work is a message |
| File | Subject |
|---|---|
references/22-mongodb.md |
MongoDB indexes and Mongock |
references/23-jpa.md |
JPA indexes and Flyway |
references/24-profiles.md |
dev, test, and prod profiles |
references/33-data.md |
PostgreSQL, MySQL, JDBC, Redis, Liquibase, isolation, locking, deadlocks |
A new service uses YAML. A repository that already uses application.properties keeps that file. The same key is not defined in both.
| File | Subject |
|---|---|
references/25-maven.md |
Single-module pom.xml, Surefire, Failsafe, JaCoCo |
references/26-gradle.md |
Kotlin or Groovy DSL, catalog, cache, locking, test suites |
references/27-maven-advanced.md |
Multi-module reactor, Enforcer, reproducible build, PMD |
Keep the build tool the repository already has. Do not mix Maven and Gradle. The gate is ./mvnw verify or ./gradlew check.
| File | Subject |
|---|---|
references/20-rabbitmq.md |
Exchanges, queues, publisher confirms, DLQ, choreography |
references/34-messaging.md |
Outbox relay, inbox, ack and nack, ordering, Kafka, redrive |
references/14-circuit-breaker.md |
Timeouts, Resilience4j, fallback |
RabbitMQ and Kafka are not interchangeable. Use the broker already on the classpath.
| File | Subject |
|---|---|
references/18-security.md |
Gateway token, IDOR, secrets, log redaction |
references/35-identity.md |
OAuth2, OpenID Connect, JWT, Keycloak, injection |
references/32-logging.md |
No personal data in logs, trace id, AppConstants |
references/10-observability.md |
SLF4J, Micrometer, Prometheus, tracing |
references/12-otel.md |
OpenTelemetry compose stack |
references/09-performance.md |
N+1, cache, query shape |
references/11-docker.md |
Multi-stage image and Compose |
references/31-cicd.md |
GitHub Actions, secrets, Kubernetes, Trivy |
references/38-platform.md |
WebFlux, Batch, Integration, Helm, GitLab, Jenkins, Azure, pools, GC |
references/30-git.md |
Branches, Conventional Commits, pull requests |
references/29-docs.md |
What belongs in the README and what belongs in OpenAPI |
references/36-scenarios.md |
New service, upgrades, outages, duplicates, rollback, offline build |
references/08-testing.md |
Pyramid, JaCoCo floors, Testcontainers, PIT |
references/37-more-tests.md |
WireMock, REST Assured, Pact, ArchUnit, jqwik, load, resilience |
scripts/audit_java.py <project-dir> checks mechanical rules (field injection, wildcards, method length, missing JavaDoc, mixed YAML and properties, and others). It needs tree-sitter and tree-sitter-java. Exit code 0 is clean. It does not replace ./mvnw verify or ./gradlew check.
In scope: Java 17+, Spring Boot 3 and 4, Spring MVC, Spring Security, Spring Data, Spring Cloud as a BOM, validation, Actuator, AMQP, Kafka when the service uses it, Integration and Batch when the service uses them, Maven, Gradle, PostgreSQL, MySQL, MongoDB, Redis as a cache, RabbitMQ, Docker, Testcontainers, quality tools, and observability.
Out of scope: a second error body, an embedded database standing in for production, a frozen patch copied from an example, and a framework that is not Spring Boot.