# CLAUDE.md - this project

Project instructions for Claude Code.

## Project

A Java + Spring Boot + Docker project.

Stack: Java + Spring Boot, Docker.

## Commands

- Run: `./mvnw spring-boot:run`
- Tests: `./mvnw test`
- Local services: `docker compose up -d`

## Project structure

- Package by feature (`user/`, `order/`), each with controller, service, repository and DTOs.

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

## Java + Spring Boot

- Use constructor injection (final fields). No field `@Autowired`.
- Use Java records for DTOs; never expose JPA entities directly from controllers.
- Validate request bodies with Jakarta Bean Validation (`@Valid`, `@NotBlank`, ...).
- Put `@Transactional` on service methods, not controllers.
- Handle errors in one `@RestControllerAdvice` returning `ProblemDetail`.
- Configuration via `application.yml` plus env vars; no secrets in the repo.
- Use the build tool wrapper in the repo (`./mvnw` or `./gradlew`), whichever exists.

## Docker

- Use multi-stage builds and slim, pinned base images.
- Run the app as a non-root user in the final image.
- Keep a `.dockerignore` that excludes `.git`, `node_modules`, `.env` and build output.
- Never bake secrets into images; pass them at runtime.

## Reference docs

- [Spring Boot docs](https://docs.spring.io/spring-boot/)
- [Dockerfile best practices](https://docs.docker.com/build/building/best-practices/)