Como usar o /caveman-commit para gerar mensagens de commit curtas no padrão Conventional Commits

Fala aí, beleza? Abrir o git log de um projeto e ver quinze linhas seguidas de "ajustes", "update" e "agora vai" é quase esporte nacional

O problema nem é preguiça, é que escrever mensagem boa no fim do dia dá trabalho, e aí todo mundo despacha genérico

O /caveman-commit ataca exatamente esse pedaço do fluxo

Ele faz parte do plugin caveman para Claude Code, mantido por Julius Brussee no repositório JuliusBrussee/caveman sob licença MIT

A ideia é simples: ele lê o diff das suas mudanças e devolve uma mensagem curta no padrão Conventional Commits, com assunto no imperativo e corpo só quando faz sentido ter corpo

Neste post a gente vai ver as três coisas que importam pra usar isso hoje: como instalar, como acionar e o que fazer com a saída

O que você precisa antes de rodar o comando

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

Nada de PC da Nasa aqui, a lista é curta:

• Claude Code instalado e acesso ao terminal, porque a instalação do plugin passa por dois comandos claude plugin
• Um repositório Git com mudanças de verdade, já que a skill trabalha em cima do diff (git diff HEAD ou git diff --cached)
• Noção básica de Conventional Commits, pra você bater o olho na saída e saber se aquele feat ali deveria ser um fix

Se você nunca leu a especificação, dá pra viver sem por enquanto: o essencial é que feat (nova funcionalidade) e fix (correção de bug) são os dois tipos obrigatórios da especificação base, e outros tipos como docs entram por convenção

Como usar o /caveman-commit passo a passo

1. Adicione o marketplace do plugin

claude plugin marketplace add JuliusBrussee/caveman

O erro comum deste passo: pular direto pro install achando que o plugin já está disponível

Ele não está, o marketplace precisa ser registrado antes

2. Instale o plugin caveman

claude plugin install caveman@caveman

Repare no caveman@caveman: é o nome do plugin seguido do marketplace

O erro comum aqui é digitar só caveman e ficar olhando pra tela sem entender por que não achou 😛

3. Deixe as mudanças prontas no repositório

Com staging ou sem staging, os dois cenários funcionam, porque a skill roda git diff HEAD (ou git diff --cached) no caminho do repositório pra obter o diff

O erro comum deste passo: chamar o comando com a árvore limpa

Sem diff, não tem o que descrever, é isso

4. Acione o comando

O gatilho direto é escrever /caveman-commit

Mas ele também dispara em linguagem natural, com pedidos como "write a commit", "commit message", "generate commit" ou "/commit", e ainda dispara quando existem mudanças em staging

O erro comum: achar que precisa decorar a sintaxe exata

Não precisa, pedir a mensagem de commit no meio da conversa já chama a skill

5. Leia a saída antes de aceitar

A resposta vem como bloco de código pronto pra colar, mais ou menos assim:

feat(api): add GET /users/:id/profile

<corpo curto explicando o porquê da mudança>

Closes #128

O erro comum deste passo é aceitar de olhos fechados

A skill descreve o que ela viu no diff, e quem sabe se aquilo é feat ou refactor de verdade é você

6. Cole a mensagem e faça o commit você mesmo

Esse é o maior erro do fluxo inteiro, então vou repetir com carinho: a skill apenas GERA o texto

Ela não roda git commit, não adiciona arquivo nenhum ao staging e não faz amend

Se você mandou o comando e ficou esperando o commit aparecer, ele não vai aparecer

E olha que essa divisão é boa, viu

O histórico é um dos poucos lugares do projeto onde não dá pra desfazer bonito depois, e vale pensar bem antes de deixar o agente commitar sozinho

Em que momento do fluxo chamar o comando (e por que a mensagem curta ajuda o histórico)

A hora certa é aquela janelinha entre "código pronto" e "agora eu escrevo a mensagem"

Nesse ponto o diff já reflete exatamente a mudança, então a skill tem o material completo pra trabalhar

Chamar antes disso é pedir resumo de um trabalho que ainda está pela metade

Agora, o porquê do formato, que é a parte que muita gente ignora

Assunto de no máximo 50 caracteres não é frescura de estilo

É o que mantém o git log legível quando você volta no projeto seis meses depois procurando onde uma coisa quebrou

O corpo entrar só quando o porquê não é óbvio é a regra mais inteligente do conjunto

Commit que renomeia uma variável não precisa de três parágrafos

Commit que muda contrato de API e obriga migração precisa, e MUITO

E tem o lado da especificação, que é onde isso vira ganho prático: feat corresponde a MINOR e fix corresponde a PATCH no versionamento semântico

Ou seja, o tipo que você escolhe na primeira palavra da mensagem carrega informação de versão junto

O escopo, aquele pedaço entre parênteses, é opcional e vem logo depois do tipo, como no exemplo da própria especificação: feat(parser): add ability to parse arrays

Manter isso consistente entre pessoas diferentes do time é o mesmo desafio de padronizar as notas do projeto, e ter uma skill fixando as regras resolve metade da briga

E se um dia você quiser voltar ao estilo verboso de sempre?

Basta pedir "stop caveman-commit" ou "normal mode"

Veja o Claude Code turbinado por plugins na prática

Pra começar do zero na ideia de estender o Claude Code com plugins e comandos próprios, este vídeo do canal mostra o assunto na prática:

Próximo passo depois do primeiro commit gerado

A divisão de responsabilidades do /caveman-commit é o que faz ele funcionar bem: a skill escreve, você commita

Ela lê o diff, aplica o padrão, entrega o bloco pronto e para por aí

O resto continua na sua mão, do jeito que tem que ser quando o assunto é histórico de repositório

Depois que o primeiro commit gerado entrar, vale dar uma passeada no resto do plugin: além do comando de commit, ele traz /caveman (compressão), /caveman ultra, /caveman lite, /caveman-review, /caveman-stats e /caveman-compress

A proposta central de todos eles é a mesma: cortar 65% dos tokens de saída mantendo a precisão técnica, segundo a descrição do próprio repositório

E se você quiser ver as regras completas, sem intermediário, a skill está em skills/caveman-commit/SKILL.md na branch main

Ler o SKILL.md direto na fonte é sempre o melhor caminho pra entender o que a ferramenta faz e o que ela não faz

até o próximo post! 😀