Ensinando suas regras ao CodeRabbit: code review com IA que entende sua stack

Toda equipe acaba escrevendo o mesmo comentário em pull requests: "Aqui a gente não faz assim." Talvez seja um composable de Nuxt que deveria estar em composables/ e não em uma pasta utils/ qualquer. Talvez seja um controller Laravel consultando o banco direto, sem passar por uma service class. Ou ainda uma interface TypeScript duplicada pela terceira vez no sprint.

Ferramentas de code review com IA prometem pegar esses problemas antes de alguém abrir o diff. O problema é que, na configuração padrão, a maioria revisa código como generalista — competente, mas ignorando suas convenções. O CodeRabbit reduz essa distância, e o diferencial aparece de verdade quando você ensina as regras do seu time.

Neste artigo, vejo como o CodeRabbit atua nos pull requests, onde ficam as regras personalizadas e como configurá-las para uma stack moderna com Nuxt, Vue, TypeScript, Laravel ou Node.js — sem transformar o bot em um linter barulhento.

O que o CodeRabbit faz em um pull request

O CodeRabbit se integra ao GitHub e ao GitLab como um bot que responde a eventos de PR. Quando um pull request é aberto ou atualizado, ele lê o diff, resume a mudança, deixa comentários inline em linhas específicas e pode sugerir melhorias ou até abrir commits de follow-up com recursos de agente.

Isso já ajuda no primeiro dia. Mas reviews iniciais ainda parecem genéricos até você configurar o que o bot deve priorizar. Felizmente, o CodeRabbit expõe várias camadas de personalização, todas versionadas em um arquivo .coderabbit.yaml na raiz do repositório.

Comece com uma configuração base

Antes de escrever regras customizadas, defina um perfil sensato. Um ponto de partida mínimo pode ser:

# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
reviews:
  profile: "chill"
  high_level_summary: true
  review_status: true
  auto_review:
    enabled: true
    drafts: false
  path_filters:
    - "!**/dist/**"
    - "!**/node_modules/**"
    - "!**/*.lock"

O profile controla o tom — chill reduz nitpicking, enquanto assertive é mais rigoroso. Os path filters fazem o CodeRabbit ignorar artefatos gerados, lock files e build output, focando no código que humanos mantêm de fato.

Se você já configurou o CodeRabbit pela interface web, não precisa reconstruir tudo manualmente. Comente @coderabbitai configuration em qualquer PR e o bot devolve o YAML resolvido. Copie para .coderabbit.yaml, faça commit, e a configuração passa a ser revisável como qualquer outro código.

Quatro formas de adicionar regras personalizadas

Regras customizadas no CodeRabbit não são um único recurso — são mecanismos complementares. Pense neles como camadas, dos padrões amplos do time até guardrails específicos por pasta.

1. Reaproveite arquivos de guidelines que você já tem

Se o time já mantém instruções para assistentes de código com IA, o CodeRabbit pode detectá-las automaticamente. Por padrão, ele lê arquivos como AGENTS.md, .cursorrules, CLAUDE.md, .github/copilot-instructions.md e REVIEW.md, aplicando o conteúdo como critério de review.

É o caminho de menor atrito. Você escreve os padrões uma vez; Cursor, Copilot e CodeRabbit leem a mesma fonte de verdade.

Para nomes fora do padrão, estenda a detecção explicitamente:

knowledge_base:
  code_guidelines:
    enabled: true
    filePatterns:
      - "**/CODING_STANDARDS.md"
      - "**/docs/convenções-frontend.md"

Um AGENTS.md para Nuxt + TypeScript pode exigir <script setup lang="ts">, lógica server-only em server/ e composables em vez de chamadas de API nos componentes. O CodeRabbit aplica isso no review sem docs duplicadas.

2. Path instructions para reviews com contexto

Guidelines globais ajudam, mas partes diferentes do código exigem olhares diferentes. Path instructions permitem anexar regras focadas a padrões glob em reviews.path_instructions.

Exemplo para um monorepo full-stack:

reviews:
  path_instructions:
    - path: "apps/web/components/**"
      instructions: |
        - Vue 3 Composition API com <script setup lang="ts"> apenas.
        - Sem fetch() direto; usar useFetch ou $fetch via composables.
        - Props tipadas com defineProps; eventos com defineEmits.
        - Sinalizar atributos de acessibilidade ausentes em elementos interativos.
    - path: "apps/web/server/api/**"
      instructions: |
        - Rotas server do Nuxt devem validar input com schemas zod.
        - Nunca expor tokens internos de serviço nas respostas.
        - Retornar erros consistentes: { statusCode, message }.
    - path: "apps/api/app/Http/Controllers/**"
      instructions: |
        - Controllers enxutos; lógica de negócio em classes Service.
        - Todo input de usuário passa por Form Request.
        - Sinalizar riscos de N+1 e checagens de autorização ausentes.
    - path: "**/*.spec.ts"
      instructions: |
        - Testes devem cobrir caminho feliz, falhas de validação e edge cases.
        - Preferir nomes descritivos em vez de "should work" genérico.
        - Mockar HTTP externo na borda, não no meio de units.

É aqui que o CodeRabbit deixa de parecer revisor genérico e passa a agir como alguém que conhece sua arquitetura. Mantenha cada bloco focado — dez bullets claros valem mais que um texto enorme que o modelo ignora em parte.

O CodeRabbit também pode ajudar a expandir essa lista. Depois de revisar vários PRs, comente @coderabbitai emit path instructions para coletar sugestões das reviews recentes e abrir um PR que as incorpora ao YAML sem sobrescrever entradas existentes.

3. Pre-merge checks para políticas inegociáveis

Algumas regras não devem ser sugestões — devem bloquear ou avisar antes do merge. Pre-merge checks validam metadados e conteúdo do PR com políticas definidas em linguagem natural.

reviews:
  pre_merge_checks:
    title:
      mode: "warning"
      requirements: "Começar com verbo no imperativo; até 72 caracteres."
    custom_checks:
      - name: "Breaking Changes Documentadas"
        mode: "error"
        instructions: |
          Aprovar se breaking changes em rotas públicas, env vars
          ou migrations estiverem documentadas na descrição do PR
          e no CHANGELOG.md. Reprovar caso contrário.
      - name: "Sem Console Logs em Código de Produção"
        mode: "warning"
        instructions: |
          Sinalizar console.log, console.debug ou dd() adicionados
          em código de aplicação fora de testes, em apps/ ou packages/.

Cada custom check tem um mode: off, warning ou error. Comece novos checks como warning enquanto calibra falsos positivos; promova políticas críticas para error quando o time confiar neles.

Antes de commitar, teste interativamente comentando no PR:

@coderabbitai evaluate custom pre-merge check --name "Breaking Changes Documentadas" --instructions "..." --mode error

Esse dry-run evita mergear um check que dispara em todo PR porque as instruções ficaram ambíguas.

4. Receitas customizadas de finishing touches

Reviews detectam problemas; finishing touches corrigem. Receitas em reviews.finishing_touches.custom definem tarefas nomeadas que o time dispara com um comentário como @coderabbitai run tighten types.

reviews:
  finishing_touches:
    custom:
      - name: "tighten types"
        instructions: |
          Nos arquivos TypeScript alterados, substituir `any` pelo tipo
          mais específico correto. Adicionar return types explícitos
          em funções exportadas que não os tenham.
      - name: "normalize imports"
        instructions: |
          Ordenar imports: pacotes externos, aliases internos,
          caminhos relativos. Remover apenas imports não utilizados.

Receitas funcionam bem para limpeza repetitiva que todo reviewer menciona, mas ninguém quer fazer na mão — ordenação de imports, type assertions obsoletas, tratamento de erro ausente em jobs Laravel assíncronos ou normalização de auto-imports do Nuxt.

Dicas de rollout para manter reviews úteis

Regras customizadas são fáceis de exagerar. Um .coderabbit.yaml inchado gera reviews longas e contraditórias que o time aprende a ignorar. Trate a configuração como produto:

Comece enxuto. Adicione path instructions primeiro nos diretórios mais barulhentos — geralmente controllers de API, composables compartilhados ou migrations.
Versione tudo. Mantenha .coderabbit.yaml na branch principal e deixe configs de feature branch valerem para o PR em review, para experimentos não surpreenderem o time inteiro.
Alinhe com CI, não duplique. ESLint, PHPStan e TypeScript já pegam sintaxe e tipos. Use o CodeRabbit para julgamento arquitetural, testes faltando, padrões de segurança e convenções que CI não expressa.
Revise o revisor. Quando o CodeRabbit errar por omissão, adicione path instruction. Quando nitpickar demais, ajuste filters ou use profile chill naquele repo.

Onde o CodeRabbit se encaixa no fluxo moderno

Os times que mais extraem valor não são os que têm o YAML mais longo. São os que tratam a configuração do CodeRabbit como documentação viva: atualizada quando convenções mudam, escopada onde julgamento importa e ancorada em arquivos que o time já mantém para assistentes de IA e novos devs.

Se seus pull requests ainda parecem output genérico de linter, a solução provavelmente não é trocar de ferramenta — é ensinar a que você já instalou o que seu codebase considera uma boa mudança. O CodeRabbit fornece os ganchos. As regras são suas.