Como pedir ao Claude Code para escrever a mensagem de commit e a descrição do PR

Fala aí, beleza? Commit update files não explica nada pra ninguém, nem pro seu colega, nem pra você daqui a três meses

E o problema quase nunca é o modelo

O Claude Code lê o diff e escreve o que ele consegue ver: arquivos tocados, linhas alteradas, funções renomeadas

Só que o PORQUÊ da mudança não está no diff

O bug que te acordou, o pedido do cliente, a decisão de arquitetura que fez você trocar a abordagem: nada disso aparece no git diff

Se você não entrega esse contexto no pedido, o texto vira uma lista genérica de arquivos, e aí a culpa é do prompt, não da IA =)

Bora montar o pedido do jeito certo?

O que você precisa antes de começar:

A base é simples e você provavelmente já tem

• um repositório com git inicializado
• o Claude Code rodando no diretório do projeto (ele lê a configuração dali)
• para o fluxo de pull request, o GitHub CLI instalado e autenticado com gh auth login

Por que o GitHub CLI? porque o Claude não inventa um PR do nada: ele cria usando o gh pr create (ou glab mr create se o teu projeto vive no GitLab) e depois liga a sessão ao PR gerado

Isso é MUITO útil, e já já te conto o motivo

Tome cuidado: sem o gh instalado e autenticado, o fluxo de PR simplesmente não roda

Aí é só resolver isso antes e seguir o baile

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Passo a passo: o pedido que gera uma mensagem de commit útil

A lógica aqui é a mesma de delegar uma tarefa pra uma pessoa: quanto mais contexto, menos genérico o resultado

1. Deixe o Claude ler o diff antes de escrever

Parece óbvio, mas muita gente pede a mensagem de cabeça, sem mandar ele olhar o que mudou de verdade

Leia o diff das mudanças staged (git diff --staged) e me diga,
em duas frases, o que mudou de fato antes de escrever qualquer
mensagem de commit

O erro comum deste passo: pedir a mensagem antes de dar git add, com o diff vazio

Aí ele escreve baseado no que lembra da conversa, e não no que realmente vai pro commit

2. Diga a motivação, porque ela não está no código

Esse é o passo que separa commit útil de commit decorativo

Contexto: usuários relataram que o filtro de busca zerava ao
trocar de página. A causa era o estado do filtro viver no
componente da lista. Movi pra URL. Escreva a mensagem de commit
explicando o problema e a decisão, não os arquivos

O erro comum deste passo: achar que "corrigi o bug" é motivação

Motivação é QUAL bug, quem reportou, o que quebrava e por que essa solução e não outra

3. Declare a convenção de formato

Se você não diz o formato, ele escolhe um

E aí cada commit sai de um jeito, o que é péssimo pro histórico

O Conventional Commits é uma escolha popular e fácil de declarar:

Use Conventional Commits: tipo, escopo opcional entre colchetes,
dois pontos e a descrição, corpo opcional começando uma linha em
branco depois da descrição, footers opcionais no fim. feat para
funcionalidade nova, fix para correção de bug. Se for mudança
quebrada, sinalize com ! depois do tipo/escopo ou com o footer
BREAKING CHANGE

O resultado fica mais ou menos assim:

fix(busca): manter filtro ao paginar

O estado do filtro vivia no componente da lista e era descartado
a cada troca de página. Movido para a URL, o que também deixa o
resultado compartilhável por link

O erro comum deste passo: colar a convenção uma vez no chat e esperar que ela valha pra sempre

Enquanto ela não estiver escrita no projeto, você repete o pedido toda sessão (na última seção a gente resolve isso)

4. Delimite o escopo: diga o que NÃO entra

Esse é o passo que quase ninguém faz, e é o que mais enxuga o texto

Não liste arquivos, não descreva renomeações mecânicas, não
mencione ajustes de formatação e não escreva mais que 5 linhas
no corpo

O erro comum deste passo: pedir "seja conciso"

Conciso é vago

Proibir explicitamente o que você não quer ver funciona MUITO melhor, e essa lógica de restrição explícita é a mesma que vale quando você vai escrever uma especificação para o Claude Code seguir de ponta a ponta

5. Peça pra revisar antes de commitar

Me mostre a mensagem final antes de rodar o commit, não commite
ainda

O erro comum deste passo: deixar ele commitar direto e só descobrir a bobagem depois de dar push

O histórico do git é público pro time, beleza? Reescrever depois é chato

Passo a passo: a descrição do PR que o revisor consegue ler

A mensagem de commit é pro histórico

A descrição do PR é pra uma PESSOA que vai revisar teu código hoje, com pouca paciência e várias abas abertas

São públicos diferentes, então o pedido também muda

1. Peça resumo por intenção, não por arquivo

Escreva a descrição do PR organizada por intenção: o que o
usuário ganha, qual problema isso resolve e qual decisão técnica
foi tomada. Nada de seção listando arquivos alterados, o próprio
GitHub já mostra isso

O erro comum deste passo: aceitar aquele bullet point por arquivo

É ruído: o diff já está ali do lado

2. Peça a seção de como testar

Inclua uma seção "Como testar" com passos numerados que o revisor
consiga seguir na máquina dele, incluindo o estado inicial
necessário

O erro comum deste passo: escrever "rode os testes"

O revisor quer reproduzir o comportamento, não só ver verde no CI

3. Peça os riscos e pontos de atenção

Esse é o pedido que mais salva revisor, e quase ninguém faz

Aponte riscos, efeitos colaterais possíveis e pontos que merecem
atenção do revisor nesta mudança

O erro comum deste passo: não perguntar

Se você não pede, ele escreve um PR otimista, todo bonitinho, sem nenhum alerta

4. Revise o PR gerado antes de enviar

Parece óbvio, mas não é firula

Você é quem assina a mudança no fim das contas

O erro comum deste passo: confiar no texto porque ele está bem formatado

Texto bem formatado e texto correto são coisas diferentes

5. Volte à sessão que gerou o PR quando o review chegar

Se liga nisso, que é bem massa: como o Claude Code liga a sessão ao PR criado, dá pra voltar pro contexto original depois

claude --from-pr 1234

Isso abre o seletor de sessões filtrado pelas sessões ligadas àquele PR

E se você não lembra o número, dá pra colar a URL do PR na busca do /resume

O erro comum deste passo: abrir uma sessão nova pra responder o review

Aí você perde todo o raciocínio que gerou aquela mudança e explica tudo de novo

Como transformar o pedido em padrão do projeto

Repetir a mesma instrução toda sessão é sinal de que ela deveria estar escrita em algum lugar

E está tudo bem: o Claude Code tem lugar próprio pra isso

1. Gere o CLAUDE.md com /init

O /init cria um CLAUDE.md inicial na raiz do projeto

Esse arquivo é carregado no começo de CADA sessão, e é o lugar de padrões de código, decisões de arquitetura e checklists de review

Ou seja: é exatamente onde as tuas três regras de commit devem morar

2. Refine com /memory

O /memory lista os arquivos de memória (CLAUDE.md, CLAUDE.local.md) por escopo de usuário e de projeto, e abre o que você escolher no editor

Use pra ir lapidando a convenção conforme o time reclama do que saiu torto

3. Empacote o pedido como comando ou skill

Se o teu pedido de commit já virou um textão, transforme ele em comando

Comandos de projeto ficam em .claude/commands/ e comandos pessoais em ~/.claude/commands/

O nome do arquivo .md (sem a extensão) vira o nome do comando, e o frontmatter YAML é opcional:

---
description: Escreve a mensagem de commit no padrão do projeto
model: claude-sonnet-4-5
allowed-tools: Bash(git diff:*), Bash(git status:*)
---

Leia o diff staged, pergunte a motivação se eu não tiver dado,
e escreva a mensagem em Conventional Commits sem listar arquivos

Hoje o formato recomendado pra empacotar é a skill

Um arquivo em .claude/commands/deploy.md e uma skill em .claude/skills/deploy/SKILL.md criam exatamente o mesmo /deploy

A diferença é o que a skill ganha por cima: pasta de arquivos de apoio, controle de quem invoca pelo frontmatter e carregamento automático pelo Claude quando o assunto é relevante

É o mesmo raciocínio de quando você monta uma skill com regras que o modelo segue de verdade: regra escrita em arquivo vale mais que regra dita no chat

4. Versione o que é do time, separe o que é seu

O Claude Code lê CLAUDE.md, settings.json, hooks, skills, commands, subagents e memória automática tanto do diretório do projeto quanto de ~/.claude

Os arquivos do projeto podem ir pro git e passam a valer pro time inteiro

Os de ~/.claude são pessoais e te seguem em todos os projetos

O erro comum deste passo: jogar preferência pessoal no CLAUDE.md do repositório e implicar com o time depois haha

Atalhos prontos e ajustes que valem a pena

Se você não quer escrever tudo do zero, tem caminho pronto

Plugin oficial de commit. A Anthropic mantém o plugin commit-commands no repositório oficial do Claude Code, na pasta plugins/commit-commands, que fornece /commit, /commit-push-pr e /clean_gone

A instalação sai pelo marketplace oficial:

/plugin install commit-commands@claude-plugins-official

O marketplace claude-plugins-official é registrado automaticamente na primeira execução interativa do Claude Code

Caso isso falhe, dá pra adicionar na mão:

/plugin marketplace add anthropics/claude-plugins-official

O catálogo também fica em claude.com/plugins e na aba Discover do /plugin

A assinatura no commit. Por padrão os commits saem com trailers de git como Co-Authored-By, e muita gente não curte isso no histórico

Dá pra customizar ou remover pelo setting attribution, que tem os campos commit e pr:

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <[email protected]>",
    "pr": ""
  }
}

String vazia esconde a atribuição

E se liga: o attribution tem precedência sobre o includeCoAuthoredBy, que está depreciado

Conectar o repositório. Rodando /install-github-app dentro do Claude Code, no repositório que você quer conectar, ele te guia pelos passos

Sobre review automático: o Code Review da Anthropic no GitHub analisa pull requests e publica os achados como comentários inline nas linhas de código, mas está em research preview e disponível pras assinaturas Team e Enterprise

Então vale conferir teu plano antes de criar expectativa

Conclusão

A qualidade do texto acompanha a qualidade do contexto que você entrega, sempre

O diff conta o QUE mudou

A motivação, a convenção e o escopo só chegam se você disser, e é aí que a mensagem de commit no Claude Code para de ser lista de arquivo e vira registro de decisão

Próximo passo bem concreto pra hoje: abra o CLAUDE.md do teu projeto e escreva três regras de commit (formato, o que sempre incluir, o que nunca incluir)

Depois testa no próximo PR e vê a diferença

faça o teste! 😀

até o próximo post!