Revisores de código com IA têm um problema conhecido: sem contexto, eles sinalizam como suspeito algo que a equipe fez de propósito, ou ficam sem saber o que dizer. Um usuário relatou nas comunidades do Claude um experimento para atacar justamente isso. Ele construiu skills do Claude Code para revisão, rodou o Claude em pull requests reais com e sem elas, em cerca de 70 revisões, usando Sonnet 5.5 e Opus 5.5 e, depois, Codex para uma segunda opinião. Este artigo resume o relato e propõe como transformá-lo em prática de engenharia. Os dados são do autor do post, não de um teste nosso.
O que o experimento descreve
- Um arquivo só: REVIEW-LESSONS.md. Quando alguém toma uma decisão em revisão e dá o motivo ("isso parece errado, mas é de propósito"), o motivo vai para esse arquivo.
- Um caso concreto. Ao revisar uma mudança de arredondamento, o Claude sem o arquivo respondeu "pergunte a alguém". Com o arquivo, respondeu que a mudança "reverte uma decisão que a equipe registrou de propósito".
- O problema que isso resolve. Resumos de workflows publicados em r/ClaudeWorkflows descrevem que revisores de IA tendem a sinalizar comportamentos intencionais como problemas, e propõem o arquivo de lições junto com skills personalizadas como forma de dar conhecimento institucional à revisão.
O que isso muda para a sua empresa
Em muitas equipes, as decisões técnicas importantes vivem na cabeça de poucas pessoas, em threads de chat ou em comentários antigos de PR. A IA não tem acesso a isso, e um novo desenvolvedor também não. Um arquivo vivo de decisões serve aos dois: dá contexto ao revisor automático e ajuda a detectar regressões que violam escolhas deliberadas, como regras de cálculo, arredondamento, tratamento de erros ou limites de negócio. É conhecimento disperso virando prática replicável. A mesma lógica aparece em memória para agentes de IA.
Piloto em 5 passos
- Escolha o escopo. Um repositório e um grupo pequeno de PRs (por exemplo, as próximas 20 a 30 revisões).
- Crie o arquivo de lições. Comece com as decisões que a equipe já sabe de cabeça: o que, por que e em que situação a regra se aplica. Cada decisão nova de revisão ganha uma entrada com o motivo.
- Integre ao fluxo de pull requests. Configure o Claude para ler o arquivo antes de revisar (por exemplo, por referência no CLAUDE.md ou em uma skill de revisão) e deixe a revisão automática como comentário, nunca como aprovação.
- Compare com e sem o arquivo. Como no experimento, rode a mesma revisão nas duas condições nos PRs de teste e compare as respostas.
- Defina critérios de avaliação. Por exemplo: quantos alertas falsos sobre decisões intencionais; quantas regressões contra decisões registradas foram detectadas; quanto tempo o revisor humano economizou; e quantas entradas do arquivo ficaram desatualizadas.
Riscos e cuidados
- Arquivo desatualizado vira armadilha. Uma decisão antiga registrada pode levar a IA a defender algo que já não vale. Dê um responsável e revise o arquivo periodicamente.
- Não substitui a revisão humana. O resultado vem de um relato individual. Trate a IA como primeira leitura, não como aprovadora. Veja como usar IA para programar com segurança.
- Cuidado com o conteúdo. O arquivo não deve conter segredos, dados de clientes nem detalhes sensíveis.
- Custo de contexto. Um arquivo grande consome tokens em toda revisão; mantenha-o enxuto, como em como reduzir o consumo de tokens no Claude Code.
Para escolher o modelo de cada etapa, veja como comparar modelos de IA para programação em tarefas reais.
Quer ver onde a IA gera retorno na sua operação? No diagnóstico gratuito, mapeamos seus processos e indicamos o que automatizar primeiro.
Quero meu diagnóstico gratuito →Conclusão
Usar IA para revisar código com Claude funciona melhor quando o revisor conhece as decisões da equipe. Um arquivo de lições é uma forma barata de testar isso, desde que haja piloto, critérios claros e um responsável. A Yggra, como consultoria de tecnologia, ajuda empresas a desenhar esse piloto e a integrá-lo ao fluxo de PRs. Conheça nosso trabalho com agentes de IA e software sob medida, ou fale com a Yggra.
Fontes
- r/ClaudeCode, Without a lessons file, Claude reviewing a rounding change said "ask someone". With one, it said "it reverses a decision the team recorded on purpose".
- r/ClaudeAI, mesmo post em r/ClaudeAI.
- r/claudeskills, mesmo post em r/claudeskills.
- r/ClaudeWorkflows, Enhancing Claude Code Review with REVIEW-LESSONS.md for Institutional Knowledge and Custom Skills.
- r/ClaudeWorkflows, Enhancing Claude Code Reviews with Institutional Knowledge via REVIEW-LESSONS.md and Custom Skills.
Perguntas frequentes
Como usar IA para revisar código com Claude?
Rode o Claude sobre os pull requests e alimente-o com um arquivo de lições (como o REVIEW-LESSONS.md) que registre decisões deliberadas da equipe e o motivo de cada uma. Assim, o revisor deixa de sinalizar como erro o que é intencional e reconhece mudanças que revertem uma decisão registrada.
O que é o REVIEW-LESSONS.md?
É um arquivo único descrito em posts de comunidades como r/ClaudeCode e r/ClaudeAI. Quando alguém toma uma decisão em uma revisão com um motivo ("parece errado, mas é de propósito"), o motivo é registrado nele para que revisões futuras o consultem.
O resultado do experimento vale para a minha empresa?
Não como garantia. É um relato de um usuário, com cerca de 70 revisões, e não um teste nosso. Use-o como hipótese e valide com um piloto no seu próprio código.
