Abra o git log de um projeto qualquer e você encontra a arqueologia da pressa: "fix", "ajustes", "agora vai", "final2". Cada uma dessas mensagens era óbvia para quem escreveu, naquele dia. Seis meses depois, é um enigma, exatamente quando alguém precisa entender por que aquela linha mudou, às 2h, durante um incidente.

Commits e PRs são documentação executável da história do projeto: o único registro que nunca fica desatualizado, porque nasce junto com a mudança. Tratá-los bem custa segundos; ignorá-los custa investigações.

Conventional Commits: gramática para máquinas e humanos

O padrão que o mercado consolidou é o Conventional Commits (conventionalcommits.org): um prefixo de tipo, escopo opcional e descrição no imperativo:

feat(checkout): add PIX as payment method
fix(auth): prevent session fixation on login
refactor(orders): extract pricing rules to domain service
chore(deps): bump next from 15.2 to 15.3

feat(api)!: remove deprecated /v1/orders endpoint

O que a gramática compra:

• git log legível por tipo: o que é feature, o que é correção, o que é faxina, num relance.
• Automação de graça: changelog gerado, versão calculada sozinha (o ! marca breaking change: o assunto do próximo artigo, SemVer), e lint de mensagem no CI (commitlint) para o padrão não depender de memória.
• A disciplina escondida: se você não consegue escolher UM tipo para o commit, ele está fazendo coisas demais.

O commit atômico: a regra que muda tudo

A mensagem é a metade visível; a outra metade é o que vai dentro. Commit atômico = uma mudança lógica completa: o fix com seu teste, o refactor sem features escondidas, nunca os dois misturados.

Os dividendos aparecem nas ferramentas que todo mundo subestima:

• git bisect encontra o commit que quebrou por busca binária, em minutos, se cada commit compila e faz uma coisa. Com commits "wip + fix + tudo junto", o bisect aponta um pântano.
• git revert desfaz uma mudança cirurgicamente, se ela vive num commit só. É o rollback de código na menor granularidade.
• git blame responde "por que isso é assim?" com uma mensagem que explica, o ADR de bolso de cada linha.

O PR que respeita o revisor

Já cobrimos a mecânica do review; aqui, o artefato. A descrição de PR que funciona responde três perguntas, nesta ordem:

## Por quê
Clientes PJ não conseguiam concluir compra acima de R$ 5.000 (ticket #482).

## O quê
- valida limite por tipo de cliente no caso de uso, não no controller
- adiciona limite configurável por ambiente

## Como testar
1. logar como PJ, adicionar itens > R$ 5.000, concluir compra
2. suíte: `npm test -- pricing`

O porquê vem primeiro porque é o que o diff não mostra: o link para o ticket, o contexto do incidente, a decisão de negócio. O diff mostra o quê; a descrição existe para o resto. E o corolário de sempre: PR pequeno; descrição de três linhas para um diff de 200 é sinal ótimo.

Como instalar isso num time (sem virar polícia)

1. Automatize o verificável: commitlint + husky rejeitam a mensagem fora do padrão na esteira, sem discussão humana.
2. Template de PR no repositório: as três perguntas já esperando resposta.
3. Squash como rede de segurança: times que preferem liberdade nos commits intermediários usam squash-merge com a mensagem final caprichada: a main fica atômica mesmo que a branch tenha sido caótica.
4. Lidere pelo exemplo no review: elogiar a boa descrição ensina mais que cobrar a ruim.

Instalar essa disciplina (com as automações que a tornam invisível) é parte do nosso serviço de DevOps e Deploy.

Faça o teste agora: rode git log --oneline -20 no seu projeto. A história se conta sozinha? Cole o resultado para a IA da Rabelo Digital, aqui no canto da tela, e ela devolve o diagnóstico. Sem formulário, sem espera.

---

Leia também

• SemVer: o contrato de três números
• GitFlow vs GitHub Flow: o fluxo certo para o seu ritmo