Skill de Commit
Prepare e commit alterações seguindo o estilo de commit convencional e princípios de commit atômico.
Formato da Mensagem de Commit
<tipo>(<escopo opcional>): <sumário curto>
- Minúsculas em tudo — tipo, escopo e sumário
- Sem ponto final no sumário
- Modo imperativo — "adicione recurso" não "adicionou recurso" ou "adiciona recurso"
- Máximo de 50 caracteres para a linha de sumário (limite flexível, 72 limite rígido)
- O sumário descreve o porquê, não o quê (o diff mostra o quê)
Tipos
| Tipo | Quando usar | Exemplo |
|---|---|---|
feat | Novo recurso ou capacidade | feat: adicionar fluxo de autenticação do usuário |
fix | Correção de bug | fix: resolver ponteiro nulo em entrada vazia |
refactor | Mudança no código que não corrige bug nem adiciona funcionalidade | refactor: extrair analisador para módulo independente |
style | Formatação, espaços em branco, ponto e vírgula — sem mudança de lógica | style: aplicar formatador a arquivos de configuração |
docs | Apenas documentação | docs: adicionar exemplos de uso da API ao readme |
test | Adicionar ou atualizar testes | test: adicionar cobertura de caso extremo para validador |
chore | Processo de build, ferramentas, dependências, configuração | chore: atualizar arquivo de dependências |
perf | Melhoria de desempenho | perf: armazenar em cache consultas repetidas ao banco |
ci | Mudanças em pipeline CI/CD | ci: adicionar etapa de lint ao workflow de PR |
Escopo (Opcional)
Use o escopo para restringir o contexto quando o tipo sozinho for ambíguo. Derive escopos da estrutura de diretórios do projeto ou áreas de domínio:
feat(auth): adicionar renovação de token OAuth2
fix(api): tratar tempo limite em payloads grandes
docs(contributing): adicionar instruções de configuração
Fluxo de Trabalho
- Revisar alterações — Execute
git statusegit diff(preparado + não preparado) para entender o que mudou - Verificar histórico recente — Execute
git log --oneline -10para corresponder ao estilo de commit existente do projeto - Verificar intenção — Confirme se as alterações formam uma única unidade lógica; caso contrário, sugira dividir em vários commits
- Executar verificações de CI — Antes de preparar, execute linters, formatadores e suíte de testes do projeto para detectar problemas cedo. Verifique scripts em
package.json,Makefileou configuração de CI para comandos disponíveis. Corrija quaisquer falhas antes de prosseguir. - Preparar arquivos — Adicione arquivos específicos pelo nome (
git add arquivo1 arquivo2), nuncagit add -Aougit add . - Criar mensagem — Selecione o tipo correto, adicione escopo se útil, escreva um sumário imperativo
- Comitar — Use um heredoc para a mensagem para garantir formatação limpa
- Verificar — Execute
git statusapós para confirmar que o commit foi bem-sucedido
Commits Multi-linha
Para commits que precisam de corpo (raro — prefira mensagens concisas de uma linha):
<tipo>(<escopo>): <sumário>
<corpo explicando o porquê, não o quê>
- Linha em branco entre sumário e corpo
- Corpo quebra em 72 caracteres
- Use corpo apenas quando o sumário sozinho não puder transmitir o raciocínio
Regras
- Commits atômicos — Uma mudança lógica por commit. Um recurso e seus testes podem ser um commit. Uma correção de formatação não relacionada deve ser um commit separado.
- Sem segredos — Nunca commitar
.env, credenciais, chaves de API ou tokens. Avise o usuário se estes estiverem preparados. - Sem artefatos gerados — Não commitar saída de build, diretórios de dependências ou arquivos compilados. Verifique a cobertura do
.gitignoreantes de preparar. - Apenas novos commits — Sempre crie um novo commit. Nunca altere a menos que o usuário peça explicitamente.
- Sem pular hooks — Nunca use
--no-verify. Se um hook falhar, corrija o problema subjacente. - Linha de co-autor — Anexe a linha de co-autoria quando Claude tiver escrito ou co-escrito as alterações:
Co-authored-by: Claude <[email protected]>
Exemplos
# Recurso — nova capacidade
feat: adicionar sistema de notificação webhook
# Recurso com escopo
feat(api): adicionar middleware de limitação de taxa
# Correção — correção de bug
fix: impedir falha em entrada JSON malformada
# Estilo — apenas formatação
style: aplicar indentação consistente entre módulos
# Docs — documentação
docs: adicionar registros de decisão de arquitetura
# Chore — ferramentas/configuração
chore: ampliar gitignore para cobrir artefatos de build
# Teste com escopo
test(auth): adicionar testes de integração para renovação de token
# Refatoração com escopo
refactor(db): substituir consultas brutas por query builder
Documentação de Referência
- conventional-commits.md — guia de seleção de tipo, mudanças que quebram compatibilidade, estratégias de escopo, decisões de commit com múltiplos arquivos, formatação de corpo, trailers e erros comuns