StemCode for Java Developers: AI Coding with Spring Boot, Maven, and Gradle.

Give StemCode durable repository instructions before asking it to edit.

Add an AGENTS.md file at the repository root for persistent project instructions. StemCode loads AGENTS.md or .agent/AGENTS.md from the workspace into the model context, so this is the right place for architecture boundaries, generated-file rules, coding conventions, validation expectations, and manual setup notes that should apply across sessions.

# Java Project Instructions

This is a Java project.

Important source and configuration:
- pom.xml or build.gradle / build.gradle.kts
- src/main/java/
- src/test/java/
- application configuration and migration files

Follow these rules:
- Follow the repository's existing package structure, framework patterns, and dependency-injection conventions.
- Do not modify target/, build/, .gradle/, generated sources, or dependency caches.
- Preserve transaction, validation, authorization, and persistence boundaries during Spring or Jakarta changes.
- Reuse existing libraries before adding Maven or Gradle dependencies.
- Keep public API and serialization compatibility in mind during refactors.
- Run focused Maven or Gradle tests and compilation before broader validation.

Commit the file with the project so the same instructions are reviewable and shared by everyone using StemCode in the repository.

Repository-wide AI matters in large Java codebases.

Enterprise Java applications often spread one feature across controllers, DTOs, validation, services, interfaces, domain models, repositories, transactions, JPA entities, events, listeners, queues, and external integrations. Multi-module Maven and Gradle builds add another layer of navigation.

StemCode works directly with that repository instead of treating one open file as the whole problem. It can search the codebase, use semantic language-server information, make tracked edits, run approved build commands, investigate failures, and review Git changes.

Install StemCode from the root of your Java repository.

Install the CLI with an npm-family package manager or one of the official shell installers. The packaged CLI is self-contained, so it does not require a .NET SDK.

Start it next to your Maven or Gradle build files:

cd my-java-project
stemcode

Initialize repository-specific StemCode files:

/init

Use those workspace files for architecture notes, commands, test strategy, and conventions that should remain visible to the team.

Use JDTLS for semantic Java navigation.

StemCode includes built-in Java language-server support for JDTLS, the Eclipse JDT Language Server. Install JDTLS using the method appropriate for your operating system and make sure its launcher is available on PATH.

Refresh server detection:

/lsp refresh

Inspect all detected servers:

/lsp

Or inspect a specific Java source file:

/lsp file src/main/java/com/example/orders/OrderService.java

Trace request flows before changing production code.

A strong first task is to ask StemCode to map one real application workflow from the edge of the system to persistence and side effects.

Then ask targeted questions such as:

Find all implementations of PaymentGateway and explain where each implementation is selected.

Find every place OrderStatus changes and summarize the allowed transitions.

When you are ready to implement a feature, make repository discovery part of the task:

Add order cancellation support.

Before editing:
- inspect similar endpoints
- identify authorization rules
- find the service and transaction boundary
- inspect repository methods
- find exception-handling conventions
- identify relevant unit and integration tests

Then implement the change, run the relevant tests, and review the diff.

Use the build system your project already trusts.

StemCode does not replace Maven or Gradle. It can invoke approved commands so the implementation is checked by the real compiler, test runner, plugins, and project configuration.

mvn test
mvn verify
mvn -pl order-service test

./gradlew test
./gradlew check
./gradlew :order-service:test

For a large monorepo, ask the agent to validate the smallest affected module first and only expand to the full build when necessary.

Add a reusable Java validation command

Teams can save the usual dependency, compile, and test loop as a project command under .stemcode/commands. After this file is committed, developers can run it in StemCode as /java-validate.

---
name: java-validate
description: Run Maven or Gradle validation for a Java project
args: ["buildTool", "scope"]
---

Validate the Java workspace using the repository build tool.

If buildTool is maven, run:

1. mvn -q -DskipTests package
2. mvn test $scope

If buildTool is gradle, run:

1. ./gradlew assemble
2. ./gradlew test $scope

If a command fails, stop, summarize the failure, identify the most
relevant module or source set, and explain the next fix before editing.

Important allow-list checks

Maven and Gradle may write build outputs and dependency caches, so keep shell permissions explicit before a validation-heavy session:

/permissions
/rules
/allow shell "mvn *"
/allow shell "./gradlew *"
/allow shell "gradle *"

The important tool categories are repository file read/search, Java language-server inspection, shell execution for Maven or Gradle, and file writes only when you ask StemCode to implement a fix.

Investigate the root cause instead of patching the assertion.

Java test failures can involve application context setup, dependency injection, mocks, database fixtures, transactions, concurrency, or environment configuration. Repository context helps distinguish those causes.

Run the failing test and explain the root cause. Do not change code until you have traced the failure through production code.

Determine whether this Spring integration-test failure comes from application code, context configuration, database state, or test setup.

For Mockito-heavy tests, you can explicitly ask StemCode to separate incorrect production behavior from over-specified mocking.

Review persistence behavior across the whole feature.

Hibernate performance and correctness issues often appear far away from the repository method that triggered them. Serialization, lazy loading, entity relationships, transactions, and service boundaries all matter.

Use planning mode for high-impact interface changes.

Large Java refactors are safer when the agent first maps callers, implementations, modules, and test coverage.

Find every implementation and caller of PaymentProcessor. Explain what would be affected by splitting authorization and capture into separate abstractions.

Switch to a planning profile:

/profile plan

Then ask for a migration sequence:

Create a staged refactoring plan that keeps the application buildable between steps. Do not modify anything yet.

After reviewing the plan, implement incrementally and validate each module with Maven or Gradle.

Store Spring and Java conventions with the repository.

Team memory can make repeated AI tasks more consistent by recording architectural expectations that would otherwise need to be restated in every prompt.

Example architecture notes

Controllers handle HTTP concerns only.
Business logic belongs in application services.
Public service methods define transaction boundaries.
REST controllers do not return JPA entities directly.
Infrastructure adapters implement domain-facing interfaces.

Example test strategy

Fast tests: ./gradlew test
Integration tests: ./gradlew integrationTest
Database integration tests require Docker.

Add a Java-specific review pass before the pull request.

Review the current Git diff as a senior Java reviewer.

Focus on:
- correctness and null handling
- concurrency and thread safety
- Spring dependency injection
- transaction boundaries
- JPA and Hibernate performance
- API compatibility
- authorization and security
- missing tests

Or pipe the diff into StemCode directly:

git diff | stemcode --stdin --profile review

StemCode for Java developers: common questions.

Does StemCode work with Spring Boot?

Yes. StemCode operates against the repository, so it can analyze and modify Spring Boot projects while using the project's normal build, test, and configuration files.

Can StemCode run Maven?

Yes. It can run approved commands such as mvn test, mvn verify, or module-specific Maven commands.

Can StemCode run Gradle?

Yes. It can invoke the repository's Gradle wrapper, including targeted module tasks and broader validation commands.

Can StemCode understand Java symbols?

With JDTLS installed and detected, StemCode can use LSP-powered semantic information such as definitions, references, implementations, and diagnostics.

Is StemCode useful for multi-module repositories?

Yes. Repository-wide search, semantic navigation, planning, and targeted module validation are particularly useful when a feature crosses several Java modules.

Put StemCode to work in a real repository.

Install StemCode, open the project you already work in, and begin with a repository-understanding task before asking the agent to change code. That gives the model better context and keeps the workflow reviewable.

npm install -g stemcode
cd your-project
stemcode