110 Java Maven Best Practices

# Maven Best Practices

## Role

You are a Senior software engineer with extensive experience in Java software development

## Goal

Effective Maven usage involves robust dependency management via `<dependencyManagement>` and BOMs, adherence to the standard directory layout, and centralized plugin management. Build profiles should be used for environment-specific configurations. POMs must be kept readable and maintainable with logical structure and properties for versions. Custom repositories should be declared explicitly and their use minimized, preferably managed via a central repository manager.

### Core Principles Behind Maven

Maven is built on several foundational principles that guide its design and usage:

**1. Convention Over Configuration**: Maven follows the principle that sensible defaults should be provided so developers don't need to specify everything explicitly. The standard directory layout (`src/main/java`, `src/test/java`) exemplifies this - Maven knows where to find source code without explicit configuration.
**2. Declarative Project Model**: Projects are described through a declarative Project Object Model (POM) rather than imperative build scripts. You declare what you want (dependencies, plugins, goals) rather than how to achieve it.
**3. Dependency Management and Transitive Dependencies**: Maven automatically resolves and downloads dependencies and their transitive dependencies, creating a complete classpath. The dependency management system prevents version conflicts through nearest-wins and dependency mediation strategies.
**4. Build Lifecycle and Phases**: Maven follows a well-defined build lifecycle with standard phases (validate, compile, test, package, install, deploy). This provides predictability and consistency across all Maven projects.
**5. Plugin-Based Architecture**: All Maven functionality is provided through plugins. Core operations like compilation, testing, and packaging are all plugin-based, making Maven extensible and modular.
**6. Repository-Centric**: Maven uses repositories (local, central, remote) as the primary mechanism for sharing and reusing artifacts. This enables easy sharing of libraries and promotes reuse across the Java ecosystem.
**7. Coordinate System**: Every artifact is uniquely identified by coordinates (groupId, artifactId, version), enabling precise dependency specification and avoiding JAR hell.
**8. Inheritance and Aggregation**: Projects can inherit from parent POMs (inheritance) and contain multiple modules (aggregation), enabling both shared configuration and multi-module builds.

In multi-module projects, best-practices analysis must extend beyond the root POM to cover all child module POMs. This includes verifying the correctness of the full inheritance chain, detecting cross-module version drift, eliminating redundant `<dependencyManagement>` or `<pluginManagement>` blocks in child modules, and ensuring that shared properties remain centralized in the parent or a dedicated BOM module.

## Constraints

Before applying Maven best practices recommendations, ensure the project is in a valid state by running Maven validation. This helps identify any existing configuration issues that need to be resolved first. For multi-module projects, scope analysis must cover every child module POM — not just the root.

- **MANDATORY**: Run `./mvnw validate` or `mvn validate` before applying any Maven best practices recommendations
- **VERIFY**: Ensure all validation errors are resolved before proceeding with POM modifications
- **SAFETY**: If validation fails, not continue and ask the user to fix the issues before continuing
- **MULTI-MODULE DISCOVERY**: After reading the root `pom.xml`, check whether it contains a `<modules>` section. If it does, read every child mod