ai-instructions: Instructions file for GitHub Copilot

Spring Boot Logging Contract

Logger acquisition

• Obtain a logger via Lombok's @Slf4j on the class (Lombok contract). Do not call LoggerFactory.getLogger(...) when Lombok is available.

Log message content

• Externalize log message text through a dedicated logging message helper component backed by MessageSource, separate from any user-facing/API message resolution path.
• The logging message helper exposes:
  • get(String key, Object... args) - resolves the message in the configured default locale (English by default) for events without a request locale.
  • get(Locale locale, String key, Object... args) - resolves the message in the caller-supplied locale; use the request locale for request-scoped log events.
• Prefix every logging-helper key with log.. Include each logging key in every locale bundle and translate its value for that locale, preserving placeholder arity.
• Never hardcode log message text directly in a log call; always resolve it through the logging message helper and an externalized message key.
• Use the request locale explicitly for request-scoped log events and the configured default locale for startup, background, or other events without a request locale. Do not rely on the JVM default locale or implicit locale state.

Structured log fields

• When more than one log statement records outcomes of the same logical event (for example, a success audit line and a rejection audit line for the same operation), give every one of them the same field schema, in the same order. Do not include a field (such as an error code) in one code path and drop it in another for the same conceptual event.
• Leave a field present but empty when it does not apply to a given outcome, instead of omitting the placeholder; this keeps field position and count stable for grep/awk-based log analysis.
• When adding, removing, or renaming a field on a shared structured log message key, update every call site that uses that key, not only the one being changed.