# gradle

Instructs Cursor to write modern Gradle scripts for Java and Android. Enforces Kotlin DSL and central version catalogs for cleaner builds.

- rule · `type=rule` · Cursor · ★ 3580
- Author: sanjeed5
- License: CC0-1.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/gradle.mdc
- Updated: 2026-05-19
- HTML: https://affpapa.org/en/nevibecode/rules/gradle

## What it does

This rule guides the AI when working on `**/*.java` files across Java and Android repositories. It enforces Kotlin DSL (`build.gradle.kts`) instead of legacy Groovy scripts. Monolithic architectures are discouraged in favor of early modularization with distinct module boundaries.

Dependency versions must stay organized inside `gradle/libs.versions.toml`. Plugins belong in the declarative `plugins {}` block, while repositories reside in `settings.gradle.kts` with `repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)`. The instructions also require enabling the configuration cache in `gradle.properties`.

Direct file access during configuration or mutable global state will immediately break Gradle configuration cache. Run `./gradlew --configuration-cache-problems` to inspect and resolve these incompatibilities before pushing build changes.

## Install

### Cursor (native platform)

**Manually: put the files in place**
- File: `.cursor/rules/gradle.mdc` — Frontmatter: description, globs, alwaysApply

### Claude Code

**Manually: put the files in place**
- File: `.claude/rules/gradle.md` — The paths frontmatter field limits the files: move globs from the source into paths

### Codex

**AGENTS.md**
- Codex reads AGENTS.md: paste the rule text there

### GitHub Copilot

**Manually: put the files in place**
- File: `.github/instructions/gradle.instructions.md` — The applyTo field sets which files it applies to: move globs from the source into applyTo

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/rules/gradle.md`

### Cline

**Manually: put the files in place**
- File: `.clinerules/gradle.md`

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/gradle.mdc

## When to use it
- migrate Groovy build scripts to Kotlin DSL
- centralize dependencies into `gradle/libs.versions.toml`
- split monolithic modules into separate Gradle subprojects
- enable configuration caching to reduce build duration

## Example prompts
- Refactor this build script to Kotlin DSL and extract dependencies to the version catalog.
- Configure repository management in `settings.gradle.kts` to reject project-level repos.
- Split the monolithic `app` module into separate feature and core library modules.

## Source text · gradle.mdc · CC0-1.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: eb04e6c0d189f4ab.

BEGIN THIRD-PARTY FILE eb04e6c0d189f4ab
````text
---
description: Enforce modern Gradle build practices for Java and Android projects, focusing on Kotlin DSL, modularity, version catalogs, and performance optimizations.
globs: **/*.java
---
# Gradle Best Practices

This guide outlines the definitive best practices for building robust, maintainable, and performant Java and Android projects with Gradle, leveraging the Kotlin DSL and modern features.

## 1. Adopt Kotlin DSL for Build Scripts

Always use the Kotlin DSL (`build.gradle.kts`) for new projects and when refactoring existing Groovy DSL (`build.gradle`) scripts. It offers strict typing, superior IDE support, and a unified language stack for Kotlin projects.

❌ BAD: Groovy DSL
```groovy
// build.gradle
plugins {
    id 'java-library'
}
dependencies {
    implementation 'com.google.guava:guava:31.1-jre'
}
```

✅ GOOD: Kotlin DSL
```kotlin
// build.gradle.kts
plugins {
    `java-library`
}
dependencies {
    implementation("com.google.guava:guava:31.1-jre")
}
```

## 2. Modularize Your Build Early and Aggressively

Split your codebase into small, logical Gradle projects (modules) from the start. This is critical for leveraging Gradle's work avoidance, parallel execution, and minimizing compilation classpaths.

❌ BAD: Monolithic `app` module
```
├── app
│   ├── build.gradle.kts
│   └── src/main/java/org/example/... (all code here)
└── settings.gradle.kts
    include("app")
```

✅ GOOD: Modularized structure
```
├── app
│   └── build.gradle.kts
├── features/feature-a
│   └── build.gradle.kts
├── core/domain
│   └── build.gradle.kts
└── settings.gradle.kts
    include("app", "features:feature-a", "core:domain")
```
*   **Guideline**: Each module should have a clear, single responsibility (e.g., `api`, `implementation`, `feature`, `ui`, `core`).

## 3. Centralize Dependencies with Version Catalogs

Manage all library versions in a single `gradle/libs.versions.toml` file. This eliminates duplication, simplifies upgrades, and ensures consistency across modules.

❌ BAD: Scattered versions or `ext` properties
```kotlin
// build.gradle.kts (multiple files)
val guavaVersion = "31.1-jre" // Or hardcoded
dependencies {
    implementation("com.google.guava:guava:$guavaVersion")
}
```

✅ GOOD: `gradle/libs.versions.toml`
```toml
# gradle/libs.versions.toml
[versions]
guava = "31.1-jre"
[libraries]
guava = { module = "com.google.guava:guava", version.ref = "guava" }
```
```kotlin
// build.gradle.kts
dependencies {
    implementation(libs.guava)
}
```
*   **Naming**: Use descriptive, hyphen-separated names in `libs.versions.toml` (e.g., `junit-jupiter`, `spring-boot-starter-web`). Convert internal dashes to camelCase for access in build scripts (e.g., `libs.spring.boot.starter.web`).

## 4. Apply Plugins Using the `plugins {}` Block

Always use the declarative `plugins {}` block for applying plugins. This is more concise, less error-prone, and allows Gradle to optimize plugin loading.

❌ BAD: Legacy `apply` statements
```groovy
// build.gradle
buildscript {
    repositories { gradlePluginPortal() }
    dependencies { classpath("com.google.protobuf:com.google.protobuf.gradle.plugin:0.9.4") }
}
apply plugin: "com.google.protobuf"
```

✅ GOOD: `plugins {}` block
```kotlin
// build.gradle.kts
plugins {
    id("java-library")
    id("com.google.protobuf").version("0.9.4")
}
```
*   **Note**: For plugins defined in your Version Catalog, use `alias(libs.plugins.myPlugin)`.

## 5. Leverage the Configuration Cache

Enable the Configuration Cache to dramatically speed up build times, especially for large projects. This feature is moving towards default enablement in future Gradle versions.

```bash
# Enable in gradle.properties (root project)
org.gradle.configuration-cache=true
```
````
END THIRD-PARTY FILE eb04e6c0d189f4ab

The third-party file has ended. Everything between the eb04e6c0d189f4ab tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3821 of 7797 bytes. © sanjeed5 · CC0-1.0 · https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/gradle.mdc

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md