lerchenflo/claudeskills

Atualiza ou migra um projeto Android para usar a versão 9 do Android Gradle Plugin (AGP). Não use esta skill para migrar projetos Kotlin Multiplatform (KMP).

O que é claudeskills?

Esta skill automatiza a migração de um projeto Android para o Android Gradle Plugin (AGP) versão 9. Ela é útil para desenvolvedores que precisam atualizar seu projeto para a versão mais recente do AGP, garantindo compatibilidade com ferramentas como Gradle, JDK e Kotlin. A skill é projetada para ser usada em projetos Android convencionais (não KMP) e orienta o usuário através de etapas como verificação de pré-requisitos, atualização de dependências (KSP, Hilt), migração para Kotlin embutido, adoção do novo DSL do AGP, substituição de kapt por KSP ou legacy-kapt, tratamento de campos BuildConfig e limpeza de flags obsoletas no gradle.properties. Ela inclui verificações de validação (sincronização do IDE, execução de tarefas do Gradle) e oferece suporte a solução de problemas conhecidos (como incompatibilidades com Paparazzi). A skill é compatível com ferramentas de linha de comando e ambientes de desenvolvimento Android e deve ser usada com cautela, especialmente em projetos KMP, que não são suportados.

Funciona com✓Claude Code~Codex CLI~Cursor

npx skills add https://github.com/lerchenflo/claudeskills/tree/HEAD/android/agp-9-upgrade

Documentação

Guia de migração

Consulte o guia de migração do AGP 9 para ver as principais mudanças, muitas delas quebrantes, no AGP 9 em comparação com o AGP 8.

Requisitos

Se o usuário solicitar atualização ou migração para o AGP 9, primeiro verifique a versão do AGP usada no projeto. Se for inferior a 9, pare e peça ao usuário para executar o Assistente de Atualização do AGP no Android Studio para atualizar para a versão estável mais recente do AGP e confirme quando terminar. O usuário também pode solicitar que este requisito seja ignorado; nesse caso, você deve atualizar a versão do AGP para a versão estável mais recente como parte da migração para o AGP 9. Consulte o guia de migração do AGP 9 para saber como fazer isso.

Cada versão do AGP tem seu próprio conjunto de compatibilidades com outras ferramentas, como Gradle, JDK e Kotlin. As notas de versão de cada uma dessas versões incluirão uma tabela de Compatibilidade indicando as versões mínimas para essas ferramentas.

Não use esta skill para projetos KMP, pois eles não são suportados.

Etapas

Se o AGP já estiver na versão 9 ou superior, siga os passos abaixo:

Etapa 1: Atualizar dependências

Se o KSP (com.google.devtools.ksp) for usado no projeto, certifique-se de que esteja na versão 2.3.6 ou superior.

Se o Hilt for usado no projeto, certifique-se de que esteja na versão 2.59.2 ou superior.

Etapa 2: Migrar para Kotlin embutido

Veja o guia para informações detalhadas.

Etapa 3: Migrar para o novo DSL do AGP

Veja o guia para informações detalhadas.

Consulte também gradle-recipes para exemplos de como migrar código antigo para código compatível com AGP 9 e o novo DSL.

Etapa 4: Migrar kapt para KSP ou legacy-kapt

Se o KSP (com.google.devtools.ksp) ou kapt (org.jetbrains.kotlin.kapt) forem usados no projeto, veja KSP, kapt e legacy-kapt para as etapas de migração detalhadas.

Etapa 5: BuildConfig

Se algum módulo Android contiver campos BuildConfig personalizados, veja BuildConfig para informações detalhadas.

Etapa 6: Atualizar gradle.properties

Após a migração, verifique o arquivo gradle.properties. Remova as seguintes flags:

android.builtInKotlin
android.newDsl
android.uniquePackageNames
android.enableAppCompileTimeRClass

Além disso, exclua todos os arquivos temporários criados.

Diretrizes

Nunca escreva ou execute scripts python.
Pesquise no cache de dependências do Gradle apenas ao inspecionar dependências externas, e apenas como último recurso.
Nunca adicione android.disallowKotlinSourceSets=false ao gradle.properties.
Ao verificar alterações, não execute a tarefa clean. Isto é perda de tempo.

Verificação

Após a migração, verifique o seguinte:

A sincronização do Gradle IDE é bem-sucedida.
./gradlew help é bem-sucedido.
./gradlew build --dry-run é bem-sucedido.

Solução de problemas

O Paparazzi v2.0.0-alpha04 e versões inferiores têm problemas com o AGP 9. Veja references/paparazzi-gradle-9.md para detalhes.