◆ Sparround

Diagnosing Gradle and build problems

Build errors suit an agent well, because the feedback loop is closed: run the command, read the error, fix, run again. The cycle a human finds tedious is natural for an agent.

But Android builds have a few characteristics:

  • Error messages are long and layered. The real cause can sit in the middle of a 200-line stack trace.
  • The cause is somewhere else. A "duplicate class" error is caused by a transitive dependency; the message doesn't say so directly.
  • Some errors appear only in certain configurations — release builds, R8, a particular API level.
  • Caching misleads. Sometimes the problem isn't the code but a stale build cache.
Problem typeAgent suitabilityWhat to supply
Compilation errorHighThe narrow compile command so the loop is fast
Dependency conflictHighLet it inspect `./gradlew :app:dependencies`
R8 / ProGuard problemMediumThe release build command plus the mapping file; have a human approve the fix
Gradle configuration errorMedium`--stacktrace` output; the version catalog
Slow build (performance)MediumA build scan or a `--profile` report
A problem that happens on one machine onlyLowIt is an environment difference — outside the agent's context

The most common trap: the agent tries to fix a build error by changing a version. That often works — and is often wrong, because a version change affects the whole project and creates problems elsewhere. State it explicitly in CLAUDE.md: "don't change libs.versions.toml without asking".

bash
# Diagnostic commands worth giving the agent

# The dependency tree — to find the source of a conflict
./gradlew :app:dependencies --configuration debugRuntimeClasspath

# Where a specific library is pulled in from
./gradlew :app:dependencyInsight \
  --configuration debugRuntimeClasspath \
  --dependency okhttp

# List the modules
./gradlew projects

# Full stack trace for a configuration error
./gradlew :app:assembleDebug --stacktrace

# When you suspect a stale cache (slow — last resort)
./gradlew clean

Putting these in the `allow` list lets the agent run the diagnosis itself — without a prompt for each command.

What to give the agent when working on a build problem:

1. The full error output, not a truncated fragment. The real cause is often in the part that got cut.

2. What you changed — in a "it worked yesterday" situation the last change is the strongest clue.

3. The verification command to confirm the fix.

4. Constraints — "don't change versions", "don't add dependencies".

Without the fourth, the agent picks the easiest "fix": downgrade a version or add an exclude. That hides the problem rather than solving it.

📚 Sources and documentation