Geração de Mensagem de Commit Git

Gere uma mensagem de commit a partir das alterações atualmente preparadas (git diff --cached). A mensagem deve informar ao leitor "o que mudou e por quê" sem abrir o diff.

Quando Usar

• Use quando o usuário pedir para escrever, gerar ou polir uma mensagem de commit git.
• Use quando as alterações preparadas precisarem de uma mensagem de commit convencional com um corpo focado no "porquê".

Fluxo de Trabalho

1. Analise as alterações: execute git status --short, git diff --cached --stat e git diff --cached para confirmar que há algo preparado. Se a área de staging estiver vazia, use um diff ou descrição de alteração explicitamente fornecido quando disponível e rotule essa evidência; caso contrário, solicite as alterações pretendidas. Não prepare arquivos implicitamente.
2. Escolha um tipo: escolha exatamente um prefixo de tipo com base nas alterações (se um commit misturar tipos, peça ao usuário para dividi-lo):
   • feat: nova funcionalidade
   • fix: correção de bug
   • docs: apenas documentação
   • refactor: refatoração (comportamento inalterado)
   • test: adicionar ou alterar testes
   • chore: build, dependências, misc
3. Escreva o assunto: formate type: English imperative phrase, ≤50 caracteres. Comece com um verbo: "Adicionar…", "Corrigir…", "Remover…", "Unificar…". Proíba assuntos vazios como "atualizar código", "algumas alterações", "corrigir bug".
4. Escreva o corpo (opcional, mas recomendado): 1–3 linhas explicando por quê, não um passo a passo de como. Correções de bugs devem declarar as condições de gatilho; funcionalidades devem descrever a mudança visível para o usuário.
5. Saída: retorne a mensagem no formato solicitado. Se estiver fornecendo um comando shell, cite-o com segurança: o texto do commit contendo $(), crases ou aspas não deve ser executado como código shell. Para uma mensagem multilinha, prefira escrevê-la literalmente em um arquivo temporário e usar git commit -F <message-file>.

Regras

• O assunto é para quem lê rapidamente; o corpo é para o seu "eu" futuro em três meses. Mantenha os dois trabalhos separados.
• Uma alteração que misture uma funcionalidade e uma refatoração deve se tornar dois commits, não um feat que disfarça a bagunça.
• Sem meta-comentários na mensagem ("gerado por IA", etc.) — a mensagem é sobre a alteração, nada mais.

Exemplo Mínimo (executável)

# 1. Look at the changes first
git status --short
git diff --cached --stat

# 2. Suppose the change: added CAPTCHA verification to the login endpoint
# Generated commit:
git commit -m "feat: add CAPTCHA verification to login endpoint" -m "Blocks automated credential stuffing; CAPTCHA valid 5 minutes, account locks 10 minutes after 3 failures."

Outro exemplo (correções de bugs devem declarar as condições de gatilho):

git commit -m "fix: keep order-list filters across pagination" -m "Trigger: filter first, then turn the page. Cause: page turns dropped the query params."

Limitações

• Apenas escreve a mensagem. Preparar, dividir, commitar e enviar continuam sendo decisões do usuário, e a habilidade nunca executa git commit por conta própria.
• O assunto de 50 caracteres e as convenções de modo imperativo são o padrão comum; repositórios com sua própria convenção de commit (Gitmoji, prefixos Jira, substituições de projeto) têm precedência sobre esta habilidade.
• Ela lê o diff preparado, portanto, não pode descrever a intenção que o diff sozinho não mostra. Quando o "porquê" não é inferível, a habilidade pergunta em vez de inventar.
• Alterações geradas ou fornecidas (arquivos de lock, saída minificada) são resumidas coletivamente em vez de listadas linha por linha.

Antí-padrões

• ❌ Escrever uma mensagem para uma área de staging vazia: sem git diff --cached, sem mensagem de commit.
• ❌ chore genérico: rotular toda funcionalidade e correção como chore até que o sistema de tipos não signifique nada.
• ❌ Assuntos de comprimento de romance: feat: add a really useful feature that greatly improves the user experience — o assunto diz o quê, deixe os elogios para o usuário.
• ❌ Corpo como log de implementação: "primeiro alterou a linha 20 de a.py, depois b.py…" — o diff já mostra isso; o corpo explica por quê.