Planejar e criar apps com o Conductor da CLI do Gemini

1. Introdução

Neste codelab, você vai aprender a planejar e criar aplicativos de software com a extensão Conductor da CLI do Gemini. Você vai começar criando um aplicativo "greenfield" do zero. Em seguida, vai tratá-lo como um projeto "brownfield", iterando nele para adicionar autenticação e armazenamento.

Atividades deste laboratório

• Instalar a CLI do Gemini e a extensão Conductor
• Criar um app da Web "Picker Wheel" do zero usando os recursos de planejamento e implementação do Conductor
• Adicionar personalização ao aplicativo, incluindo autenticação e armazenamento usando o Firebase

O que você vai aprender

• Como usar a extensão Conductor para planejar, implementar e revisar um aplicativo "greenfield"
• Como usar a extensão Conductor para adicionar recursos a um aplicativo "brownfield"

O que é necessário

• Um navegador da Web, como o Chrome
• Tenha um projeto na nuvem do Google Cloud com o faturamento ativado.
• Node.js instalado (versão 18 ou mais recente recomendada)
• Um editor de código local, como o Visual Studio Code

2. Antes de começar

Criar um projeto do Google Cloud

1. No console do Google Cloud, na página de seletor de projetos, selecione ou crie um projeto do Google Cloud.
2. Verifique se o faturamento está ativado para seu projeto na nuvem. Saiba como verificar se o faturamento está ativado em um projeto.

Iniciar o Cloud Shell

O uso do Cloud Shell permite concluir esta seção sem precisar instalar as ferramentas de CLI gcloud e firebase localmente.

O Cloud Shell é um ambiente de linha de comando em execução no Google Cloud que vem pré-carregado com as ferramentas necessárias.

1. Clique em Ativar o Cloud Shell na parte de cima do console do Google Cloud.
2. Depois de se conectar ao Cloud Shell, verifique sua autenticação:

   gcloud auth list
   

3. Confirme se o projeto está configurado:

   gcloud config get project
   

4. Se o projeto não estiver definido como esperado, defina-o:

   export PROJECT_ID=<YOUR_PROJECT_ID>
   gcloud config set project $PROJECT_ID
   

Ativar APIs

Ative a API Firebase Management no seu projeto na nuvem do Google Cloud.

gcloud services enable firebase.googleapis.com

Adicione o Firebase ao seu projeto

A CLI do Firebase vem pré-instalada no Cloud Shell. No Cloud Shell, faça login com a mesma Conta do Google que dá acesso ao projeto na nuvem do Google Cloud. Se você estiver trabalhando localmente, instale a CLI do Firebase seguindo as instruções.

firebase login

Execute o seguinte comando para adicionar o Firebase ao seu projeto do Google Cloud:

firebase projects:addfirebase

Se esta for a primeira vez que você executa a CLI firebase, responda às perguntas que forem feitas.

Sair do Cloud Shell

Você pode fechar a janela do Cloud Shell. Na seção a seguir, vamos configurar seu ambiente local.

3. Instalar a CLI do Gemini e o Conductor localmente

Nesta etapa, você vai preparar seu ambiente de desenvolvimento local instalando a CLI do Gemini e a extensão Conductor usando o editor de código e o terminal locais.

Instalar a CLI do Gemini

1. Instale a versão mais recente da CLI do Gemini globalmente usando o npm:

   npm install -g @google/gemini-cli
   

   Se você receber erros de permissão, talvez seja necessário usar um gerenciador de versões como nvm ou executar esse comando como raiz usando sudo.

2. Reinicie o terminal para que gemini seja adicionado ao seu PATH.
3. Verifique se a instalação instalou a versão mais recente:

   gemini --version
   

4. Crie e mude para um novo diretório de projeto: em uma seção posterior, vamos criar um projeto em um diretório picker-wheel. Crie esse diretório agora e mude para ele:

   mkdir picker-wheel
   cd picker-wheel
   

5. Autenticar:
   • Inicie a CLI do Gemini.

     gemini
     

   • Quando perguntado "Você confia nos arquivos desta pasta?", selecione Confiar na pasta (picker-wheel).
   • Quando perguntado "Como você quer se autenticar para este projeto?", selecione Vertex AI. Siga o guia de autenticação para receber uma chave de API do Google Cloud e definir a variável de ambiente GOOGLE_API_KEY. Reserve um momento para conhecer os diferentes níveis de uso e os limites de taxa de API correspondentes.
6. Sair da CLI do Gemini: digite /quit no terminal da CLI para encerrar a sessão da CLI do Gemini antes de continuar.

Instalar a extensão Conductor

O Conductor é uma extensão de código aberto da CLI do Gemini criada pelo Google que permite recursos de desenvolvimento orientados por contexto, como planejamento e acompanhamento da implementação.

1. Instalar a extensão:

   gemini extensions install https://github.com/gemini-cli-extensions/conductor
   

2. Verifique a instalação:
   • Inicie a CLI do Gemini.

     gemini
     

   • Digite /conductor e você verá uma lista de comandos como setup, newTrack, implement etc.
3. Sair da CLI do Gemini: digite /quit no terminal da CLI para encerrar a sessão da CLI do Gemini antes de continuar.

4. Desenvolvimento greenfield: a roda de seleção

Agora que seu ambiente está configurado, você vai criar um novo aplicativo do zero. Você vai criar uma "roda de seleção", um app da Web leve que gira para selecionar uma opção aleatória.

Configurar o contexto do produto

1. Confirme se você está no picker-wheel diretório criado na seção anterior:

   pwd
   

2. Iniciar a CLI do Gemini: inicie uma nova sessão da CLI do Gemini no diretório do projeto.

   gemini
   

3. Inicializar o Conductor: execute o comando de configuração para criar a estrutura do projeto e configurar o ambiente do Conductor.

   /conductor:setup
   

4. Siga as instruções interativas: as instruções interativas que você vê não correspondem exatamente a estes exemplos. Concentre-se em um design mais simples para se familiarizar com o fluxo de trabalho do Conductor.
   • Objetivo do produto: um aplicativo da Web que mostra uma roda giratória configurável para selecionar um item aleatório de uma lista.
     • Público-alvo → público em geral
     • Interação → toque/clique para girar
     • Personalização → básica
     • Plataforma → prioridade para computadores
   • Diretrizes de produtos: geradas automaticamente.
   • Stack de tecnologia:
     • Linguagens → TypeScript/JavaScript: ideal para Web full-stack
     • Front-end → Vue.js: interfaces da Web intuitivas
     • Back-end → Express.js: back-end rápido do Node
     • Banco de dados → nenhum: não é necessário
   • Fluxo de trabalho: padrão.
   • Requisitos do produto:
     • Histórias de usuários → opções personalizáveis, exibição clara do vencedor
     • Principais recursos → lista de opções editável, cores aleatórias
     • Restrições → somente do lado do cliente, alto desempenho
     • Não funcional → alta cobertura de testes, TypeScript e Vue.js, design responsivo
   O Conductor vai gerar arquivos de contexto em um diretório conductor/.

Criar uma nova faixa

Uma "faixa" no Conductor representa um recurso ou uma unidade de trabalho.

1. Inicie uma nova faixa usando /conductor:newTrack. O Conductor pode propor uma faixa inicial com base no contexto do produto. Como alternativa, você pode propor sua própria faixa ou pedir que o Conductor sugira uma.
2. Revise o plano gerado: o Conductor vai gerar um index.md, um spec.md e um plan.md dentro de conductor/tracks/{track-id}/. Reserve um momento para lê-los. Se tudo estiver certo, o Conductor vai pedir que você salve e confirme os arquivos de configuração inicial.

Implementar a faixa

1. Iniciar a implementação:

   /conductor:implement
   

   O Conductor vai trabalhar no plano, escrevendo o código do projeto.

   Dica:para evitar ficar preso em shells interativos ou processos de longa duração (como servidores de desenvolvimento ou observadores de teste), precisamos garantir que o Conductor saiba exatamente como lidar com esses comandos específicos. Ferramentas como Vite (npm run dev) e Vitest (npm run test) geralmente são executadas no "modo de observação" por padrão, o que mantém o processo aberto indefinidamente. Você pode instruir o Conductor a desativar o modo de observação ou usar is_background: true ao executar comandos atualizando workflow.md.

2. Verificar o aplicativo: durante a fase de implementação, o Conductor vai pedir que você teste o aplicativo manualmente. Por exemplo, ele vai pedir que você abra o servidor da Web local, visualize o aplicativo no navegador e verifique as mudanças. Quando a implementação estiver concluída, você verá uma roda de seleção funcional.

   Solução de problemas:se o código gerado se comportar de maneira inesperada, verifique o conductor/tracks/.../plan.md para conferir se há etapas ou erros ignorados.

3. Revisar a implementação: como última etapa, você pode pedir que o Conductor revise a implementação. Ele precisa revisar o código-fonte, sincronizar a documentação do projeto e arquivar a faixa.

   /conductor:review
   

5. Iteração brownfield: adicionar personalização

Agora você vai mudar para o desenvolvimento "brownfield". Você vai melhorar o aplicativo da Web da roda de seleção da seção anterior para que os usuários conectados possam salvar e restaurar as configurações da roda de seleção.

Se você quiser acessar diretamente um aplicativo brownfield, faça o download do código dourado da última seção para uma implementação de referência e continue criando nele.

Criar uma faixa de personalização

1. No exemplo "brownfield" a seguir, vamos usar o Firebase para autenticação e armazenamento. Instale a extensão do Firebase da CLI do Gemini para que o Conductor possa usá-la.

   gemini extensions install https://github.com/gemini-cli-extensions/firebase
   

2. Iniciar a CLI do Gemini: inicie uma nova sessão da CLI do Gemini no diretório do projeto.

   gemini
   

3. Iniciar uma nova faixa: inicie uma nova faixa.

   /conductor:newTrack "I want users to be able to log in to their accounts and
   save their picker wheel configurations."
   

4. Siga as instruções interativas: as instruções interativas que você vê não correspondem exatamente a estes exemplos. Concentre-se em um design mais simples para se familiarizar com o fluxo de trabalho do Conductor.
   • Meta do objetivo:
     • Provedor de autenticação → Firebase Auth
     • Configurações salvas → opções de roda
     • Armazenamento de dados → Firestore
     • Interface de login do Firestore → sobreposição modal
   O Conductor vai gerar arquivos de contexto para uma nova faixa dentro de conductor/tracks/{track-id}.
5. Revise o plano gerado: reserve um momento para ler um index.md, um spec.md e um plan.md dentro de conductor/tracks/{track-id}/.

   Dica:recomendamos que você converse com o Gemini para entender e discutir o plano o máximo possível antes de passar para a implementação.

6. Implementar: se tudo estiver certo, você poderá iniciar a implementação.

   /conductor:implement
   

7. Verificar: recarregue o aplicativo. Você verá um aplicativo atualizado.

   Caso a IA fique presa ao testar a implementação da autenticação, lembre-se de ativar o login do Google no console do Firebase em Autenticação > Método de login.

   

Confira o código dourado para uma implementação de referência. Você precisa fornecer seu projeto do Firebase em .firebaserc e suas configurações do Firebase em firebase.ts para iniciar o aplicativo corretamente.

6. Limpar

Para evitar cobranças contínuas na sua conta do Google Cloud, exclua os recursos criados durante este codelab.

Excluir o projeto do Firebase (e o projeto do Google Cloud)

A maneira mais fácil de limpar é excluir o projeto inteiro.

1. No console do Google Cloud, selecione o projeto criado.
2. Clique em EXCLUIR.

Como alternativa, se você quiser manter o projeto, mas excluir recursos:

1. Excluir o banco de dados do Firestore: acesse o console do Firebase > Firestore e exclua o banco de dados.
2. Excluir a autenticação: acesse o console do Firebase > AutenticaçãoMétodo de login e desative o Google.

7. Parabéns

Parabéns! Você usou a extensão Conductor da CLI do Gemini para criar um aplicativo da Web do zero e, em seguida, iterar nele com recursos complexos, como autenticação e integração de banco de dados.

Próximas etapas

• Conhecer o modo de plano da CLI do Gemini para planejamento leve
• Descoberta avançada extensões da CLI do Gemini