Intellij-Java-Kotlin

# IntelliJ IDEA Java and Kotlin Development

Use these instructions for Java and Kotlin projects developed in IntelliJ IDEA. Follow repository-specific conventions first and apply language- or framework-specific guidance only when relevant. IDE actions are optional developer workflows: do not assume Copilot can operate the IDE or claim to have performed actions without tool evidence. Do not require paid IntelliJ features or additional IDE plugins.

Project Model and Build Configuration

- Treat Gradle or Maven configuration, repository documentation, and CI workflows as the source of truth. Inspect the build files and existing module layout before changing code.

- Import or reload the project from its Gradle settings or Maven root POM. Define dependencies, repositories, source sets, compiler options, and test tasks in the build files rather than only in IntelliJ Project Structure.

- Use the repository's Gradle or Maven wrapper when present. Preserve wrapper versions, dependency catalogs, lockfiles, parent POMs, and dependency-management conventions; do not upgrade tooling as a side effect of an unrelated change.

- Align the IntelliJ project SDK, module SDKs, language level, Gradle JVM, and Maven runner/importer JDK with the build configuration. Distinguish the JDK running the build tool from compilation toolchains and target bytecode; they may intentionally differ. Do not select the newest installed JDK or enable preview features unless the repository requires them.

- After build changes, reload the Gradle or Maven project and resolve synchronization errors before interpreting IDE diagnostics. Fix missing dependencies and source roots in the build model rather than manually adding local JARs or machine-specific paths.

Editing, Navigation, and Refactoring

- Follow the repository's `.editorconfig`, formatter, import order, and inspection settings. Use configured checks such as Spotless, Checkstyle, ktlint, or detekt only when already present; avoid unrelated whole-file reformatting or new formatter dependencies.

- Use Go to Declaration, Find Usages, and type or call hierarchies to understand a change. Also search configuration, reflection-based lookups, serialization names, and framework conventions that static IDE navigation may miss.

- Prefer semantic Rename, Move, Change Signature, Extract Method, and Safe Delete refactorings over textual replacement when available. Preview the affected usages and review the diff, including Java/Kotlin interop, public APIs, resources, and tests.

- Treat inspections and quick fixes as suggestions, not authority. Check them against the configured language level and project behavior; do not blanket-suppress warnings, weaken inspections, or change compiler settings merely to remove highlighting.

- If IDE actions are unavailable, make equivalent source/build edits with available tools and validate them from the command line. Do not add IDE automation or plugins just to complete a code change.

Running, Debugging, and Testing

- Match run/debug configurations to the intended module classpath, JDK, working directory, JVM options, application arguments, environment, and active profiles. Keep secrets in the existing environment or secret-management mechanism, not in shared run configurations.

- Use Gradle/Maven tool windows or delegated build/test execution when the project relies on build-tool tasks, generated sources, or custom test setup. An IntelliJ-only compilation or green gutter test is not a substitute for the CI command.

- Use breakpoints, conditional breakpoints, watches, and exception breakpoints to investigate failures. Evaluate expressions cautiously because method calls can mutate state; do not introduce production behavior changes just to simplify debugging.

- Add or update focused tests in the repository's existing framework, source set, naming style, and assertion conventions. Preserve the distinction between unit and integration tests, including required services, profiles