Práticas recomendadas

O agente no Android Studio atua como seu colaborador de programação, acelerando seu fluxo de trabalho de desenvolvimento ao gerar código, resumir tópicos complexos, encontrar recursos específicos e muito mais. A comunicação eficaz é a chave para liberar todo o potencial do agente.

Este guia descreve estratégias para configurar seu ambiente de desenvolvimento e escrever comandos que geram respostas úteis e confiáveis. Para várias estratégias, fornecemos exemplos de comandos para diferentes casos de uso. Para mais exemplos de comandos, consulte a galeria de comandos.

Escreva de forma específica

O agente funciona melhor com instruções claras e específicas. Se houver determinadas bibliotecas, APIs ou abordagens que você queira usar, inclua-as na pergunta ou no arquivo AGENTS.md raiz do projeto para que elas sejam mantidas nas interações. Pense nisso como o envio de um relatório de bug: quanto mais informações você fornecer, mais rápido e eficaz será o processo de solução do problema.

Implementação de novas funcionalidades:

O que fazer

Como faço para adicionar suporte à câmera ao meu app usando a CameraX? Inclua todas as dependências e permissões necessárias para usar a biblioteca.

O que não fazer

Como faço para adicionar suporte à câmera no meu app?

Gerar código:

O que fazer

Escrever uma função de suspensão do Kotlin que usa a biblioteca Coil para fazer o download de uma imagem de uma determinada string de URL.

A função precisa ser chamada de fetchImageAsBitmap. Ele precisa usar um Context e um URL String como argumentos e retornar um Bitmap anulável. Se houver algum erro de rede ou decodificação, ela vai capturar a exceção, registrá-la e retornar null.

O que não fazer

Escreva uma função para fazer o download de uma imagem.

Explicar um conceito:

O que fazer

Estou criando um app de reprodução de música e preciso continuar a reprodução quando o app estiver em segundo plano.

Quais são minhas opções para manter o app em execução enquanto o usuário faz outras coisas no dispositivo? Quais são os requisitos de nível da API e as implicações na duração da bateria para cada abordagem?

O que não fazer

Explicar os serviços do Android.

Descreva a estrutura da resposta

Por padrão, o agente fornece respostas em um formato de conversa baseado em parágrafos. Embora isso seja útil para explicações, você pode conseguir resultados mais eficazes e imediatamente utilizáveis ao dizer como estruturar a resposta. Especificar o formato de saída orienta o modelo a organizar as informações de maneira clara e previsível, poupando o tempo de reformatar manualmente.

Se você quiser inserir o código gerado pelo agente no seu app e precisar dele em um determinado formato para usá-lo instantaneamente, dê ao agente instruções claras sobre como gerar e formatar o código.

Estruturar a resposta:

O que fazer

Criar uma entidade do Room para um perfil de usuário. Ele precisa conter os campos id, userName, email e memberSince. O campo id precisa ser gerado automaticamente. O campo memberSince precisa representar um carimbo de data/hora.

O que não fazer

Criar uma entidade do Room para um perfil de usuário.

Se você estiver fazendo uma pergunta mais aberta, peça um número x de opções.

Limitar a resposta:

O que fazer

Quais ferramentas estão disponíveis para otimizar o desempenho do app? Mostre uma lista com os três primeiros.

O que não fazer

Quais ferramentas estão disponíveis para otimizar o desempenho do app?

Divida pedidos complexos em tarefas menores

Se a abordagem do agente não for o que você espera, pode ser útil orientá-lo com uma série de comandos menores e sequenciais, em vez de pedir tudo de uma vez. Essa abordagem oferece mais controle e permite verificar cada etapa antes de prosseguir para a próxima.

Como aplicar comandos sequenciais:

O que fazer

Comando 1: o modelo de dados
Primeiro, crie uma classe de dados do Kotlin chamada User. Ela precisa ter três propriedades: id (um Int), name (uma String) e email (uma String).

Comando 2: a camada de rede
Agora, crie uma interface da API Retrofit chamada ApiService. Ele precisa de um único suspend fun chamado getUsers() que retorna um List<User>.

Comando 3: o gerenciamento de estado
Em seguida, escreva um UsersViewModel que receba o ApiService como uma dependência. O UsersViewModel precisa expor um StateFlow de uma classe UiState selada que pode representar os estados Loading, Success(users: List) e Error(message: String). Crie uma função no ViewModel para buscar os usuários e atualizar o estado. Escreva testes de unidade para a nova funcionalidade.

Comando 4: a camada de IU
Por fim, escreva uma função do Jetpack Compose chamada UserListScreen que aceite o UiState como um parâmetro. Use uma instrução when para mostrar um CircularProgressIndicator para o estado de carregamento, uma LazyColumn de nomes de usuário para o estado de sucesso e um elemento Text com a mensagem de erro para o estado de erro. Adicione testes que verifiquem a nova funcionalidade.

O que não fazer

Crie uma tela do Jetpack Compose que busque uma lista de usuários de uma API JSON e os mostre em uma lista. Ele precisa ter um ViewModel que use o Retrofit e corrotinas, um repositório para processar a lógica de dados, uma classe de dados User e precisa mostrar estados de carregamento e de erro.

Gerenciar contexto

Uma parte importante do trabalho com o agente é fornecer o contexto correto. Forneça snippets de código, conteúdo de arquivos e informações sobre a estrutura do projeto relevantes para receber as respostas mais úteis. Talvez seja necessário iterar para encontrar o equilíbrio certo: muitas informações podem confundir o agente, enquanto poucas não fornecem contexto suficiente para que ele ajude. Use os recursos disponíveis para dar ao agente acesso ao contexto necessário:

  • Anexe imagens para fornecer uma visualização da interface que você está imaginando ou da arquitetura do app que está tentando entender.
  • Anexe arquivos para destacar partes relevantes da base de código.
  • Use arquivos .aiexclude para que o agente ignore determinadas partes da base de código.
  • Use arquivos AGENTS.md para dar instruções específicas do projeto e compartilhá-las com sua equipe. Ao usar arquivos AGENTS.md, use cabeçalhos e formatação Markdown para deixar as instruções claras.
  • Ao usar o Modo Agente, configure servidores MCP para ampliar o conhecimento e as habilidades do agente com o ambiente externo.

Pedir explicações

Se você não entender a resposta do agente, peça uma explicação. Essa é uma ótima maneira de aprender e verificar se a solução proposta é adequada para seu caso de uso. Se a resposta não for o que você esperava, pode ser que o agente esteja incorreto, e pedir uma explicação dará a ele a oportunidade de se corrigir.

Iterar as instruções

Assim como quando você trabalha com um colega, trabalhar com o agente às vezes exige uma comunicação de ida e volta para esclarecer a tarefa e o resultado esperado. Se a resposta inicial do agente for insuficiente, responda com feedback e sugestões de melhoria. Se a resposta melhorar com base nas suas sugestões, incorpore essa sugestão ao comando original atualizando a entrada na Biblioteca de comandos ou atualizando os arquivos AGENTS.md.