AGENTS.md for Spring Boot

# AGENTS.md

Instructions for coding agents working in this Spring Boot repository. Cursor, Claude Code, Codex, Copilot, and other agents should follow this file before they guess.

## Stack

This repository is a Spring Boot service. Controllers stay thin, transactions sit on the service the project already uses, and configuration comes from the environment.

## Layout

- Controllers, services, and repositories follow the package split the project already has.
- DTOs are separate from JPA entities when the project already separates them.
- Configuration lives in application config and env vars. Do not hard-code a profile.

## Commands

- Test: `./mvnw test`
- Run: `./mvnw spring-boot:run`
- Package: `./mvnw package`

Use the script the repo already defines when it differs from the command above.

## Conventions

- Validate request bodies with Bean Validation. Do not parse maps by hand.
- Keep `@Transactional` on the service boundary the project uses, not on the controller.
- Use constructor injection. Do not add field injection.
- Return the response type the controller already declares. Do not leak lazy entities.
- Match MVC or WebFlux. Do not block inside a reactive chain.
- Use the existing test slice: `@WebMvcTest`, `@DataJpaTest`, or `@SpringBootTest` only when you need the whole context.

## Testing

Add or update tests when behavior changes.

Add a sliced test for the controller or service. Do not boot the entire context for a validation rule.

## Style

- Optimize for the next reader over the shortest diff.
- Comment only when the why is non-obvious.
- Name things the way neighboring files already do.
- Do not reformat code you did not change.

## Errors

- Fail at the boundary. Do not swallow errors.
- Use the project's exception handler for expected failures. A validation failure is 400, a missing row is 404.

## Scope

- Do the requested task. Do not refactor unrelated code.
- Match the rigor already in the repo. Fix what you touch.
- Ask one clarifying question only when the task cannot be finished without it. Otherwise state the assumption and continue.

## Avoid

- Do not catch Exception and return 200.
- Do not use the open-in-view pattern as an excuse to lazy-load in the controller.
- Do not commit `application-local` files that contain passwords.
- Do not add a new bean of a type that is already defined.

## Done when

- The requested behavior works.
- The module's tests pass. Use the Maven wrapper if it is present, otherwise the Gradle wrapper.
- The diff stays inside the task.
- You list anything you could not run.