Por Que Regras São a Arma Secreta
do Code Review com IA

No diffray, resolvemos isso com regras estruturadas. Deixe-me mostrar por que elas são a chave para fazer code review com IA realmente funcionar.

O Problema: Diluição de Contexto Mata Performance de IA

Quando você despeja um PR inteiro em uma LLM com um prompt como "revise este código," várias coisas dão errado:

A Solução: Regras Estruturadas

Uma regra estruturada não é apenas um prompt — é uma especificação completa que diz à IA exatamente o que procurar, onde procurar, e como reportar descobertas.

Veja como uma regra se parece:

rules:
  - id: sec_sql_injection
    agent: security
    title: "SQL injection via concatenação de strings"
    description: "Input do usuário concatenado em queries SQL permite atacantes executar SQL arbitrário"
    importance: 9

    match:
      file_glob:
        - "src/api/**/*.ts"
        - "src/routes/**/*.ts"
        - "!**/*.test.ts"
      content_regex:
        - "query.*\$\{|\+.*query"

    checklist:
      - "Encontrar todos os lugares onde input do usuário é usado em queries SQL"
      - "Verificar se queries parametrizadas ou prepared statements são usados"
      - "Verificar que concatenação de strings NÃO é usada para construção de query"

    examples:
      bad: |
        const query = `SELECT * FROM users WHERE id = ${userId}`;
        await db.execute(query);
      good: |
        const query = 'SELECT * FROM users WHERE id = ?';
        await db.execute(query, [userId]);

Esta estrutura habilita três capacidades críticas que fazem code review com IA realmente funcionar.

1. Resultados Determinísticos Através de Direcionamento Preciso

Notou a seção match? Isso é pattern matching que determina quando a regra sequer executa.

Sem pattern matching, revisar um PR de 50 arquivos significa analisar todos os 50 arquivos para cada problema possível. Com pattern matching:

Se um PR tem 5 arquivos de API contendo queries SQL, apenas esses 5 arquivos são enviados para verificações de SQL injection. A IA vê exatamente o que precisa avaliar — nada mais.

Essa precisão elimina a aleatoriedade que assombrava tentativas anteriores de code review com IA. Mesmo código + mesmas regras = mesmas descobertas. Sempre.

2. Arquitetura Multi-Agente: Especialista Certo para Cada Problema

Aqui é onde fica interessante. O diffray não usa uma IA para revisar tudo — ele usa 31 agentes especializados, cada um focado no que faz de melhor:

Cada agente tem um prompt de sistema especializado com expertise de domínio. Um agente de segurança conhece OWASP Top 10. Um agente React entende regras de hooks. Essa especialização melhora dramaticamente a qualidade de detecção.

Mas aqui está a chave: regras determinam qual agente lida com o quê.

- id: react_useeffect_cleanup
  agent: react              # Tratado pelo especialista React
  match:
    file_glob: ["**/*.tsx"]
    content_regex: ["useEffect"]
  checklist:
    - "Verificar se useEffect retorna uma função de cleanup"
    - "Verificar se event listeners e subscriptions são limpos"

Essa regra só vai para o agente React, só para arquivos TSX, só quando useEffect está presente. O agente recebe contexto focado sobre exatamente uma coisa — não 50 preocupações diferentes competindo por atenção.

3. Curadoria de Contexto: O Segredo para Não Diluir Atenção da IA

LLMs modernas podem lidar com 200k+ tokens. Mas pesquisas mostram que performance prática atinge um teto por volta de 25-30k tokens para raciocínio complexo. Além disso, você está pagando por tokens que o modelo não consegue usar efetivamente.

O sistema de gerenciamento de contexto do diffray garante que cada agente receba precisamente a informação que precisa:

Cada agente recebe exatamente o que precisa para fazer seu trabalho. Nada mais. O resultado: atenção focada, melhores descobertas, menos falsos positivos.

4. Flexibilidade: Regras Específicas de Projeto e Equipe

É aqui que regras realmente brilham para equipes. Todo codebase tem convenções que ferramentas genéricas não conhecem:

Suas bibliotecas internas:

- id: use_internal_http_client
  agent: consistency
  title: "Use wrapper de cliente HTTP interno"
  match:
    file_glob: ["src/**/*.ts"]
    content_regex: ["\\bfetch\\(", "axios\\."]
  checklist:
    - "Encontrar chamadas raw fetch() ou axios"
    - "Verificar se código deveria usar httpClient de @/lib/http-client"
  examples:
    bad: |
      const response = await fetch('/api/users');
    good: |
      import { httpClient } from '@/lib/http-client';
      const data = await httpClient.get('/api/users');

Seus padrões específicos de domínio:

- id: money_use_decimal
  agent: bugs
  title: "Use Decimal para valores monetários"
  match:
    content_regex: ["(price|amount|total)\\s*:\\s*(number|float)"]
  checklist:
    - "Encontrar campos monetários usando tipos float/number"
    - "Verificar se armazenamento usa centavos (inteiro) ou tipo Decimal"

Seus requisitos de compliance:

- id: pii_logging_check
  agent: compliance
  title: "Nunca logar PII diretamente"
  tags: [compliance-gdpr, compliance-hipaa]
  match:
    content_regex: ["log.*(email|phone|ssn|password)"]

Coloque esses em .diffray/rules/ e eles estarão ativos no próximo PR. Sem mudanças de infraestrutura, sem atualizações de ferramenta — apenas adicione YAML e seu revisor de IA aprende seus padrões.

Por Que YAML? Estrutura Habilita Inteligência

Você pode se perguntar por que usamos YAML estruturado ao invés de apenas escrever prompts. A estrutura habilita capacidades que prompts de forma livre não conseguem:

Um prompt flat não consegue fornecer essa separação de concerns.

O Resultado: Code Review com IA Que Realmente Funciona

Quando você combina regras estruturadas com arquitetura multi-agente e gerenciamento inteligente de contexto, você obtém:

Isso é o que faz a diferença entre "code review com IA" como demo e code review com IA como infraestrutura na qual sua equipe realmente confia.