Cada Erro Vira uma Regra:
Como o diffray Aprende com Seu Feedback
Por que code review com IA sem aprendizado de feedback é apenas um gerador de ruído caro
Boris Cherny, o criador do Claude Code, revelou recentemente seu fluxo de trabalho, e uma frase da sua thread explodiu pela comunidade de desenvolvedores: "Toda vez que vemos o Claude fazer algo errado, adicionamos ao CLAUDE.md, para que o Claude saiba não fazer na próxima vez."
O líder de produto Aakash Gupta resumiu perfeitamente: "Cada erro vira uma regra." Quanto mais tempo uma equipe trabalha junto com IA, mais inteligente ela se torna.
Esta é exatamente a filosofia sobre a qual o diffray foi construído. Hoje, mostraremos como funciona por baixo dos panos.
O Problema: Poluição de Contexto Mata a Qualidade da Revisão
Antes de falar sobre regras, precisamos entender o principal desafio técnico do code review com IA — poluição de contexto.
A pesquisa da Anthropic mostra que LLMs, como humanos, perdem o foco à medida que a janela de contexto enche. Correções se acumulam, discussões paralelas se empilham, saídas de ferramentas desatualizadas permanecem. O resultado é previsível:
Falsos positivos
A IA encontra "problemas" que não existem
Alucinações
Bugs imaginários e padrões inexistentes
Desvio de objetivo
Revisões se tornam progressivamente menos relevantes
A JetBrains Research (Dezembro 2025) quantificou isso: contextos de agentes crescem tão rapidamente que se tornam caros, mas não entregam desempenho significativamente melhor. Mais contexto ≠ melhores resultados.
A Solução: Subagentes Especializados com Contexto Isolado
Boris Cherny usa subagentes como "encapsulações automatizadas dos fluxos de trabalho mais comuns." Sua filosofia:
"Confiabilidade vem da especialização mais restrição"
Em vez de um revisor onisciente, seu comando de code review gera múltiplos agentes paralelos com responsabilidades distintas:
Esta camada adversarial é crucial. Agentes secundários desafiam os achados do primeiro passe, eliminando falsos positivos através do ceticismo estruturado.
O resultado, nas palavras de Cherny: "encontra todos os problemas reais sem os falsos."
Como Funciona Tecnicamente
Quando o agente principal delega para um subagente, uma janela de contexto nova é gerada contendo apenas a descrição da tarefa e parâmetros relevantes. O subagente pode explorar extensivamente—consumindo dezenas de milhares de tokens buscando código—mas retorna apenas um resumo condensado de 1.000-2.000 tokens.
Isso preserva o foco do agente principal enquanto permite análise profunda.
No diffray, usamos mais de 30 agentes especializados, cada um focado em um domínio específico: segurança, performance, estilo de código, padrões arquiteturais, e mais. Cada agente opera em um contexto isolado e retorna apenas achados substanciais.
Criação de Regras: Transformando Feedback em Conhecimento
Agora o evento principal. Subagentes resolvem o problema do contexto. Mas como você faz a IA aprender com suas correções?
O Padrão CLAUDE.md
No Claude Code, equipes mantêm um arquivo CLAUDE.md em seu repositório—uma espécie de "constituição" para o projeto. O arquivo é carregado automaticamente no contexto em cada sessão.
Mas há uma limitação crítica. A pesquisa da HumanLayer mostra que o prompt do sistema do Claude Code já contém ~50 instruções, e LLMs de fronteira seguem confiavelmente apenas 150-200 instruções no total. A qualidade do seguimento de instruções diminui uniformemente conforme o número aumenta.
Isso significa: você não pode simplesmente despejar 500 regras e esperar mágica.
Três Níveis de Conhecimento
Regras efetivas codificam conhecimento em três níveis:
O QUÊ (Mapa do Projeto)
## Stack Tecnológico
- Backend: Python 3.11, FastAPI, SQLAlchemy
- Frontend: React 18, TypeScript, TailwindCSS
- BD: PostgreSQL 15POR QUÊ (Decisões Arquiteturais)
## Por Que NÃO Usamos ORM para Consultas Complexas
Histórico: ORM gerava consultas N+1 em relatórios.
Decisão: SQL puro para analytics, ORM apenas para CRUD.COMO (Processos)
## Antes de Commitar
- Executar `make lint` — deve passar sem erros
- Executar `make test` — cobertura não deve cairO Problema com Abordagens Manuais
Manutenção manual de regras funciona... enquanto sua equipe for pequena e disciplinada. Na realidade:
Desenvolvedores esquecem de atualizar regras
Regras ficam desatualizadas mais rápido que código
Convenções implícitas permanecem implícitas
Conhecimento tribal morre quando pessoas-chave saem
Como o diffray Automatiza a Criação de Regras
O diffray inverte o processo. Em vez de escrever regras manualmente, você apenas dá feedback nas revisões.
O Ciclo de Aprendizado
Passo 1: Você Dá Feedback
Deu um joinha para baixo em um comentário do diffray? Respondeu "isso não é um bug, é intencional"? Ignorou uma recomendação? O diffray captura tudo.
Passo 2: Extração de Padrões
O diffray analisa: o que exatamente estava errado? Foi um alarme falso (código está correto), contexto inaplicável (regra não se aplica aqui), ou convenção específica do projeto (é assim que fazemos aqui)?
Passo 3: Geração de Regras
Baseado no padrão, o diffray formula uma regra que especifica o escopo (quais arquivos/diretórios), o que suprimir ou aplicar, e por quê. A regra é vinculada ao feedback original para rastreabilidade.
Passo 4: Validação
Antes de aplicar a regra, o diffray a executa contra PRs históricos. Quantos comentários teriam sido suprimidos? Quantos desses eram realmente falsos positivos? A regra é aplicada apenas se melhorar a precisão.
Tipos de Regras no diffray
Regras de Supressão
"Não sinalize X no contexto Y" — silenciar avisos específicos em código legado, arquivos de teste, ou código gerado.
Regras de Aplicação
"Sempre verifique Z" — garantir que padrões críticos como parametrização SQL ou verificações de auth nunca sejam perdidos.
Regras de Contexto
"Considere as especificidades" — ajustar prioridade baseado no tipo de arquivo, decoradores, ou padrões de código circundantes.
Regras de Terminologia
"Chamamos assim" — ensinar ao diffray seu vocabulário de domínio para que ele entenda melhor sua base de código.
Exemplo Prático: De Incômodo a Regra
Imagine: o diffray deixa um comentário no seu PR:
Aviso Performance: Usar any reduz a segurança de tipos. Considere tipagem explícita.
Você sabe que este é um módulo legado programado para reescrita no próximo trimestre. Corrigir tipos agora seria perda de tempo.
Você responde: "Isso é legado, tipagem será tratada durante a refatoração do Q2"
O que acontece depois:
src/legacy/, há um TODO com datasrc/legacy/** com data de expiração (Q2)src/legacy/ — o diffray permanece em silêncio sobre tiposMas importante: a regra não é permanente. A data de expiração significa que após o Q2, o diffray começará a verificar tipos naquele diretório novamente.
A Métrica: Reduzindo a Taxa de Falsos Positivos
A medida chave da efetividade do code review com IA é a taxa de falsos positivos. Quantos comentários de 100 foram inúteis?
Benchmarks típicos da indústria:
40-60%
Falsos positivos de revisão IA base
25-35%
Com regras manuais
8-13%
diffray com regras aprendidas
Como conseguimos isso:
Isolamento de contexto
Através de subagentes previne desvio
Especialização de agentes
Melhora a precisão em cada domínio
Aprendizado com feedback
Elimina falsos positivos recorrentes
Validação de regras
Previne overfitting
Começando: Três Passos
Passo 1: Conecte o diffray ao Seu Repositório
A integração leva 5 minutos via GitHub App ou webhook do GitLab.
Passo 2: Apenas Trabalhe
Durante as primeiras 2-3 semanas, o diffray opera em modo de aprendizado. Ele estuda a estrutura do seu projeto, seus padrões de PR, e o estilo de comentários dos seus revisores.
Passo 3: Dê Feedback
Não ignore silenciosamente os comentários do diffray. Dê joinha para cima nos úteis, joinha para baixo nos inúteis, responda aos debatíveis.
Cada interação torna o diffray mais inteligente. Após um mês, você terá um revisor de IA personalizado que conhece suas convenções melhor que um novo desenvolvedor após o onboarding.
Conclusão: IA Que Cresce com Sua Equipe
A filosofia de "cada erro vira uma regra" não é apenas uma frase de efeito. É um princípio arquitetural que separa ferramentas de brinquedo de soluções prontas para produção.
O diffray é construído sobre três pilares:
Subagentes com contexto isolado
Para precisão sem poluição
Criação de regras a partir de feedback
Para aprendizado sem trabalho manual
Validação no histórico
Para confiança nas melhorias
O resultado: code review com IA que melhora a cada PR. Não porque o modelo foi atualizado, mas porque aprende com sua equipe.
Comece a Ensinar Seu Revisor de IA Hoje
Instale o diffray e abra um PR. É grátis para repos públicos e inclui um generoso plano gratuito para repos privados.