Pull request bonito é o que alguém lê até o fim

Escrito e revisado por Jefferson Oliveira. Os templates vêm do post original de 2024; a skill é a proposta desta revisão.

Em junho de 2024 eu publiquei um guia de templates de pull request: um modelo pra cada tipo de mudança, com título, problema, solução, referências, screenshots e notas. A ideia era simples. Quem revisa precisa entender o que mudou antes de abrir o diff.

Dois anos depois, a descrição do PR quase sempre sai de uma IA. E o problema inverteu. Antes faltava contexto. Hoje chega uma descrição gigante, com seção pra tudo, que dá preguiça de ler. Quem revisa pula direto pro diff e a descrição vira enfeite.

Quem lê um PR é uma pessoa com pouco tempo, entre uma tarefa e outra. Ela quer saber três coisas: o que mudou, por quê, e como conferir. Tudo que não responde a uma dessas perguntas atrasa a revisão.

Essa parte do post original continua valendo. Os tipos vêm do Conventional Commits, e cada um pede uma coisa. Fix: qual era o problema e como ficou. Feat: o que dá pra fazer agora e como testar. Refactor: por que mexer e a garantia de que o comportamento não mudou. Chore: o que foi atualizado e por quê. Style: o que foi reformatado, e só.

Jefferson Oliveira // onde eu errei

Relendo os exemplos de 2024: quatro dos cinco templates terminam em “Notas Adicionais: Nenhuma.”. Uma seção que quase sempre fica vazia não ajuda quem revisa, só ocupa espaço. Ela saiu do template.

Screenshot continua obrigatório quando a mudança é visual. Em front responsivo, uma imagem por resolução testada, como eu já pedia em 2024. É a parte que a IA não escreve por você.

Juntei os cinco templates num só. O GitHub lê o arquivo pull_request_template.md na raiz do repositório, em docs/ ou em .github/, e preenche o corpo de todo PR novo com ele.

1<!-- Título: tipo: o que muda. ID da tarefa na frente, se houver -->23## Por quê4<!-- O problema ou a necessidade, em 1 a 3 frases -->56## O que mudou7<!-- Só o que o diff não deixa óbvio -->89## Como testar101.1112## Screenshots13<!-- Só se for visual. Antes e depois. -->1415Closes #

Jefferson Oliveira // o detalhe que eu gosto

O ID da tarefa no começo do título eu mantenho até hoje, quando o time usa Jira ou outro quadro que gera ID. Está nas minhas instruções de commit: “ABC-123 feat: add payment validation”. Quem chega pelo quadro acha o PR, e quem chega pelo PR acha a tarefa. Sem quadro, o título começa direto pelo tipo.

A IA tem o diff inteiro e nenhum critério de corte. Então descreve tudo: cada arquivo, cada função renomeada, uma seção de impacto, outra de riscos, outra de próximos passos. Parece completo. Na prática, ninguém lê, e o que importava fica enterrado no meio.

Jefferson Oliveira // na prática

O que mais chega pra mim hoje são documentações gigantes de PR geradas por IA. Dá preguiça de ler, e preguiça de ler vira aprovação sem ler. Descrição curta tem mais chance de ser lida inteira.

A saída não é parar de usar IA pra isso. É dar a ela as regras que a gente usaria: o que cortar, o tamanho máximo, a ordem das seções.

Skill é um arquivo de instruções que o agente carrega quando a tarefa bate com a descrição dela. No Claude Code fica em .claude/skills/<nome>/SKILL.md. Se skill é novidade pra você, escrevi um post curto sobre como elas funcionam. Esta é a que eu sugiro pra descrição de PR:

1---2name: pr-description3description: Escreve título e descrição de pull request.4  Use ao abrir um PR ou quando pedirem "descreve esse PR".5---67Leia o diff da branch contra a base e a tarefa ligada.89Título: `tipo: o que muda`, até 72 caracteres. Se o time10usa Jira ou similar, ID na frente: `ABC-123 fix: ...`.11Tipo do Conventional Commits: fix, feat, refactor,12chore ou style.1314Corpo, nesta ordem, cortando a seção que ficar vazia:15- Por quê: 1 a 3 frases. O problema, não a solução.16- O que mudou: até 5 itens. Só o que o diff não mostra.17- Como testar: passos numerados que alguém consegue18  repetir.19- Screenshots: se a mudança for visual, peça ao autor20  o antes e o depois. Nunca invente.21- Closes #ID quando houver issue.2223Regras:24- Escreva pra uma pessoa que tem 2 minutos.25- Lista de arquivos alterados fica de fora: o diff mostra.26- Seção sem conteúdo real (riscos, notas) fica de fora.27- Passou de 15 linhas? Corte antes de entregar.2829Entrega: pergunte como a pessoa quer receber.30- Criar o PR direto, se o gh estiver instalado e logado.31- Mostrar o título e o corpo no chat, prontos pra copiar.32- Salvar num .md em uma pasta temporária e devolver o33  caminho do arquivo.34Sem gh, ofereça só as duas últimas.

A regra das 15 linhas é a que mais trabalha. Um limite obriga o agente a escolher o que importa, e escolher é justamente o que ele não faz sozinho.

A skill também não depende do GitHub. Sem o gh, ou se você preferir revisar antes, ela devolve o markdown no chat ou num arquivo temporário, e você cola onde abre o PR: GitLab, Bitbucket, Azure DevOps. Quem abre o PR lê, corta o que sobrou e assina. Se você não leria aquela descrição como revisor, não mande.

O exemplo de correção do post original, no formato novo:

1STU-132 fix: corrige erro 500 no login com senha errada23## Por quê4O login retornava erro 500 ao receber credenciais5incorretas. Apareceu nos testes de integração.67## O que mudou8- Tratamento de erro do backend ajustado9- Mensagens de erro mais descritivas10- Validações a mais no frontend1112## Como testar131. Abra o login e envie uma senha errada142. A tela mostra a mensagem de erro, sem 5001516Closes #123

1. [1] Google Engineering Practices: Writing good CL descriptions (abre em nova aba) google.github.io/eng-practices/review/developer/cl-descriptions.html copiar link da referência 1copiado
2. [2] GitHub Docs: Linking a pull request to an issue (abre em nova aba) docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue copiar link da referência 2copiado
3. [3] GitHub Docs: Creating a pull request template (abre em nova aba) docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository copiar link da referência 3copiado
4. [4] Claude Code Docs: Skills (abre em nova aba) code.claude.com/docs/en/skills copiar link da referência 4copiado

Fontes conferidas em out 2026.

// quem escreveu

Jefferson Oliveira

AI Engineer · Studio Visual (abre em nova aba) · São Paulo, SP

Trabalho há mais de 5 anos com PHP, Laravel e WordPress, construindo e-commerces, integrações e sistemas internos. Hoje lidero a adoção de IA na Studio Visual (abre em nova aba) e curso MBA em Engenharia de Software na FIAP.

• MBA em Engenharia de Software · FIAP (cursando)
• Análise e Desenvolvimento de Sistemas · FATEC Zona Leste
• Liderança e Gestão de Equipes · FGV
• PHP: Desenvolvimento Web e POO · 4Linux

Conheça minha trajetória → LinkedIn ↗ (abre em nova aba) GitHub ↗ (abre em nova aba)