eins78/agent-skills

Revisão de Código com IA

Solicite revisões de código de um segundo modelo de IA durante a sessão via CLI.

Pré-requisitos

• CLI gemini instalada (execute ${CLAUDE_SKILL_DIR}/scripts/install-dependencies.sh)
• Autenticação: variável de ambiente GEMINI_API_KEY (recomendado — veja "API Paga" abaixo) ou OAuth da Conta Google (gemini interativamente uma vez)
• Opcional: CLI codex para revisões OpenAI: brew install codex

CRÍTICO: Nunca Pule Revisões

Qualidade acima da velocidade. Quando uma revisão é solicitada, você DEVE esperar pelo resultado. NÃO:

• Pule a revisão devido a limites de taxa ou timeouts
• Prossiga sem a revisão e diga "podemos revisar depois"
• Substitua sua própria revisão em vez de chamar o modelo externo

A CLI gemini lida com novas tentativas de limite de taxa automaticamente. Se o script sair com timeout (código de saída 2), peça ajuda ao seu parceiro humano — não continue silenciosamente.

Limites de Taxa (Nível Gratuito — Autenticação por Conta Google)

Métrica	Limite
Requisições por minuto	60 RPM
Requisições por dia	1.000 RPD
Capacidade (tokens/tempo)	Muito baixa — o verdadeiro gargalo
Modelo	Selecionado automaticamente pelo Google (atualizações ao longo do tempo)
Custo	R$ 0

Importante: Os limites de RPM/RPD raramente são o problema. O Google também impõe uma cota de capacidade (total de tokens processados em uma janela de tempo rolante) que é muito mais restritiva. Payloads grandes de revisão (código + contexto automático) podem esgotar essa cota em apenas algumas requisições, gerando um TerminalQuotaError com um reset de várias horas (tipicamente 1-3 horas). Isso é especialmente apertado em modelos selecionados automaticamente mais novos (por exemplo, Gemini 2.5 Pro).

Para reduzir a pressão na cota:

• Use --no-context para revisões pequenas/focadas para cortar o uso de tokens
• Divida revisões grandes em partes menores
• Use uma chave de API paga para evitar limites de capacidade completamente (veja abaixo)

A CLI tenta novamente automaticamente em hits de limite de taxa por minuto (reseta em segundos). A cota de capacidade NÃO tenta novamente — exige esperar pela janela de reset. O script tem um timeout de 1 hora — se excedido, ele aborta e você deve pedir ajuda ao usuário.

API Paga (Recomendado para Uso Regular)

A cota de capacidade do nível gratuito a torna impraticável para mais de algumas revisões por sessão. Uma chave de API paga remove esse gargalo a um custo mínimo.

Configuração

1. Obtenha uma chave no Google AI Studio
2. Ative o faturamento no projeto Google Cloud associado — sem faturamento, a chave de API ainda usa os limites de capacidade do nível gratuito (o mesmo gargalo do OAuth). No AI Studio: Configurações → Faturamento, ou no Console do Google Cloud.
3. Configure a CLI gemini para usar autenticação por chave de API:

   # Defina o tipo de autenticação nas configurações do gemini (~/.gemini/settings.json)
   # Execute gemini interativamente uma vez — ele solicitará a seleção do método de autenticação.
   # Escolha "Chave da API Gemini" quando solicitado.
   

4. Defina a variável de ambiente:

   export GEMINI_API_KEY="sua-chave-aqui"
   

   Adicione isso ao seu perfil de shell para que novos shells a peguem. Se você estiver em uma sessão já em execução (por exemplo, Claude Code), precisará executar source no arquivo ou reiniciar a sessão.
5. Verifique se funciona: gemini -p "olá" — deve responder sem prompts OAuth ou erros de cota.

Estimativa de Custo (Gemini 2.5 Pro)

	Tokens	Custo
Entrada por revisão (contexto + diff)	~8-12K	~R$ 0,05-0,08
Saída por revisão	~1-2K	~R$ 0,05-0,10
Total por revisão		~R$ 0,10-0,18

Nível de uso	Revisões/mês	Custo estimado
Leve (poucas/semana)	~20	~R$ 2,50
Moderado (poucas/dia)	~60	~R$ 7,50
Intenso (muitas/dia)	~150	~R$ 20,00

Rastreamento de Uso

• AI Studio → Painel → Guia Uso (requisições, tokens, custos)
• Console do Google Cloud → APIs e Serviços → Painel → "API de Linguagem Generativa"
• Relatórios de Faturamento → agrupar por SKU para detalhamento por modelo
• Dica: Crie várias chaves no mesmo projeto para separar o uso de ai-review do uso interativo da CLI gemini

Como Usar

Passo 1: Determinar o que Revisar

Escolha com base no contexto:

Situação	O que enviar
Acabou de escrever código	Os arquivos específicos alterados
No meio de uma funcionalidade	git diff (alterações não preparadas)
Antes do commit	git diff --cached (alterações preparadas)
Revisão de branch	git diff main...HEAD
Preocupação específica	Arquivo ou função única

Passo 2: Executar a Revisão

Use o script de revisão em ${CLAUDE_SKILL_DIR}/scripts/review.sh — este caminho resolve para o próprio diretório da skill independentemente do diretório de trabalho atual. Nunca use ./scripts/review.sh (isso é relativo ao CWD e falhará em outros repositórios). Nunca canalize código diretamente para gemini ou codex — sempre use o script de revisão.

# Revisar alterações não preparadas (padrão)
${CLAUDE_SKILL_DIR}/scripts/review.sh

# Revisar alterações preparadas
${CLAUDE_SKILL_DIR}/scripts/review.sh --staged

# Revisar arquivos específicos
${CLAUDE_SKILL_DIR}/scripts/review.sh caminho/para/arquivo1.swift caminho/para/arquivo2.swift

# Revisar diff do branch vs main
${CLAUDE_SKILL_DIR}/scripts/review.sh --branch

# Revisar branch vs remoto (ao trabalhar diretamente no main)
REVIEW_BASE_BRANCH=origin/main ${CLAUDE_SKILL_DIR}/scripts/review.sh --branch

# Adicionar string de contexto extra para melhores revisões
${CLAUDE_SKILL_DIR}/scripts/review.sh --context "App SwiftUI, iOS 18+, Swift 6" caminho/para/arquivo.swift

# Revisar com um arquivo de plano específico
${CLAUDE_SKILL_DIR}/scripts/review.sh --plan PLAN.md caminho/para/arquivo.swift

# Pular contexto automático (enviar apenas o código/diff)
${CLAUDE_SKILL_DIR}/scripts/review.sh --no-context --staged

Passo 3: Agir com Base no Feedback

Após receber a revisão:

1. Resolva quaisquer problemas de severidade ERROR imediatamente
2. Considere itens WARNING — corrija a menos que haja um bom motivo para não fazê-lo
3. Itens INFO são sugestões — use seu julgamento
4. Se a revisão levantar perguntas sobre as quais você não tem certeza, discuta com o usuário

Lidando com Falhas

Código de saída	Significado	Ação
0	Sucesso	Agir com base no feedback da revisão
1	Nenhum código para revisar / argumentos inválidos	Verificar argumentos
2	Timeout (>1 hora bloqueado)	Pedir ajuda ao usuário — não pular a revisão

Contexto Automático

O script de revisão automaticamente anexa contexto do projeto a cada revisão para que o revisor entenda convenções, arquitetura e intenção. Nenhuma seção manual "Contexto da Revisão de Código" necessária no CLAUDE.md.

Incluído automaticamente (em ordem):

1. Plano de implementação — primeiro encontrado de: flag --plan, PLAN.md na raiz do repositório, .claude/plans/*.md mais recente
2. Instruções do projeto — primeiro encontrado de: CLAUDE.md, GEMINI.md, AGENTS.md na raiz do repositório
3. Árvore de arquivos — estrutura do repositório na profundidade 3

Use --no-context para pular isso (por exemplo, para payloads muito grandes).

A flag --context adiciona uma string de contexto inline extra além do contexto automático.

Configuração do Provedor

O provedor padrão é gemini. Substitua por sessão:

# Usar OpenAI
REVIEW_PROVIDER=codex ${CLAUDE_SKILL_DIR}/scripts/review.sh

Notas Importantes

• Revisões são consultivas — o segundo modelo pode ter falsos positivos
• Diffs grandes (>50KB) podem ser truncados. Divida em revisões menores, se necessário.
• O modelo de revisão executa em modo prompt (-p) e não pode navegar pelo repositório. O contexto do projeto é incluído automaticamente para compensar — veja "Contexto Automático" acima.