ai-instructions: Instructions file for GitHub Copilot

Java Style Contract

Formatting

• Use exactly two spaces per indentation level in every Java file. Never use tabs, and never use non-two-space indentation, regardless of what an IDE or generator produced by default.

Imports

• Order imports in four groups, separated by exactly one blank line between groups, omitting any group that has no members:
  1. Static imports.
  2. java.* / jakarta.* standard/platform imports.
  3. Third-party imports (Spring, other framework, and library packages).
  4. Project-local imports.
• Import each type explicitly; wildcard imports are forbidden.
• Remove unused imports before finishing a file.

Visibility and dependency injection

• Declare every field and helper method with the most restrictive visibility that satisfies its usage scope; default to private, expanding only when external access is required.
• Use constructor injection for every dependency; never use field injection or setter injection.
• Do not add Objects.requireNonNull(...) guards in constructors of classes that are instantiated exclusively by the framework's dependency injection container (services, repositories, controllers) - the container guarantees a non-null dependency graph and the check only adds boilerplate.
• Use Objects.requireNonNull(...) in constructors of classes that can be instantiated directly by arbitrary calling code outside of the DI container (for example configuration/properties holders built from parsed values, or public utility classes), where a null argument would otherwise fail confusingly downstream.
• Do not expose implementation details through public fields or helper methods unless they are part of a real API contract (e.g., a documented constant shared across classes).

Annotation order

• Order class-level annotations as:
  1. Logging annotation (e.g., @Slf4j).
  2. Framework stereotype annotation (e.g., @Service, @Repository, @Controller, @RestController, @Component, @ConfigurationProperties).
  3. Lombok generation annotations other than the logging annotation (e.g., @RequiredArgsConstructor).
  4. Behavioral/validation annotations (e.g., @Validated).
• Annotate every method that implements or overrides an interface/superclass method with @Override.
• Keep annotations directly attached to the declaration they annotate; never separate an annotation from its target with a blank line or comment.
• Do not use @Data, @Builder, @AllArgsConstructor, or @NoArgsConstructor on business classes (services, repositories, controllers). Lombok ownership of allowed annotations and record preference is in the Lombok contract.