jksim/agent-skills-jksim

Higiene de Commits

Visão Geral

Regra 4 das regras de Jarrett: uma mudança tem apenas os commits que ela logicamente necessita. Um revisor lê um único commit limpo para cada mudança, não um histórico de tentativas. Comentários são curtos.

O hook commit-check avisa quando uma mensagem de git commit ultrapassa os limites. Ele não bloqueia. Você corrige o commit.

Quando Usar

• Antes de cada commit.
• Antes de cada push.
• Quando você fez mais de um commit para corrigir um único problema.
• Quando o hook commit-check avisa.

Processo

1. Escreva a mensagem

• Assunto: 72 caracteres ou menos. Use o imperativo: "Adiciona hook de regras", não "Adicionado hook de regras".
• Corpo: 5 linhas ou menos. Omita-o quando o assunto for suficiente.
• Diga o que mudou e por quê. Não descreva cada arquivo.
• Use inglês simplificado. Veja a habilidade simplified-english.

2. Faça um commit para cada mudança lógica

• Uma mudança lógica: uma fatia de funcionalidade, uma correção ou uma refatoração que um revisor possa aceitar ou rejeitar como uma unidade.
• Não misture uma refatoração e uma alteração de comportamento em um mesmo commit.
• Não faça commit de cada tentativa. Faça commit quando a mudança funcionar e os testes passarem.

3. Achate commits de ajuste antes do push

Um commit de ajuste corrige um commit anterior na mesma mudança. Exemplos: "corrige digitação", "wip", "atende revisão".

1. Faça o commit de ajuste com git commit --fixup <sha>.
2. Achate-o sem editor: GIT_SEQUENCE_EDITOR=: git rebase -i --autosquash <base>.
3. Se o rebase parar em um conflito, corrija os arquivos e execute git add <arquivos>. Execute GIT_EDITOR=true git rebase --continue. Para parar, execute git rebase --abort.
4. Execute os testes novamente.
5. Verifique o resultado: git log --oneline <base>..HEAD.

Se o último commit for o que precisa ser corrigido, use git commit --amend --no-edit.

Aviso: não reescreva commits que já estão em um branch compartilhado. Pergunte ao usuário primeiro. Uma reescrita força cada colega de equipe a redefinir o branch.

4. Mantenha comentários curtos

• Escreva um comentário apenas quando o código não estiver claro.
• Uma linha geralmente é suficiente. Diga o porquê, não o quê.
• Não escreva histórico de alterações em comentários. O Git mantém o histórico.

Racionalizações Comuns

Racionalização	Realidade
"Commits pequenos mostram meu progresso."	O revisor precisa do resultado, não do caminho. Ache as tentativas.
"Uma mensagem longa dá mais contexto."	Mensagens longas não são lidas. Coloque o contexto na especificação ou no PR.
"Vou achar depois."	Depois é após o push. Ache antes do push.
"O hook só avisa, então o limite é opcional."	O limite é uma regra da equipe. O hook avisa para que você possa corrigir.

Bandeiras Vermelhas

• git log mostra "wip", "corrige", "ops" ou "tenta de novo" antes do push.
• Mais de um commit para uma única correção de bug.
• Um corpo de commit que lista cada arquivo alterado.
• Comentários que repetem o que o código diz.

Verificação

• Cada assunto tem 72 caracteres ou menos e usa o imperativo.
• Cada corpo tem 5 linhas ou menos.
• git log --oneline <base>..HEAD mostra um commit para cada mudança lógica.
• Nenhum commit de ajuste foi deixado antes do push.
• Testes passam após qualquer rebase.

Limite conhecido: o hook não verifica git -C <dir> commit ou git -c <key>=<value> commit. Ele também ignora algumas mensagens que não consegue ler, por exemplo -F <arquivo>.