Como deixar o Claude Code escrever a mensagem de commit e o changelog do projeto

O commit é o único texto do seu projeto que ninguém vai editar depois

Post de blog tu corrige, README tu reescreve, mas a mensagem que já foi pro remoto vira registro permanente e fica lá, sendo lida por alguém daqui a dois anos tentando entender porque aquela linha mudou

E o Claude Code é uma ferramenta de codificação agêntica que roda no terminal e resolve fluxos de git a partir de linguagem natural, então escrever a mensagem de commit e o changelog é, sim, uma tarefa de escrita técnica delegável

Com duas condições: ele precisa receber o material certo, e o que sai precisa passar por revisão antes de virar histórico

Esse post é dividido exatamente nessas duas metades: que contexto entregar pro agente, e o que conferir antes de publicar 🙂

O que você precisa antes de começar

Nada de mágica aqui, só o básico no lugar:

• Um repositório git com mudanças reais para descrever: mudança inventada gera mensagem inventada, sempre
• Claude Code instalado e rodando no terminal, no diretório do projeto
• Uma convenção escolhida E escrita: o Conventional Commits 1.0.0 para o formato do assunto, o Keep a Changelog 1.1.0 para o arquivo de mudanças e o formato clássico do Pro Git para a mecânica da mensagem: resumo em uma linha de no máximo cerca de 50 caracteres, linha em branco obrigatória, corpo quebrado em cerca de 72 caracteres e verbo no imperativo ("Fix bug", não "Fixed bug")
• Uma decisão sobre permissões de git, tomada antes e não no susto: uma regra Bash(git commit ) libera o comando, e o exemplo oficial de permissões usa ask justamente para Bash(git push )

Escolher a convenção é o item que mais gente pula, e é o que mais dói depois

Sem convenção escrita, o agente escreve no estilo genérico dele e tu vai passar o resto da vida corrigindo no code review

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Que contexto dar ao Claude Code para a mensagem de commit sair útil

A regra que resume tudo: o agente escreve bem o que ele consegue ler

Então o trabalho é entregar leitura, nesta ordem:

1. O diff das mudanças

É o material mínimo, o que efetivamente mudou nos arquivos

Só que diff sozinho responde uma pergunta só: o QUE mudou

2. O motivo da mudança

Aqui mora a diferença entre uma mensagem útil e um resumo automático

O porquê não está no código: o bug que o suporte relatou, a decisão de produto que derrubou aquele campo, a issue que pediu, o comportamento que quebrava em produção

Escreva isso no pedido, em uma ou duas frases, do jeito que tu explicaria pro colega do lado

O erro comum deste passo: pedir a mensagem entregando só o diff e depois reclamar que veio um resumo do diff

Ele não adivinhou o motivo porque o motivo nunca entrou na conversa 😛

3. A convenção do projeto escrita no CLAUDE.md da raiz

O Claude Code lê os arquivos CLAUDE.md no início de cada sessão, o de projeto na raiz do repositório e o global em ~/.claude/, e esse conteúdo entra na janela de contexto logo na largada

Então é ali que mora a sua convenção: tipo permitido, limite do assunto, imperativo, o que vai no corpo

## Convenção de commit deste repo

- Conventional Commits: feat, fix, refactor, docs, chore
- Assunto no imperativo, até ~50 caracteres
- Linha em branco antes do corpo, corpo quebrado em ~72
- O corpo explica o PORQUÊ, não repete o diff
- BREAKING CHANGE sempre declarado explicitamente

O erro comum deste passo: editar o CLAUDE.md no meio da sessão achando que passa a valer ali mesmo

Não passa

O arquivo da raiz é lido uma vez no início da sessão e mantido em memória, e ele só é relido do disco e reinjetado depois do /compact

Mudou a convenção? Ou tu roda um /compact pra ele voltar do disco ainda na mesma sessão, ou abre sessão nova

4. O histórico do projeto como amostra de estilo

Commits anteriores são o melhor exemplo de "é assim que se escreve aqui"

Se o teu repo já tem um padrão bom, aponte pra ele no pedido e mande seguir a mesma pegada

E trate isso como algo que tu pede explicitamente, não como algo que acontece por osmose

Como rodar o fluxo: plugin oficial, permissões e atribuição

Dá pra fazer tudo conversando em linguagem natural, mas existe caminho pronto e mantido pela própria Anthropic

1. Adicione o marketplace oficial de plugins

/plugin marketplace add anthropics/claude-code

2. Abra o gerenciador e instale o commit-commands

/plugin

O gerenciador abre com as abas Discover e Installed: é pela Discover que tu navega e instala

O plugin commit-commands vive no repositório anthropics/claude-code e traz três comandos:

• /commit: revisa as mudanças, faz stage, cria o commit com a mensagem e mostra o status
• /commit-push-pr: commit, push e abre o PR
• /clean_gone: limpa os branches marcados como gone

3. Ou monte o seu próprio comando

Se a tua convenção é específica demais, um comando caseiro resolve

Comandos slash personalizados são arquivos markdown em .claude/commands/ (projeto) ou ~/.claude/commands/ (pessoal), só que esse formato hoje é considerado legado

O recomendado atualmente é .claude/skills/<nome>/SKILL.md, que também é invocável por /nome

Mesma ideia de sempre: tu escreve ali o passo a passo que faria na mão e para de repetir o mesmo prompt toda vez

4. Resolva a atribuição ANTES do primeiro commit

Por padrão o Claude Code adiciona o trailer Co-Authored-By: Claude <[email protected]> nos commits e uma linha de atribuição nas descrições dos PRs que ele abre

Se a política do teu repo não aceita isso, a chave attribution do settings.json controla commit e PR separadamente, e strings vazias escondem tudo:

{
  "attribution": {
    "commit": "",
    "pr": "",
    "sessionUrl": false
  }
}

O attribution tem precedência sobre a configuração antiga includeCoAuthoredBy, que está deprecada

E o attribution.sessionUrl em false omite o link da sessão claude.ai em commits e PRs criados em sessões web e de Remote Control

Colocou em ~/.claude/settings.json? Vale pros teus projetos todos, que é o que a maioria quer

O erro comum deste passo: descobrir a linha de atribuição só depois que o commit já foi pro remoto

Aí não tem settings.json que conserte, tem reescrita de histórico, e ninguém merece isso numa manhã de segunda

Se o teu interesse é afinar o texto que sai (assunto, corpo e também a descrição do PR), esse ajuste é de prompt e de convenção, não de configuração

Como gerar o changelog a partir dos commits

Changelog não é git log formatado bonito

O Keep a Changelog 1.1.0 parte de um princípio bem direto: changelog é escrito por humanos e para humanos

Então o fluxo é este:

1. Defina a fonte com precisão

O intervalo da versão: quais commits e quais diffs entram

Fonte frouxa ("resume as últimas mudanças aí") gera changelog frouxo, e frouxo aqui significa item que não existe no código

2. Peça o agrupamento nos seis tipos do padrão

Added, Changed, Deprecated, Removed, Fixed e Security

São esses seis, não invente categoria nova porque ficou bonitinho

3. Mande traduzir cada item para o leitor final

O commit fala pro time, o changelog fala pra quem usa

"refactor: extrai validação para service" não vira item de changelog, vira nada

Já "corrige erro ao salvar cadastro com e-mail em maiúsculas" é o tipo de linha que alguém lê e entende

4. Amarre com o versionamento

O Conventional Commits define o mapeamento com SemVer: fix é PATCH, feat é MINOR e BREAKING CHANGE em qualquer tipo é MAJOR

Os outros tipos (build, chore, ci, docs, style, refactor, perf, test) são permitidos, mas não têm efeito implícito na versão

Isso é ouro pro changelog: o tipo do commit já sinaliza o peso da mudança

O erro comum deste passo: aceitar entrada de changelog para commit interno que não muda absolutamente nada pra quem usa o produto

Bump de dependência, ajuste de lint, rename de variável: isso fica no histórico do git e só

Checklist: o que revisar antes do commit virar registro permanente

Revisão aqui é ritual, não opcional

São trinta segundos que separam um histórico útil de um monte de ruído:

1. Formato: o assunto cabe em cerca de 50 caracteres, está no imperativo, tem linha em branco antes do corpo e o corpo está quebrado em cerca de 72
2. Conteúdo do corpo: ele explica o PORQUÊ e não fica narrando o diff em português
3. Tipo correto: o tipo do Conventional Commits corresponde à mudança real, sem marcar feat o que é refactor, e atenção redobrada no BREAKING CHANGE porque ele vira MAJOR
4. Nada inventado: número de issue, nome de pessoa, comportamento que o diff não comprova… se não dá pra provar pelo código, sai da mensagem
5. Escopo do stage: o que foi pro stage confere com o que a mensagem descreve
6. Nada sensível: token, caminho interno, nome de cliente, detalhe de vulnerabilidade que ainda não foi corrigida
7. Atribuição: conforme a política do repositório, decidida no passo anterior e não no impulso

O erro comum: revisar a mensagem com lupa e esquecer completamente de revisar o que entrou no stage

Mensagem impecável descrevendo três arquivos, commit levando sete

Já vi essa cena mais de uma vez e ela sempre custa caro

Problemas comuns e como evitar

Mensagem genérica que só narra o diff

Sintoma: sai "atualiza componente de login e ajusta validação", que é literalmente o que qualquer um veria abrindo o diff

Causa: o pedido não tinha motivo, só material

Solução: reescreva o pedido incluindo o porquê em uma frase e peça a mensagem de novo

Como prevenir: coloque no CLAUDE.md que o corpo do commit deve responder "por que", e acostume a mandar o motivo junto do pedido

Changelog com item que não existe no código

Sintoma: linha bonita no changelog descrevendo uma melhoria que ninguém implementou

Causa: fonte frouxa, intervalo mal definido, pedido genérico

Solução: peça que cada item cite o commit de origem, e apague o que não tiver origem

Como prevenir: rastreabilidade item a item vira parte do formato, não um favor

Commit disparado antes de você conferir

Sintoma: tu ia ler a mensagem e ela já estava commitada

Causa: permissão liberada demais pro comando de git

Solução e prevenção: use ask em vez de allow nas regras que importam

"allow": ["Bash(npm run *)"],
"ask": ["Bash(git push *)"],
"deny": ["Read(./.env)"]

Pra quem quer trava mais dura, dá pra usar um hook PreToolUse com o campo if em Bash(git commit *), escopando o hook só aos commits

Esses hooks disparam ANTES da checagem de modo de permissão, e um permissionDecision de deny bloqueia a chamada mesmo em bypassPermissions

Ou seja: é o cinto de segurança que continua funcionando no dia em que tu resolveu correr

Convenção ignorada do nada

Sintoma: tu escreveu a convenção e ele seguiu outra

Causa: o CLAUDE.md foi editado no meio da sessão

Solução: rode um /compact pra ele reler o arquivo do disco, ou abra sessão nova

Como prevenir: lembre que o arquivo da raiz é lido uma vez no início e só volta do disco depois do /compact

Quando delegar compensa e quando escrever você mesmo

Veredito honesto, cenário por cenário:

A regra de bolso é essa: o agente escreve bem o que o repositório consegue provar

O resto continua sendo trabalho humano, e tudo bem

Se a dúvida é mais ampla, do tipo até onde vale soltar o agente no Git, a resposta passa pelo mesmo critério de prova

Próximo passo

Delegar a escrita do commit e do changelog funciona quando o contexto é explícito e a revisão é ritual

Contexto explícito: diff, motivo, convenção escrita e amostra de estilo

Revisão ritual: o checklist rodando sempre, inclusive no commit pequeno, principalmente no commit pequeno

O próximo passo concreto é bem direto: escreva a convenção de commit e de changelog no CLAUDE.md da raiz do repo, instale o commit-commands pelo /plugin e rode o fluxo no teu próximo commit de verdade, passando pelo checklist antes de confirmar

Depois de uns dez commits assim o histórico do projeto muda de cara, e aí não tem volta 😀

até o próximo post!