Um pull request criado com ajuda de IA pode chegar bonito na superfície, com diff organizado, descrição razoável e teste passando. A intenção de como revisar PR com CLAUDE.md aparece quando o agente ignora idioma, padrão de pasta, comando obrigatório, limite de escopo ou regra de domínio que deveria ter recebido antes de tocar no repositório.

Revisar PR com CLAUDE.md ajuda justamente nesse ponto, porque o arquivo registra referência persistente para comparar intenção, diff e evidência de teste. Ele não existe para decorar o projeto, mas para reduzir comentário repetido e dar ao review uma base escrita.

Eu não uso o arquivo de agente como substituto da revisão humana em pull requests com mudança relevante. Uso como contrato de referência, porque o PR revela tanto a aderência do agente quanto lacunas que ainda precisam entrar na memória do projeto.

Aqui na Promovaweb, Luiz Eduardo Oliveira Fonseca trata agentes de código com Git, permissão delimitada e revisão humana. A IA pode ajudar a escrever, explicar e apontar achados, mas a decisão de merge continua sendo responsabilidade de uma pessoa que entende risco, escopo, manutenção e consequência técnica.

Direto ao ponto

Para revisar PR com CLAUDE.md, use o arquivo como referência persistente de padrões, fontes de verdade, comandos de validação, limites de edição e cuidados de segurança. O review deve comparar o diff com esse contrato, sem terceirizar aprovação para a IA, e atualizar a memória apenas quando o PR revelar regra recorrente ausente ou desatualizada.

O que muda quando a referência está escrita

Um review ruim gasta energia com o básico, repetindo instruções que já deveriam estar disponíveis antes da implementação. A pessoa revisora precisa explicar idioma, lugar de arquivo, convenção de commit ou comando de validação como se cada PR começasse do zero.

Um CLAUDE.md bem mantido não elimina esse trabalho por completo, mas diminui a repetição. O agente recebe regras antes da tarefa, e a pessoa revisora ganha um parâmetro objetivo para avaliar se o diff respeitou o projeto.

Esse ponto conversa com o post sobre contrato operacional para agentes em projetos reais. O arquivo precisa guardar regra persistente, limite de edição e validação final, ou o PR gerado com IA vira mais uma rodada de interpretação solta.

Na prática, a revisão melhora quando o comentário sai de gosto pessoal e aponta para uma regra registrada. Essa diferença torna o feedback mais claro e facilita corrigir o agente, o arquivo de referência ou o pedido original.

Review de PR combina diff, referência e evidência

O diff mostra o que mudou, enquanto o arquivo de referência ajuda a entender se a mudança respeita o modo como o projeto deve mudar. Essa diferença importa em código gerado ou editado por agente, porque o resultado pode parecer plausível e ainda desviar do contrato do sistema.

Eu olho para três camadas durante o review: intenção, aderência e evidência da alteração proposta. A primeira verifica se o PR resolve o problema declarado, a segunda compara o diff com regras do projeto, e a terceira confirma teste, log, captura, descrição ou verificação que sustente a alteração.

Sem histórico persistente, cada pessoa revisora reconstrói essas camadas a partir da própria memória. Com CLAUDE.md, parte desse critério fica explícita e a revisão deixa de depender da pessoa mais experiente disponível naquele momento.

Isso não transforma o arquivo em juiz automático, porque ele não sabe se uma exceção faz sentido ou se uma regra precisa mudar. Ele organiza a conversa para que a decisão humana seja mais bem informada.

O que precisa estar no CLAUDE.md para ajudar o review

O arquivo precisa registrar aquilo que aparece com frequência nos comentários de PR. Se a pessoa revisora repete a mesma instrução toda semana, existe boa chance de aquilo virar regra persistente do projeto.

Eu colocaria regras de idioma, comandos de validação, fontes de verdade, limites de permissão, padrão de branch, expectativa de PR pequeno e áreas sensíveis do repositório. Também colocaria critérios de parada, deixando claro quando o agente deve pedir referência em vez de continuar inferindo.

O cuidado é não transformar o arquivo em depósito de todo conhecimento técnico. Procedimento recorrente pode virar skill, regra localizada pode ficar perto da área afetada, e referência grande pode entrar por import quando for fonte mantida.

O post sobre imports sem duplicar referência de projeto aprofunda esse limite. Um bom arquivo para review responde qual padrão respeitar, qual comando prova a mudança, qual arquivo não deve ser tocado sem motivo e qual alteração exige cuidado maior.

Como o Claude Code Review entra nessa conversa

A documentação oficial do Claude Code descreve o Code Review como análise de pull requests com achados publicados em comentários inline. Isso é útil porque aproxima a IA do ponto exato em que a mudança será discutida.

Mesmo assim, eu não trataria esse recurso como aprovador, porque o fluxo de pull request continua dependendo de revisão, comentário, solicitação de mudança e aprovação antes do merge. A documentação do GitHub reforça esse papel colaborativo do review, com comentários, sugestões, aprovação e pedidos de alteração.

O uso bom é colocar a IA para ampliar cobertura, apontando falhas, regressões, inconsistências com memória do projeto e trechos que merecem atenção. A pessoa revisora decide se o achado procede, se o risco importa e se a mudança deve entrar.

Quando um comentário automatizado encontra algo que também deveria estar no CLAUDE.md, eu vejo oportunidade de manutenção. Talvez a regra esteja ausente, vaga, antiga ou ignorada, e cada caso pede uma correção diferente.

Quando o PR deve atualizar o CLAUDE.md

Nem todo PR precisa mexer na memória do projeto depois de uma alteração localizada e bem explicada. Atualizar CLAUDE.md faz sentido quando a mudança altera regra recorrente, comando de validação, padrão de arquitetura, restrição de segurança, fonte de verdade ou decisão que o agente deve respeitar nas próximas sessões.

Se o PR corrige um bug localizado, talvez a descrição e os testes bastem. Se muda autenticação, validação de dados, organização de pastas, publicação de conteúdo ou build, a memória pode precisar acompanhar.

O post sobre quando atualizar a memória de projeto em tarefas longas com IA ajuda nesse critério. Aprendizado temporário não deve virar regra permanente, enquanto decisão recorrente precisa sair da conversa e entrar no arquivo certo.

Eu prefiro revisar essa necessidade no final do PR, depois de confirmar se a mudança está correta. Assim o arquivo continua enxuto e útil, em vez de acumular cada detalhe de uma tarefa específica.

A descrição do PR continua indispensável

O arquivo de agente não substitui uma descrição de PR bem escrita e ligada ao diff que será revisado. A memória explica o contrato do projeto, enquanto a descrição explica a mudança proposta e ajuda a pessoa revisora a entender intenção, risco e teste.

Um PR apoiado por IA precisa dizer qual problema foi tratado, quais arquivos principais mudaram, quais verificações foram feitas e qual risco merece atenção. Se a descrição não carrega isso, o revisor precisa reconstruir referência por conta própria.

Esse ponto se conecta ao post sobre documentar pull requests em projetos com IA. A descrição não precisa ser longa, mas precisa preservar intenção, risco, teste e limite.

Quando CLAUDE.md, descrição do PR e diff contam histórias diferentes, o review deve parar. A divergência mostra que alguém perdeu referência: quem pediu a mudança, o agente que executou ou a pessoa que escreveu a descrição.

Critérios frequentes

CLAUDE.md reduz comentário repetido quando registra regras que a pessoa revisora costuma repetir. Se o agente continua errando a mesma regra, o review deve checar se o arquivo está claro, atualizado e realmente carregado.

Claude Code Review pode apoiar a revisão com achados inline e comparação com referência do projeto. Ele não assume responsabilidade pelo merge, porque a pessoa revisora ainda precisa avaliar gravidade, aderência, teste, exceção e impacto de manutenção.

O arquivo deve receber regras persistentes, como comandos de validação, padrões de pasta, idioma, fontes de verdade, restrições de segurança, áreas sensíveis e critérios de parada. Instruções temporárias, investigações pontuais e gosto individual não devem virar memória permanente.

O review deve distinguir falha de agente, falha de pedido e falha de referência. Quando a regra estava clara, cobre aderência; quando não existia, registre a lacuna; quando estava antiga, atualize antes de repetir o erro.

O melhor review começa antes do PR

Revisar PR com referência persistente começa antes do diff aparecer, quando o projeto registra o que o agente precisa respeitar, quais fontes não podem ser ignoradas e quais validações encerram uma tarefa. Esse preparo reduz improviso, aproxima o review da regra escrita e torna a revisão mais objetiva.

Eu gosto desse recorte porque ele tira o review da memória informal e coloca a conversa em regra escrita, evidência e referência compartilhada. O PR continua exigindo leitura humana, mas a IA passa a entregar mudança mais revisável em vez de aumentar a quantidade de coisa plausível para alguém conferir depois.

Na Formação IA Makers, esse tema entra como parte da disciplina de trabalhar com IA em projeto real. Git, referência, PR pequeno, teste, revisão humana e memória mantida formam o conjunto mínimo para usar agente de código sem perder rastreabilidade técnica.