Guia de Desenvolvimento com Gemini Code Assist e CLI

Gemini CLI

📦 Repositório Oficial: google-gemini/gemini-cli

Índice

Visão Geral

Este guia cobre duas ferramentas de IA do Google para desenvolvimento:

  • Gemini CLI: Interface de linha de comando flexível e extensível
  • Gemini Code Assist: Solução empresarial integrada ao Google Cloud Platform

Características Comuns

Ambas as ferramentas compartilham:

  • Modelo Recomendado: Gemini Pro 2.5 para melhor qualidade de resposta
  • Janela de Contexto: 1 milhão de tokens - permite análise de projetos inteiros, múltiplos arquivos e contexto extenso em uma única conversa
  • Integração VS Code: Nativa com diff visual para aceitar/rejeitar mudanças
  • Contexto Automático: Detecta e inclui arquivos abertos na IDE automaticamente

⚠️ Importante sobre Modelos: Recomendamos sempre usar Gemini Pro 2.5 para melhor qualidade de resposta. O modelo Flash, embora tenha limite diário maior (~1.000 req/dia), pode produzir resultados inferiores e não é recomendado para desenvolvimento profissional.

Comparação: Gemini CLI vs Code Assist

Característica Gemini CLI Gemini Code Assist
Web Search ✅ Nativo ❌ Não disponível
MCP Servers ✅ Suporte completo ❌ Limitado
Limite Diário (Free) ~100 req/dia (Pro 2.5) N/A
Quotas Empresariais ⚠️ Limitado ao tier gratuito ✅ Configuráveis via GCP
Flexibilidade ✅ Terminal + IDE + Scripts ⚠️ Limitado ao IDE
Automação ✅ Fácil de integrar ⚠️ Mais complexo
Atualizações ✅ Frequentes ⚠️ Mais lentas

Quando usar cada ferramenta

Gemini CLI: - ✅ Desenvolvimento ágil individual - ✅ Scripts e automação - ✅ Busca na web em tempo real - ✅ Exploração rápida e prototipagem - ✅ Máxima flexibilidade (terminal + IDE) - ⚠️ Limite de ~100 requisições/dia (tier gratuito)

Gemini Code Assist: - ✅ Ambientes corporativos - ✅ Alta demanda de uso - ✅ Quotas empresariais personalizadas via GCP - ✅ Integração com Google Cloud - ✅ Suporte empresarial - ⚠️ Limitado ao IDE (sem terminal standalone)

Gemini CLI

Instalação

Pré-requisitos

  • Node.js (versão 18 ou superior)
  • npm
  • Conta Google

Instalando o Gemini CLI

npm install -g @google/gemini-cli

Autenticação

Opção 1: Free tier (conta Google)

gemini
# Após abrir, digite:
/auth

Opção 2: API Key

Configure sua chave de API do Gemini como variável de ambiente:

export GEMINI_API_KEY="sua-chave-api-aqui"

Para tornar permanente, adicione ao seu arquivo ~/.zshrc:

echo 'export GEMINI_API_KEY="sua-chave-api-aqui"' >> ~/.zshrc
source ~/.zshrc

Integração com VS Code

O Gemini CLI se integra nativamente ao VS Code oferecendo:

✅ Diff Visual Integrado

  • Exibe mudanças de código diretamente no editor
  • Interface visual para aceitar/rejeitar alterações
  • Preview lado a lado das modificações

✅ Contexto Automático de Arquivos

  • Detecta automaticamente arquivos abertos no editor
  • Inclui o conteúdo no contexto da conversa
  • Não precisa referenciar manualmente com @arquivo.js

✅ Terminal Integrado

  • Execute gemini no terminal integrado do VS Code
  • Aceite/rejeite mudanças visualmente no editor
  • Workflow fluido sem sair do ambiente

Exemplo de Uso com Diff Visual

  1. Abra um arquivo no VS Code
  2. Abra o terminal integrado (Cmd+`)
  3. Execute gemini
  4. Faça sua pergunta referenciando o arquivo:
gemini
# No input:
@src/utils/validation.js Melhore esta validação de email com regex adequado

O Gemini mostra o diff visual:

- function validateEmail(email) {
-   return email.includes('@');
- }
+ function validateEmail(email) {
+   const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+   return regex.test(email);
+ }

✅ Você aceita ou rejeita a mudança diretamente no editor!

Configuração

Configuração Global vs Projeto

O Gemini CLI suporta dois níveis de configuração:

Configuração Global (~/.gemini/)

Configurações aplicadas a todos os projetos:

mkdir -p ~/.gemini

Arquivo ~/.gemini/settings.json:

{
  "context": {
    "fileName": "AGENTS.md"
  },
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": [
        "-y",
        "@upstash/context7-mcp"
      ]
    },
    "youtube-transcript-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "--package=github:lucasliet/youtube-transcript-mcp#main",
        "youtube-transcript-mcp"
      ]
    },
    "tavily-web-search": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>"
      ]
    }
  }
}

Arquivo ~/.gemini/commands/: Comandos customizados disponíveis globalmente

Configuração de Projeto (.gemini/ no projeto)

Configurações aplicadas apenas ao projeto específico:

# Na raiz do seu projeto
mkdir -p .gemini

Arquivo AGENTS.md: Contexto específico do projeto

Pasta .gemini/commands/: Comandos customizados exclusivos do projeto

💡 Prioridade: Configurações do projeto sobrescrevem configurações globais quando há conflito.

📚 Referência: Para criar um AGENTS.md eficaz, consulte agents.md - guia oficial sobre agentes de IA e boas práticas de contexto.

MCP Servers (Model Context Protocol)

MCP Servers estendem as capacidades do Gemini CLI, permitindo integração com serviços externos.

Context7 MCP

Função: Documentação atualizada de bibliotecas e frameworks populares

Documentação: github.com/upstash/context7-mcp

Exemplo:

gemini
# No input:
Como usar hooks no React?

YouTube Transcript MCP

Função: Extrai e processa transcrições de vídeos do YouTube

Documentação: github.com/lucasliet/youtube-transcript-mcp

Exemplo:

gemini
# No input:
Resuma o vídeo https://youtube.com/watch?v=...

Tavily Web Search MCP (Opcional)

Função: Busca web em tempo real com IA otimizada - útil para adicionar capacidade de web search ao Gemini Code Assist via extensões MCP

Documentação: tavily.com

Configuração: Obtenha sua API key em app.tavily.com

💡 Nota: O Gemini CLI possui web search nativo e não requer Tavily. Este MCP é útil principalmente para usuários do Gemini Code Assist que desejam adicionar funcionalidade de busca web.

Comandos do Gemini CLI

💡 Dica: Digite / no modo interativo para ver todos os comandos disponíveis

Modo Interativo (Recomendado)

gemini

Inicia uma sessão interativa. Digite suas perguntas diretamente no input.

Listar Comandos

gemini
# No input, digite:
/

Exibe todos os comandos disponíveis com descrições.

Analisar Arquivo

gemini
# No input:
@arquivo.js Explique este código

Múltiplos Arquivos

gemini
# No input:
@src/models/User.js @src/services/auth.js Como integrar estes módulos?

Salvar Conversa

gemini
# No input:
/chat save nome-da-conversa

Retomar Conversa

gemini
# No input:
/chat resume nome-da-conversa

Modo Sandbox

gemini
# No input:
/sandbox
Teste este código com diferentes inputs

Permite executar código de forma segura e isolada.

Dicas de Uso

1. Seja Específico nas Perguntas

❌ Ruim: "Como fazer autenticação?" ✅ Bom: "Como implementar autenticação JWT com refresh tokens em Node.js usando Express?"

2. Use Contexto de Arquivos

gemini
# No input:
@src/models/User.js @src/services/auth.js Como integrar estes módulos?

3. Aproveite o AGENTS.md

Configure corretamente o arquivo AGENTS.md para que o Gemini entenda o contexto do seu projeto automaticamente.

4. Use MCP Servers Estrategicamente

  • Context7: Documentação oficial de frameworks
  • YouTube Transcript: Aprender com vídeos técnicos
  • Tavily: Soluções recentes e artigos atualizados

5. Combine Ferramentas

gemini
# No input:
Busque informações sobre Clean Architecture e sugira como aplicar em @src/services

6. Use GitHub Spec Kit para Desenvolvimento Estruturado

Para projetos novos ou refatorações grandes, combine o Gemini CLI com o GitHub Spec Kit para desenvolvimento orientado por especificações:

gemini
# No input:
Ajude-me a criar a constituição e especificação usando GitHub Spec Kit para este projeto

💡 Recomendação: O GitHub Spec Kit é ideal para estruturar projetos complexos antes da implementação. Consulte o Guia de Uso do GitHub Spec Kit para fluxo de trabalho detalhado.

7. Diff Visual no VS Code

Use o terminal integrado do VS Code para aproveitar o diff visual:

  1. Abra o arquivo que deseja modificar
  2. Abra o terminal integrado (Cmd+`)
  3. Execute gemini
  4. Faça suas perguntas referenciando arquivos
  5. Aceite/rejeite mudanças visualmente

8. Gere Testes Automaticamente

gemini
# No input:
@src/utils/validator.js Gere testes unitários completos para este módulo

9. Documente Código

gemini
# No input:
@src/services/payment.js Adicione JSDoc completo para todas as funções

10. Peça Explicações Passo a Passo

gemini
# No input:
Explique passo a passo como @arquivo.js funciona

Prompts Reutilizáveis

Você pode criar prompts customizados em arquivos .toml para automatizar tarefas repetitivas.

Localização dos Comandos

  • Global (~/.gemini/commands/): Comandos disponíveis em todos os projetos
  • Projeto (.gemini/commands/ na raiz do projeto): Comandos específicos do projeto, compartilháveis com a equipe via Git

Organização e Boas Práticas

  • Documente queries úteis: Salve prompts frequentes como comandos reutilizáveis
  • Comandos globais: Use ~/.gemini/commands/ para comandos genéricos (ex: refatoração, documentação)
  • Comandos de projeto: Use .gemini/commands/ para comandos específicos da arquitetura/stack do projeto
  • Compartilhe com a equipe: Comandos de projeto podem ser versionados no Git
  • Nomeie descritivamente: Use nomes claros que indiquem a função do comando

Exemplo: ~/.gemini/commands/load-folder.toml

description = "Carrega todos os arquivos de um diretório e seus subdiretórios no contexto"

prompt = """
Você deve carregar TODOS os arquivos do diretório {{args}} e de TODAS as suas subpastas recursivamente.

Instruções:
1. Liste a estrutura completa de diretórios e arquivos dentro de {{args}} recursivamente
2. Identifique todos os caminhos de arquivos (não diretórios) encontrados
3. Use a ferramenta ReadManyFiles passando TODOS os caminhos de arquivos de uma vez
4. Não filtre arquivos por tipo ou extensão - carregue todos
5. Confirme quantos arquivos foram carregados ao final

Importante:
- {{args}} é o caminho relativo à pasta atual
- Explore recursivamente todas as subpastas
- Use ReadManyFiles com a lista completa de arquivos encontrados
- Não pule nenhum arquivo
"""

Nota: ReadManyFiles é uma ferramenta interna do Gemini CLI usada para carregar múltiplos arquivos de uma vez no contexto.

Melhores Práticas

Segurança

  • Nunca exponha sua chave de API em repositórios públicos
  • Use variáveis de ambiente para credenciais
  • Configuração global (~/.gemini/): Mantenha API keys e credenciais aqui, nunca versione no Git
  • Configuração de projeto (.gemini/): Pode ser versionada, mas adicione ao .gitignore se contiver dados sensíveis do projeto

Performance

  • Mantenha o AGENTS.md conciso e relevante
  • Use arquivos de contexto específicos quando possível
  • Limite o número de arquivos referenciados em uma única query
  • Aproveite a janela de contexto de 1M tokens, mas evite sobrecarga desnecessária

Troubleshooting

Erro: "Quota exceeded"

Problema: Limite diário atingido

Soluções: 1. Aguardar: O limite reseta a cada 24 horas 2. Trocar conta: Use /auth para logar com outra conta Google 3. Upgrade: Considere tier pago via Google AI Studio 4. Empresarial: Migre para Gemini Code Assist com quotas GCP

⚠️ Evite Gemini Flash: Embora tenha limite maior (~1.000 req/dia), a qualidade é inferior. Use apenas em situações onde a qualidade da resposta não é crítica.

MCP Server não responde

Verifique se o Node.js está atualizado:

node --version  # Deve ser >= 18
npx -y @upstash/context7-mcp --version

Contexto não está sendo aplicado

Verifique se o AGENTS.md existe e está configurado no projeto:

ls -la AGENTS.md
cat .gemini/settings.json

Ou verifique a configuração global:

cat ~/.gemini/settings.json

Gemini Code Assist

Visão Geral

O Gemini Code Assist é uma solução empresarial integrada ao Google Cloud Platform, projetada para ambientes corporativos que necessitam de alta demanda e quotas personalizadas.

Instalação

VS Code

  1. Acesse o VS Code Marketplace
  2. Instale a extensão "Gemini Code Assist"
  3. Configure suas credenciais do Google Cloud

JetBrains IDEs

  1. Acesse o JetBrains Marketplace
  2. Instale o plugin "Gemini Code Assist"
  3. Configure suas credenciais do Google Cloud

Configuração

Pré-requisitos

  • Conta Google Cloud Platform
  • Projeto GCP com Gemini API habilitada
  • Credenciais configuradas

Autenticação

  1. Abra o VS Code
  2. Cmd+Shift+P → "Gemini Code Assist: Sign In"
  3. Faça login com sua conta GCP
  4. Selecione o projeto

Funcionalidades

✅ Sugestões de Código em Tempo Real

O Code Assist oferece sugestões contextuais enquanto você digita, similar ao GitHub Copilot.

✅ Geração de Código

Selecione código e peça modificações via: - Clique direito → "Gemini Code Assist: Generate" - Cmd+Shift+P → "Gemini Code Assist: Generate"

✅ Explicação de Código

Selecione código e peça explicações: - Clique direito → "Gemini Code Assist: Explain" - Painel lateral com explicação detalhada

✅ Geração de Testes

Selecione uma função e gere testes automaticamente: - Clique direito → "Gemini Code Assist: Generate Tests"

✅ Diff Visual Integrado

Todas as modificações são exibidas com diff visual para aceitar/rejeitar.

Quotas e Limites

O Gemini Code Assist utiliza quotas do Google Cloud Platform:

  • Quotas Configuráveis: Defina limites personalizados no GCP
  • Sem Limite Fixo Diário: Baseado em uso e configuração GCP
  • Faturamento: Integrado à sua conta GCP
  • Escalabilidade: Ajuste conforme necessidade da equipe

Para configurar quotas, acesse Google Cloud Console.

Comparação com Gemini CLI

Use Gemini Code Assist quando: - Trabalha em ambiente corporativo - Precisa de alta demanda de requisições - Necessita de quotas personalizadas e escaláveis - Quer integração total com GCP - Prefere suporte empresarial

Use Gemini CLI quando: - Trabalha individualmente ou em equipe pequena - Precisa de flexibilidade (terminal + IDE + scripts) - Quer recursos extras (MCP Servers, web search nativo) - Limite de ~100 req/dia é suficiente - Prefere ferramenta mais atualizada e com mais features

Recursos Adicionais

Gemini CLI

Gemini Code Assist

Gemini API e Recursos

Metodologias e Frameworks

  • GitHub Spec Kit - Desenvolvimento orientado por especificações com IA
  • agents.md - Guia oficial sobre agentes de IA e criação de arquivos AGENTS.md

Conclusão

Gemini CLI

✅ Integração nativa com VS Code - Diff visual e contexto automático ✅ Web Search nativo em tempo real - sem necessidade de MCP adicional ✅ Documentação atualizada via Context7 MCP ✅ Aprendizado de vídeos via YouTube Transcript MCP ✅ Flexibilidade total - Terminal + VS Code + Scripts ✅ Atualizações frequentes com novos recursos ✅ Automação fácil para CI/CD e workflows ⚠️ Limite de ~100 req/dia (tier gratuito com Pro 2.5)

Gemini Code Assist

✅ Quotas empresariais configuráveis via GCP ✅ Sem limite fixo diário ✅ Integração GCP nativa ✅ Suporte empresarial ✅ Escalabilidade conforme demanda ⚠️ Limitado ao IDE (sem terminal standalone) ⚠️ Menos features que o CLI (sem MCP, sem web search)

Próximos Passos

Para Gemini CLI:

  1. Configure ~/.gemini/settings.json com os MCP Servers (global)
  2. Crie um arquivo AGENTS.md na raiz do seu projeto com contexto específico
  3. Configure .gemini/settings.json no projeto apontando para o AGENTS.md
  4. Crie comandos customizados em ~/.gemini/commands/ (globais) ou .gemini/commands/ (projeto)
  5. Teste diferentes comandos digitando / no modo interativo
  6. Monitore seu uso de quota e ajuste conforme necessário

Para Gemini Code Assist:

  1. Instale a extensão no VS Code ou plugin no JetBrains
  2. Configure suas credenciais GCP
  3. Defina quotas adequadas no Google Cloud Console
  4. Integre com outros serviços GCP se necessário
  5. Monitore custos e uso regularmente

Lembre-se: Ambas as ferramentas são poderosas e complementares. Escolha de acordo com suas necessidades de uso, quota e flexibilidade.