Guia de Habilidades Gemini

Quando Usar Gemini

• QUANDO SOLICITADO A SER ATIVADO
• Revisão de Código: Revisões de código abrangentes em múltiplos arquivos
• Revisão de Plano: Análise de planos arquiteturais, especificações técnicas ou roadmaps de projeto
• Processamento de Contexto Amplo: Tarefas exigindo >200k tokens de contexto (bases de código completas, conjuntos de documentação)
• Análise Multi-Arquivo: Compreensão de relações e padrões entre muitos arquivos

⚠️ Crítico: Aviso de Modo Background/Não-Interativo

NUNCA use --approval-mode default em shells background ou não-interativos (como chamadas de ferramentas Claude Code). Ficará pendurado indefinidamente aguardando prompts de aprovação que não podem ser fornecidos.

Para revisões automatizadas/background:

• ✅ Use --approval-mode yolo para execução totalmente automatizada
• ✅ OU encapsule com timeout: timeout 300 gemini ...
• ❌ NUNCA use --approval-mode default sem terminal interativo

Sintomas de Gemini pendurado:

• Processo em execução 20+ minutos com 0% de uso de CPU
• Sem atividade de rede
• Estado do processo mostra 'S' (dormindo)

Corrigir processo pendurado:

# Verificar se está pendurado
ps aux | grep gemini | grep -v grep

# Matar se necessário
pkill -9 -f "gemini.*gemini-3-pro-preview"

Executando uma Tarefa

1. Pergunte ao usuário (via AskUserQuestion) qual modelo usar em um único prompt. Modelos disponíveis:

   • gemini-3-pro-preview ⭐ (modelo principal, melhor para codificação e raciocínio complexo, 35% melhor em engenharia de software que 2.5 Pro)
   • gemini-3-flash (latência sub-segundo, destilado de 3 Pro, melhor para tarefas sensíveis à velocidade)
   • gemini-2.5-pro (opção legada, desempenho sólido em geral)
   • gemini-2.5-flash (opção legada, com capacidades de thinking)
   • gemini-2.5-flash-lite (opção legada, processamento mais rápido)

2. Selecione o modo de aprovação baseado na tarefa:

   • default: Solicitar aprovação (⚠️ APENAS para sessões de terminal interativo)
   • auto_edit: Auto-aprovar apenas ferramentas de edição (para revisões de código com sugestões)
   • yolo: Auto-aprovar todas as ferramentas (✅ OBRIGATÓRIO para tarefas automatizadas/background)

3. Monte o comando com opções apropriadas:

   • -m, --model <MODEL> - Seleção de modelo
   • --approval-mode <default|auto_edit|yolo> - Controlar aprovação de ferramentas
   • -y, --yolo - Alternativa a --approval-mode yolo
   • -i, --prompt-interactive "prompt" - Executar prompt e continuar interativamente
   • --include-directories <DIR> - Diretórios adicionais para incluir no workspace
   • -s, --sandbox - Executar em modo sandbox para isolamento

4. Para tarefas automatizadas/background, SEMPRE use --approval-mode yolo ou adicione wrapper de timeout. NUNCA use default em shells não-interativos.

5. Execute o comando e capture a saída. Para modo automatizado/background:

   # Recomendado: Use yolo para tarefas background
   gemini -m gemini-3-pro-preview --approval-mode yolo "Revisar esta base de código para problemas de segurança"
   
   # Ou com timeout (limite de 5 min)
   timeout 300 gemini -m gemini-3-pro-preview --approval-mode yolo "Revisar esta base de código"
   

6. Para sessões interativas com prompt inicial:

   gemini -m gemini-3-pro-preview -i "Revisar o sistema de autenticação" --approval-mode auto_edit
   

7. Após Gemini completar, informe o usuário: "A análise Gemini está completa. Você pode iniciar uma nova sessão Gemini para análise de acompanhamento ou continuar explorando os resultados."

Referência Rápida

Caso de uso	Modo de aprovação	Flags principais
Revisão de código background	yolo ✅	-m gemini-3-pro-preview --approval-mode yolo
Análise background	yolo ✅	-m gemini-3-pro-preview --approval-mode yolo
Background com timeout	yolo ✅	timeout 300 gemini -m gemini-3-pro-preview --approval-mode yolo
Revisão de código interativa	default	-m gemini-3-pro-preview --approval-mode default (apenas terminal interativo)
Revisão de código com auto-edições	auto_edit	-m gemini-3-pro-preview --approval-mode auto_edit
Refatoração automatizada	yolo	-m gemini-3-pro-preview --approval-mode yolo
Background crítico em velocidade	yolo ✅	-m gemini-3-flash --approval-mode yolo
Background otimizado por custo	yolo ✅	-m gemini-2.5-flash --approval-mode yolo
Análise multi-diretório	yolo (se background)	--include-directories <DIR1> --include-directories <DIR2>
Interativo com prompt	auto_edit ou default	-i "prompt" --approval-mode <mode>

Guia de Seleção de Modelo

Modelo	Melhor para	Janela de contexto	Características principais
gemini-3-pro-preview ⭐	Modelo principal: Raciocínio complexo, codificação, tarefas agênticas	1M input / 64k output	Vibe coding, 76,2% SWE-bench, R$0,04-0,08/M input
gemini-3-flash	Latência sub-segundo, aplicações críticas em velocidade	1M input / 64k output	Destilado de 3 Pro, otimizado para TPU
gemini-2.5-pro	Legado: Desempenho sólido em geral	1M input / 65k output	Modo thinking, maturidade estável
gemini-2.5-flash	Legado: Eficiente em custo, tarefas de alto volume	1M input / 65k output	Melhor preço (R$0,003/M), modo thinking
gemini-2.5-flash-lite	Legado: Processamento mais rápido, alto rendimento	1M input / 65k output	Velocidade máxima, latência mínima

Vantagens Gemini 3: 35% maior precisão em engenharia de software, estado-da-arte em SWE-bench (76,2%), GPQA Diamond (91,9%) e WebDev Arena (1487 Elo). Corte de conhecimento: janeiro de 2025.

Em Breve: gemini-3-deep-think para raciocínio ultra-complexo com capacidades de thinking aprimoradas.

Casos de Uso Comuns

Revisão de Código (Background/Automatizado)

# Para execução background (Claude Code, CI/CD, etc.)
gemini -m gemini-3-pro-preview --approval-mode yolo \
  "Realizar uma revisão de código abrangente focando em:
   1. Vulnerabilidades de segurança
   2. Problemas de desempenho
   3. Qualidade e manutenibilidade do código
   4. Violações de melhores práticas"

# Com timeout de segurança (5 minutos)
timeout 300 gemini -m gemini-3-pro-preview --approval-mode yolo \
  "Realizar uma revisão de código abrangente..."

Revisão de Plano (Background/Automatizado)

# Para execução background
gemini -m gemini-3-pro-preview --approval-mode yolo \
  "Revisar este plano arquitetural verificando:
   1. Preocupações com escalabilidade
   2. Componentes ausentes
   3. Desafios de integração
   4. Abordagens alternativas"

Análise de Contexto Amplo (Background/Automatizado)

# Para execução background
gemini -m gemini-3-pro-preview --approval-mode yolo \
  "Analisar toda a base de código para compreender:
   1. Arquitetura geral
   2. Padrões e convenções principais
   3. Possível débito técnico
   4. Oportunidades de refatoração"

Revisão de Código Interativa (Apenas Terminal)

# Use default mode APENAS em terminal interativo
gemini -m gemini-3-pro-preview --approval-mode default \
  "Revisar o fluxo de autenticação para problemas de segurança"

Acompanhamento

• Sessões CLI Gemini são tipicamente únicas ou interativas. Ao contrário do Codex, não há funcionalidade de retomada integrada.
• Para análise de acompanhamento, inicie uma nova sessão Gemini com contexto dos achados anteriores.
• Ao propor ações de acompanhamento, reafirme o modelo e modo de aprovação escolhidos.
• Use AskUserQuestion após cada comando Gemini para confirmar próximas etapas ou coletar esclarecimentos.

Tratamento de Erros

• Pare e informe falhas sempre que gemini --version ou um comando Gemini sair com código não-zero.
• Solicite direcionamento antes de tentar novamente comandos com falha.
• Antes de usar flags de alto impacto (--approval-mode yolo, -y, --sandbox), peça permissão ao usuário usando AskUserQuestion a menos que já tenha sido concedida.
• Quando a saída incluir avisos ou resultados parciais, resuma-os e pergunte como ajustar usando AskUserQuestion.

Solução de Problemas de Processos Gemini Pendurados

Detecção

# Verificar processos pendurados
ps aux | grep -E "gemini.*gemini-3" | grep -v grep

# Procurar por estes sintomas:
# - Processo em execução 20+ minutos
# - Uso de CPU em 0%
# - Estado do processo 'S' (dormindo)
# - Sem conexões de rede

Diagnóstico

# Obter informações detalhadas do processo
ps -o pid,etime,pcpu,stat,command -p <PID>

# Verificar atividade de rede
lsof -p <PID> 2>/dev/null | grep -E "(TCP|ESTABLISHED)" | wc -l
# Se o resultado for 0, o processo está pendurado

Resolução

# Matar processos Gemini pendurados
pkill -9 -f "gemini.*gemini-3-pro-preview"

# Ou matar PID específico
kill -9 <PID>

# Verificar limpeza
ps aux | grep gemini | grep -v grep

Prevenção

• SEMPRE use --approval-mode yolo para tarefas automatizadas/background
• Adicione wrapper de timeout para segurança: timeout 300 gemini ...
• Nunca use --approval-mode default em shells não-interativos
• Monitore primeira execução com ps para garantir que o processo termina

Dicas para Processamento de Contexto Grande

1. Seja específico: Forneça prompts claros e estruturados sobre o que analisar
2. Use include-directories: Especifique explicitamente todos os diretórios relevantes
3. Escolha o modelo certo:
   • Use gemini-3-pro-preview para raciocínio complexo, tarefas de codificação e qualidade máxima de análise (padrão recomendado)
   • Use gemini-3-flash para tarefas críticas em velocidade exigindo respostas sub-segundo
   • Use gemini-2.5-flash para processamento de alto volume otimizado por custo
4. Aproveite os pontos fortes do Gemini 3: 35% melhor em tarefas de engenharia de software, excepção em workflows agênticos e vibe coding
5. Divida tarefas complexas: Mesmo com contexto grande, análise estruturada é mais efetiva
6. Salve resultados: Peça ao Gemini para exportar relatórios estruturados que podem ser salvos para referência

Versão CLI

Exige Gemini CLI v0.16.0 ou posterior para suporte do modelo Gemini 3. Verifique versão: gemini --version