Using Claude for a Java Project

Claude works well on Java projects once it has the build commands, the project conventions, and the limits on what it may change. Without that setup, it will guess at the build tool, apply generic Java style, and run commands that may not match your environment. Tools like fenbs retain the implementation decisions and lessons that would otherwise disappear when a session ends.

This article focuses on Claude Code, Anthropic's coding assistant. The same principles apply when using Claude in other environments—you are giving it the context it needs to act correctly on your specific project, not just on generic Java.

Start with the build tool and commands

The single most useful thing you can put in your CLAUDE.md is the correct build and test commands. A Java project built with Maven uses different commands from one built with Gradle, and both differ from a multi-module build that passes flags to a wrapper script.

Write out the exact commands, including any flags that matter. If your project uses a wrapper (./mvnw or ./gradlew), say so—Claude will not assume the wrapper exists unless you tell it. If tests require a specific profile or environment variable, include that too.

## Build and test
- Build: `./mvnw clean package -DskipTests`
- Run all tests: `./mvnw test`
- Run a single test: `./mvnw test -Dtest=ClassName`
- Check style: `./mvnw checkstyle:check`
- Do not run `mvn` directly; always use `./mvnw`.

Share conventions in CLAUDE.md

Java projects accumulate conventions that are not obvious from reading the code. Name them explicitly. Common examples: which Java version the project targets, the package naming scheme, where to place new classes, how exceptions are handled, and which logging library and level conventions apply.

If your project uses a specific pattern—say, the service layer never calls the repository directly, or all database queries go through a named interface—state that as a rule. Claude will follow it if you tell it. It will invent its own approach if you do not.

Keep CLAUDE.md focused on what Claude needs to act. Architecture background and historical context belong in a separate notes file. See how to organize Claude projects for guidance on splitting these.

Set clear test boundaries

Tell Claude which tests it may run automatically and which require your approval. Some Java projects have integration tests that need a running database or external service—running those by default wastes time or produces confusing errors. A unit test suite with an in-memory database is usually safe to run freely.

• Unit tests: safe to run after any change.
• Integration tests: run only when asked, or only on named test classes.
• Performance tests or load tests: require explicit approval.
• Tests that modify shared data or send external requests: list them and mark them off-limits without approval.

If a test fails, ask Claude to show the failure output before it tries to fix the code. Automated fixes without reading the failure often produce code that passes the test by changing the assertion rather than fixing the bug.

Record implementation decisions

Java projects involve many choices that are correct for reasons that are not in the code: why a particular library was chosen over another, why an interface was split into two, why a test class uses a specific fixture strategy. Those reasons disappear from context at the end of a session.

When you and Claude settle on an approach, record the decision: what was chosen, what was considered and rejected, and why. "Chose Caffeine over Guava Cache because the project already uses it and the API is simpler" is a useful decision. It stops the next session from reopening the question or choosing the other option for no reason.

Claude project memory covers where these notes can live within a Claude Project. For team work, fenbs lets multiple sessions and multiple teammates read the same record.

Capture lessons to avoid repeating mistakes

When something goes wrong—a build breaks in an unexpected way, a refactor produces a subtle bug, a Claude change fails a test for the wrong reason—record the lesson before the session ends. A lesson has three parts: what happened, what it reveals about the codebase or the workflow, and what to do differently next time.

Say a Gradle project has a custom task that must run before compilation, and Claude skips it because nothing in the instructions mentioned it. The lesson is: "Custom task generateSources must run before compilation; always include it in the build command." Add that to CLAUDE.md and the decision record so it does not happen again.

How to do this with fenbs

Connect Claude Code to fenbs and create a project for your Java codebase. Add the build commands and conventions as context notes, and create tasks for the work in progress.

1. Create a free account and add a project for the Java codebase. Write a short description of what it does and what technology it uses.
2. Connect Claude Code from Integrations. Sign in in the browser, approve the access, and follow the MCP guide for Claude Code.
3. Add the build commands, test boundaries, and conventions as context notes. Mark them verified after you confirm each one.
4. When you and Claude settle on an implementation approach, ask Claude to record it as a decision in fenbs: what was chosen and why. Record rejected options too.
5. After any session where something went wrong or was learned, ask Claude to add a lesson in fenbs. Before starting similar work next time, ask Claude to list relevant lessons first.

fenbs does not read your Java source files or import your build output. You or Claude add notes by hand during a session, based on what you discover. That manual step keeps the record accurate—Claude cannot verify a note it generated without you confirming it.