Skip to content

project rulesBackend and APIsjava

Java Maven Library Rules

Project rules for Java libraries built with Maven: a small public API, semantic versions, null contracts, Javadoc and a repeatable release.

npx workspacetemplates add java-maven-library-rules --tool claude-code

Writes 1 file to your project root

CLAUDE.mdadd to your file21 lines · 1.5 KBFile
# Project rules: Java Maven library

## API surface
- Keep implementation in a `internal` package that is not exported. Default to package-private, then public only what users need. Prefer interfaces, final classes and static factories or builders.
- If you use JPMS, export only the API packages in `module-info.java`.
- Never change or remove a public signature in a minor release. Deprecate with `@Deprecated(since=..., forRemoval=...)` and a Javadoc `@deprecated` pointing to the replacement.

## Contracts
- Parameters and returns are non-null unless documented. Use `Objects.requireNonNull` with a message at entry points, `Optional` for absent return values and never for fields or parameters.
- Throw unchecked exceptions for programming errors. Use a small checked or custom hierarchy for expected failures, with the cause attached.
- Make types immutable where possible and document thread safety.

## Documentation
- Every public type and method has Javadoc with the behavior, parameters, exceptions and an example. Build with `-Xdoclint` and fail on warnings.

## Build and versions
- Follow semantic versioning. Pin plugin versions, declare dependencies with the narrowest scope and keep them few. Never leak third-party types in the API.
- Run a binary compatibility check, such as japicmp, against the last release.

## Done checks
- Run `mvn -B verify` with tests, Javadoc and the compatibility check. Releases go through `mvn release:prepare` or the CI workflow, with a changelog entry and a signed tag.

What it does

A library is judged by what it exposes, not by how it works inside. These rules make an agent treat every public type as a promise to users and keep the surface as small as it can be.

They also set up versioning, documentation and a release routine, so a change never breaks a downstream build by accident.

Example

you › Add a retry option to our HttpClient wrapper

agent › The agent adds a RetryPolicy interface and a builder method in the API package, keeps the implementation in internal, documents it with Javadoc and an example, and confirms japicmp reports no breaking change.

Questions

Is this meant for applications too?
No. Applications can expose more freely; these rules assume other people compile against your jar.
Do I need JPMS?
Not required. The internal package rule works with or without module descriptors.
  • ASP.NET Core Web API Rules

    Project rulesdotnet

    Free
  • Django Rules

    Project rulespython

    Free
  • Flask Rules

    Project rulespython

    Free
  • Go Service Rules

    Project rulesgo

    Free