Pular para o conteúdo principal
Uma diretiva de revisão permite dizer à Kody onde concentrar a análise mais profunda em uma revisão específica. Em vez de mudar qualquer configuração, você anexa uma instrução curta ao acionar a revisão — por exemplo, “foque na lógica de auth e sessão” — e a Kody gasta a análise mais rigorosa no código alterado que corresponde a isso.
Uma diretiva é efêmera: vale apenas para aquela execução de revisão. Ela não é salva nas suas configurações e não afeta revisões futuras. Para mudar o comportamento da Kody de forma permanente, use as instruções de categoria e a personalidade de Kody (Instruções e Personalidade, antigos Custom Prompts) ou Kody Rules.

​
Quando Usar

  • Um PR mexe em muitos arquivos, mas você se importa mais com uma área arriscada (auth, pagamentos, uma migração).
  • Você quer que a Kody rastreie os callers e callees de uma mudança específica e a questione com mais rigor.
  • Você está reexecutando uma revisão e quer direcionar a atenção sem editar nenhuma configuração.

​
Prioridade, Não Filtro

Este é o ponto mais importante de entender:
Uma diretiva define prioridade, não filtro. A Kody prioriza a área de foco, mas ainda reporta qualquer bug, problema de segurança ou de performance concreto que perceba em outros pontos do diff. Ela nunca suprime achados fora do foco e nunca aprova o resto do PR sem olhar.
Use uma diretiva para dizer “olhe aqui com mais afinco” — não “olhe só aqui.”

​
Como Acionar

Coloque o texto de foco logo após o comando de revisão em um comentário do pull request:
Você também pode usar start-review e combinar com --force:
--force reexecuta a review mesmo quando Kody normalmente pularia (“nenhum commit novo desde a última review”). Use — com ou sem diretiva de foco — para obter uma nova análise depois de corrigir o que fez a execução anterior falhar, ou para aplicar configurações atualizadas a um PR já revisado.
Apenas a primeira linha após o comando é usada como diretiva. Tudo nas linhas seguintes é ignorado, então mantenha o foco em uma única linha.
Funciona no GitHub, GitLab, Azure DevOps, Bitbucket e Forgejo.

​
Heavy mode

Uma diretiva de foco diz ao Kody onde olhar com mais atenção. O --heavy diz para olhar de forma mais ampla: junto com a revisão de sempre, nove revisores especialistas leem o diff inteiro, cada um atrás de um único tipo de defeito:
  • código que diz uma coisa e faz outra (nomes, medições, resultados)
  • texto que chega a uma pessoa — mensagens, comentários, traduções — em desacordo com o código
  • estado inválido, invariantes quebradas e condições de corrida
  • suposições de limite, índice e ordem
  • segredos e identidade: comparações, normalização, valores de fallback
  • um contrato alterado que um chamador não acompanhou
  • testes que continuariam passando se o comportamento que cobrem quebrasse
  • dados vazando em respostas, logs e mensagens de erro
  • dois arquivos alterados que não concordam entre si
Todo achado de especialista passa pela mesma verificação dos achados da revisão principal antes de qualquer coisa ser publicada, e depois pela deduplicação e severidade de sempre — então um palpite que não se sustenta é descartado como qualquer outro.

​
Heavy por padrão, ou para uma revisão

A configuração Review mode em Code review → General escolhe como toda revisão de um repositório roda: Balanced (o padrão, só a revisão principal) ou Heavy. Ela vale para as revisões automáticas, para o @kody review e para o kodus review. Uma flag em um comando a sobrescreve naquela revisão:
O --heavy roda uma revisão heavy em um repositório configurado como Balanced; o --balanced roda uma revisão balanced em um repositório configurado como Heavy. Se um comando trouxer as duas, vence o --heavy. Qualquer uma das flags pode ficar em qualquer posição da linha — antes ou depois do texto de foco — e é removido da diretiva de qualquer jeito, então @kody review foca na lógica de retry --heavy foca em “foca na lógica de retry”. As flags se combinam em qualquer ordem: @kody review --heavy --force roda uma revisão heavy forçada. Num pull request que a Kody já revisou, pedir o modo diferente do da última revisão revisa o pull request inteiro, não só os commits desde então. O traço é obrigatório: um heavy ou balanced solto é lido como texto de diretiva, então @kody review heavy fluxo de checkout foca em “heavy fluxo de checkout” em vez de ligar a flag.

​
O que esperar

  • Disponível para todos, na Cloud e no self-hosted. Sem pedido de acesso. Na CLI, exige um time logado (kodus auth login): uma revisão em modo trial roda sem ele e avisa.
  • Suas categorias continuam valendo. Os especialistas de uma categoria desligada não rodam: sete são de Bug e dois de Security. Kody Rules e agentes customizados rodam como sempre.
  • Roda no modelo Heavy. Em AI providers → Routing → Code Review, o Model for Heavy escolhe o modelo das revisões heavy e o Model for Balanced o das revisões balanced. Sem um modelo Heavy definido, uma revisão heavy usa o padrão da organização. Um modelo definido para um repositório ou diretório em Code review → General roda os dois modos.
  • Custa mais e demora mais. Na nossa avaliação com 30 pull requests, comparada ao Balanced no mesmo modelo, a revisão heavy levou até cerca do dobro do tempo e cerca de 2,5 vezes o custo de modelo por pull request. Ela encontrou cerca de um problema real a mais a cada dois pull requests e publicou cerca de um comentário a mais por pull request que não era um problema real. Com a sua própria chave de modelo (BYOK), o custo extra entra na conta do seu provedor, e um provedor com limite de concorrência baixo pode enfileirar as chamadas.
  • Sem acesso ao repositório (sem sandbox), os especialistas leem só o diff, como a revisão principal faz nesse caso.
  • A lista de pull requests mostra um selo Heavy nos PRs cuja última revisão rodou em heavy mode.
Defina Heavy como Review mode dos repositórios em que deixar algo passar sai caro — um serviço de pagamentos, um módulo de auth — ou peça com --heavy em uma única mudança arriscada.

​
Escrevendo uma Boa Diretiva

  • Seja específico sobre a área, não sobre o veredito. “foque em concorrência no consumidor da fila” funciona melhor que “encontre bugs”.
  • Nomeie o código, não o resultado. Aponte para um módulo, fluxo ou preocupação (“a lógica de retry”, “o SQL no serviço de relatórios”).
  • Seja breve. Diretivas têm limite de 500 caracteres; só a primeira linha do comentário é lida.
  • @kody review foque no fluxo de autenticação e refresh de token
  • @kody review foque no novo tratamento do webhook do Stripe
  • kodus review --focus "condições de corrida no worker em background"
  • @kody review por favor seja minucioso — não há área para priorizar.
  • @kody review comente só no arquivo X — uma diretiva não é filtro; use Ignored files para restringir arquivos.

​
Observações e Limites

  • Tamanho: diretivas são truncadas em 500 caracteres.
  • Só a primeira linha: em comentários de PR, apenas a primeira linha após o comando vira a diretiva.
  • Não confiável por design: como qualquer pessoa que pode comentar no PR pode fornecer uma diretiva, o texto é sanitizado antes do uso (caracteres de controle e sinais de menor/maior são removidos). Isso não altera o seu foco — apenas impede que o texto adultere o prompt interno da Kody.
  • Não persistida: nada é gravado nas configurações do seu repositório ou organização.