Melhore a qualidade dos Pull Requests com Claude Code

Pull Request é o lugar onde uma equipe propõe, revisa e faz merge de mudanças. A documentação oficial do GitHub trata PRs como uma superfície central de colaboração, e isso fica ainda mais importante quando Claude Code acelera a implementação. O gargalo deixa de ser escrever código e passa a ser explicar a mudança: descrição vaga, diff grande demais, evidência de teste fraca, risco de segurança sem análise e comentários de review que voltam ao mesmo ponto.

Neste guia, Claude Code funciona como assistente de qualidade de PR, não apenas como gerador de texto. diff é o conjunto de linhas alteradas, CI é a porta automática de build e teste, diff-size budget é o limite de tamanho do PR, e handoff é a nota curta para o próximo revisor continuar sem reler tudo. Para complementar, veja também code review com Claude Code e estratégias de teste.

flowchart LR
  A["Implementar com Claude Code"] --> B["Preencher template de PR"]
  B --> C["Limitar diff no CI"]
  C --> D["Adicionar evidências de teste"]
  D --> E["Preparar handoff"]
  E --> F["Rascunhar release notes"]

As fontes oficiais usadas aqui são GitHub Pull Requests, templates de Pull Request, sintaxe de workflows do GitHub Actions, protected branches, secrets no GitHub Actions, Claude Code docs e, se você usa categorias de commit, Conventional Commits.

Defina o padrão em um template de PR

Pedir para Claude Code “escrever uma boa descrição de PR” toda vez gera textos inconsistentes. O caminho mais seguro é colocar o contrato de review em .github/pull_request_template.md. O GitHub pode inserir esse conteúdo automaticamente no corpo do PR, transformando a regra do time em parte do repositório.

## O que mudou
<!-- Separe implementação, configuração, documentação e arquivos gerados. -->

## Por que a mudança é necessária
<!-- Linke issue, incidente, pedido de usuário ou decisão de design. -->

## Foco da revisão
- [ ] Lógica de negócio
- [ ] UI/UX
- [ ] Contrato de API ou banco de dados
- [ ] Segurança e privacidade

## Evidências de teste
- [ ] Testes automáticos:
- [ ] Verificação manual:
- [ ] Screenshots ou gravação:

## Tamanho do diff
- Arquivos alterados:
- Linhas adicionadas/removidas:
- Por que não foi dividido:

## Segurança e operação
- [ ] Não contém secrets, tokens nem dados pessoais
- [ ] Logs não expõem credenciais ou dados pessoais
- [ ] Permissões, variáveis de ambiente e feature flags revisadas
- [ ] Plano de rollback escrito

## Handoff para revisores
<!-- Arquivos para ler primeiro, decisões abertas, riscos e PRs seguintes. -->

Os campos mais importantes são “por que não foi dividido” e “plano de rollback”. Quando ficam vazios, o PR costuma estar grande demais ou pouco preparado para produção. Claude Code ajuda a preencher, mas o template define o que é revisável.

Gere o corpo do PR a partir de fatos

Com o template pronto, peça para Claude Code preencher os campos a partir do diff. O prompt precisa impedir suposições. Se não houver prova de teste, a resposta correta é “não executado”. Se o impacto não estiver no diff ou no contexto passado, deve aparecer como pendente.

git diff origin/main...HEAD | claude -p "
Leia este diff e escreva o corpo do Pull Request usando .github/pull_request_template.md em português.

Regras:
- Não invente fatos que não estejam visíveis no diff
- Se faltar evidência de teste, escreva 'não executado'
- Explique termos técnicos na primeira ocorrência
- Limite o foco de review aos 3 arquivos ou áreas mais importantes
- Verifique secrets, tokens, dados pessoais e logs arriscados
- Termine com itens que uma pessoa ainda precisa confirmar
"

Assim o PR vira um mapa de leitura. O revisor sabe se deve começar pela função de autorização, pela tela alterada ou pelo arquivo de migração, em vez de abrir o branch inteiro sem direção.

Use CI para limitar o tamanho do PR

PR grande reduz profundidade de review. Claude Code pode renomear, formatar, refatorar, testar e documentar em uma única sessão. Isso é útil, mas mistura intenções. Um diff-size budget transforma “parece grande demais” em regra objetiva.

Em um projeto Node, adicione scripts/check-pr-size.mjs. Ele ignora lockfiles e saídas geradas, e conta apenas o que uma pessoa precisa revisar.

#!/usr/bin/env node
import { execFileSync } from "node:child_process";

const [range = "origin/main...HEAD", maxLinesRaw = "700", maxFilesRaw = "35"] =
  process.argv.slice(2);
const maxLines = Number(maxLinesRaw);
const maxFiles = Number(maxFilesRaw);

const ignored = [
  /^package-lock\.json$/,
  /^pnpm-lock\.yaml$/,
  /^yarn\.lock$/,
  /^dist\//,
  /^coverage\//,
];

function numeric(value) {
  const parsed = Number(value);
  return Number.isFinite(parsed) ? parsed : 0;
}

const output = execFileSync("git", ["diff", "--numstat", range], {
  encoding: "utf8",
}).trim();

let files = 0;
let lines = 0;

for (const row of output.split(/\r?\n/).filter(Boolean)) {
  const [added, deleted, file] = row.split("\t");
  if (ignored.some((pattern) => pattern.test(file))) continue;
  files += 1;
  lines += numeric(added) + numeric(deleted);
}

if (files > maxFiles || lines > maxLines) {
  console.error(
    `PR is too large: ${files} files / ${lines} changed lines. ` +
      `Budget is ${maxFiles} files / ${maxLines} lines.`,
  );
  console.error("Split formatting, generated files, and behavior changes into separate PRs.");
  process.exit(1);
}

console.log(`PR size OK: ${files} files / ${lines} changed lines.`);

Depois conecte ao GitHub Actions. Workflows ficam em .github/workflows, e esse job pode virar required status check em uma branch protegida.

name: PR quality

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

permissions:
  contents: read
  pull-requests: read

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install dependencies
        run: npm ci

      - name: Run project checks
        run: |
          npm run lint --if-present
          npm test --if-present

      - name: Enforce PR size budget
        run: node scripts/check-pr-size.mjs "origin/${{ github.base_ref }}...HEAD" 700 35

Os números são política do time. Eu começaria com 700 linhas e 35 arquivos, exigindo justificativa para migrações ou refatorações mecânicas. O objetivo não é proibir PR grande, e sim forçar a explicação.

Deixe evidência de teste reproduzível

“Testes passaram” é pouco. O PR precisa mostrar comandos, resultados, checagens manuais, screenshots quando houver UI e uma lista do que não foi verificado. Claude Code pode formatar a seção, mas não deve afirmar que um comando rodou se ele não rodou.

claude -p "
Prepare a seção de evidências de teste para o Pull Request deste branch.

Formato:
## Testes automáticos
- Comando:
- Resultado:
- Motivo da falha, se houver:

## Verificação manual
- Tela, API ou job verificado:
- Dados de entrada:
- Resultado esperado:
- Resultado real:

## Não verificado
- Itens ainda pendentes:
- Quem deve verificar antes do merge:

Use apenas fatos. Não marque como aprovado um comando não executado.
"

Três casos aparecem muito. PR de UI precisa de screenshots, larguras de tela e acessibilidade. PR de API precisa de compatibilidade, respostas de erro e comportamento de logs. Migração ou batch precisa de dry run, rollback e estimativa de tempo. Essa separação ajuda cada revisor a começar pela sua área.

Faça uma passada de segurança e privacidade

Código gerado com IA pode tocar mais arquivos do que o esperado. Secrets podem aparecer em exemplos, logs, fixtures ou screenshots. GitHub Actions secrets são feitos para valores sensíveis em workflows, mas isso não autoriza imprimir esses valores em logs nem copiá-los no PR.

Revise este diff sob segurança e privacidade.

Checklist:
1. Secrets, tokens, API keys, cookies e session IDs
2. Dados pessoais em logs, fixtures, screenshots ou erros
3. Permissões aplicadas no servidor, não apenas escondidas na UI
4. GitHub Actions permissions amplas demais
5. Erros que expõem caminhos internos ou credenciais
6. Feature flags ou variáveis de ambiente que mudam o rollout

Retorne severidade High/Medium/Low e nomes de arquivos.
Inclua também áreas suspeitas que você não consegue confirmar.

A última linha é proposital. Em segurança, listar incertezas costuma ser melhor do que receber um “sem problemas” rápido demais.

Prepare handoff e respostas de review

Um handoff evita que outro revisor reconstrua toda a conversa. Isso é valioso em times distribuídos, PRs longos e rodízio de revisão. Passe comentários e estatística do diff para Claude Code.

PR_NUMBER=123
{
  gh pr view "$PR_NUMBER" --comments
  gh pr diff "$PR_NUMBER" --stat
} | claude -p "
Escreva uma nota de handoff para revisores deste Pull Request.

Inclua:
- Objetivo em no máximo duas frases
- Até 3 arquivos para ler primeiro
- Comentários de review já atendidos
- Comentários ainda aguardando decisão
- Riscos de CI, teste manual e release

A nota deve ser compreensível em menos de cinco minutos.
"

O mesmo vale para respostas a comentários. “Corrigido” raramente basta. Uma boa resposta diz o que mudou, em qual arquivo, qual teste cobre e por que uma sugestão não foi adotada. Claude Code pode rascunhar; você corta o que for defensivo, especulativo ou longo demais.

Transforme PRs em release notes

Qualidade de PR aparece no release. Se o corpo do PR não vira uma nota compreensível para usuários, provavelmente o impacto não estava bem explicado. Conventional Commits ajuda a agrupar, mas release notes ainda precisam de linguagem humana.

gh pr list --state merged --base main --limit 20 \
  --json number,title,body,mergedAt \
  | claude -p "
Rascunhe release notes a partir destes Pull Requests mergeados.

Seções:
## Novas funcionalidades
## Correções
## Performance
## Documentação
## Mudanças para desenvolvedores

Regras:
- Mantenha números dos PRs
- Resuma mudanças internas
- Destaque breaking changes, migrações e feature flags
- Não invente impacto que não esteja no corpo dos PRs
"

Esse fechamento melhora o começo. Quando autores sabem que o PR alimenta a comunicação de release, tendem a explicar motivação, risco e teste com mais cuidado.

Evite PRs de IA barulhentos

O erro mais comum é ruído. Formatação não solicitada, renomeações amplas, refatorações especulativas, comentários duplicados, texto com tom de marketing e testes não verificados deixam a revisão lenta.

Regras simples ajudam. Separe formatação. Mantenha o diff gerado no menor tamanho útil. Escreva apenas fatos no corpo do PR. Explique por que aceitou uma sugestão de Claude Code. Separe mudanças mecânicas, mudanças de comportamento e testes quando possível.

PR barulhento	PR revisável
“Claude melhorou o módulo”	“Moveu validações de autorização para server/auth.ts”
Formatação e lógica misturadas	PR de formatação separado do PR funcional
“Tudo certo” sem evidência	Comandos, resultados e lacunas listados
Sem foco de review	Arquivos e riscos indicados no início

Encaixe em uma oferta da ClaudeCodeLab

Este fluxo combina com templates, treinamento e consultoria. Um time não precisa apenas de um prompt; precisa de template de PR, regras em CLAUDE.md, gates de CI e hábitos de review. Conecte este artigo a templates CLAUDE.md, regras de handoff de equipe e treinamento ou consultoria.

Implemente em etapas. Semana 1: template de PR. Semana 2: limite de diff. Semana 3: handoff de review. Semana 4: release notes a partir de PRs mergeados. Se tudo chegar de uma vez, o time briga com o processo antes de melhorar a qualidade.

Resultado testado

Testei esse fluxo em um projeto Node pequeno. A combinação de template de PR e limite de tamanho teve o maior impacto. Claude Code sozinho escrevia descrições longas, mas irregulares; o template expôs testes não executados, revisão de segurança, arquivos prioritários e rollback. O orçamento de 700 linhas e 35 arquivos também ajudou a separar formatação de mudança de comportamento antes do pedido de review.

Resumo

Claude Code melhora a qualidade dos Pull Requests quando recebe trilhos claros: template rígido, orçamento de diff em CI, evidência de teste reproduzível, checklist de segurança e privacidade, handoff de review e release notes. O objetivo não é fazer o PR soar melhor, e sim tornar mudanças assistidas por IA fáceis de revisar, verificar e publicar.