android-gradle-build-performance

Android Gradle Build Performance

When To Use

• Use this skill when the request is about: android gradle build performance, configuration cache android build, ksp vs kapt android.
• Primary outcome: Diagnose and improve Android and Gradle build performance with scans, cache checks, and bottleneck audits.
• Use this skill when the problem is build speed, task churn, cache misses, or CI wall time rather than build-logic structure.
• Read references/patterns.md when you need the measurement ladder or the most common Gradle performance smells.
• Read references/scenarios.md for audit-first entry points on the example projects.
• Handoff skills when the scope expands:
• android-gradle-build-logic
• android-ci-cd-release-playstore

Workflow

1. Identify whether the problem is local developer feedback time, CI build duration, or both.
2. Measure one build path at a time with --profile, --scan, configuration-cache diagnostics, or the bundled audit script before proposing a fix.
3. Check gradle.properties, plugin wiring, dependency declarations, task registration style, and module conventions for common performance smells.
4. Apply one high-confidence optimization at a time, then compare before and after behavior instead of stacking changes.
5. Hand off structural Gradle refactors or release-pipeline changes once the performance bottleneck is isolated.

Guardrails

• Do not recommend broad rewrites when a single cache, plugin, or dependency pattern is the real bottleneck.
• Separate measurement from speculation; call out what was observed vs inferred.
• Prefer KSP, configuration cache, and lazy task configuration when the toolchain supports them.
• Treat dynamic dependency versions, changing modules, and eager task creation as performance regressions unless there is a deliberate reason.
• Keep CI guidance reproducible on the example projects before suggesting org-wide rollout.

Anti-Patterns

• Turning on every Gradle flag without checking compatibility or failures.
• Blaming AGP upgrades for slow builds without measuring task hot spots.
• Mixing build-logic architecture advice with build-time diagnosis in one pass.
• Using dynamic dependency versions that force repeated resolution work.

Review Focus

• Configuration time vs execution time vs dependency resolution vs test wall time.
• Configuration cache compatibility and lazy task registration.
• KSP vs kapt and annotation-processor hotspots.
• Remote/local cache value, dynamic dependencies, and CI-specific bottlenecks.

Examples

Happy path

• Scenario: Audit the Compose fixture for build cache, configuration cache, KSP, and eager task creation smells.
• Command: python3 skills/android-gradle-build-performance/scripts/audit_build_performance.py examples/orbittasks-compose --json

Edge case

• Scenario: Compare XML and Compose fixture build settings before choosing a CI build optimization.
• Command: bash skills/android-gradle-build-performance/scripts/run_examples.sh

Failure recovery

• Scenario: Re-check a project after enabling performance flags so regressions are caught before rollout.
• Command: python3 skills/android-gradle-build-performance/scripts/audit_build_performance.py examples/orbittasks-xml

Done Checklist

• The bottleneck is tied to a specific phase, flag, plugin, or dependency pattern.
• Proposed optimizations are measurable and reversible.
• The recommended fix is compatible with the current Android and Gradle toolchain.
• Structural Gradle work is handed off separately from performance tuning.

Official References

• https://docs.gradle.org/current/userguide/performance.html
• https://docs.gradle.org/current/userguide/configuration_cache.html
• https://docs.gradle.org/current/userguide/task_configuration_avoidance.html
• https://developer.android.com/build/optimize-your-build
• https://developer.android.com/build/ksp