Este documento apresenta um processo agnóstico de linguagem, framework, plataforma e ferramenta para lidar com múltiplos problemas, planejar mudanças, implementar com foco e construir um histórico de commits confiável.
O princípio central é:
Registre problemas amplamente, mas implemente estreitamente.
Perceber um problema não obriga a resolvê-lo imediatamente. O objetivo é tirar a descoberta da memória, registrá-la em um sistema confiável e continuar trabalhando em uma unidade pequena, completa e verificável.
Use este ciclo como padrão:
capturar → classificar → priorizar → delimitar → implementar → verificar → commitDepois do commit, escolha a próxima unidade e repita. Evite implementar muitas frentes antes de formar um estado válido do projeto.
Ao encontrar outro bug, melhoria, risco ou dívida técnica durante uma tarefa, registre-o sem interromper desnecessariamente o trabalho atual. Use um issue tracker, backlog, arquivo de notas ou outra fonte única e pesquisável.
Um registro mínimo deve conter:
## Título que descreve o problema
### Contexto
Onde e em qual situação o problema foi observado.
### Impacto
O que acontece se ele não for resolvido.
### Evidência
Erro, comportamento observado, exemplo ou forma de reprodução.
### Possível direção
Uma hipótese de solução, sem tratá-la como decisão definitiva.
### Critérios de aceitação
- resultado observável esperado;
- casos relevantes que precisam funcionar;
- comportamento existente que deve ser preservado.O registro não precisa conter uma solução completa. Ele precisa preservar contexto suficiente para que uma pessoa consiga retomar a investigação sem depender da memória de quem fez a descoberta.
Classifique cada descoberta em relação ao trabalho atual:
Bloqueadores, dependências e partes inseparáveis do comportamento normalmente entram no plano atual. Itens adjacentes, cosméticos e investigações devem ser registrados e priorizados separadamente.
Proximidade no código não significa unidade de responsabilidade. Desconfie da frase “já que estou neste arquivo”.
Considere pelo menos quatro fatores:
Uma ordem comum é:
Essa ordem não é absoluta. Registre o motivo quando o contexto exigir uma prioridade diferente.
Transforme o trabalho em uma sequência de estados válidos. Para cada etapa, pergunte:
Uma etapa que não satisfaz essas condições provavelmente ainda não representa uma unidade entregável.
Planeje preferencialmente em fatias verticais. Uma mudança de comportamento pode exigir contrato, implementação, composição, migração, interface e testes no mesmo passo. O limite correto não é um arquivo ou uma camada: é a menor mudança completa e verificável.
Exemplo de sequência saudável:
Mantenha, sempre que possível, apenas uma unidade funcional em implementação. As demais descobertas permanecem registradas no backlog.
O ciclo recomendado é:
Evite:
Separar mudanças posteriormente é possível, mas aumenta o risco de dependências acidentais, arquivos parcialmente alterados e commits intermediários inválidos.
Um commit atômico não é necessariamente pequeno. Ele é completo e possui uma responsabilidade coerente.
Idealmente, qualquer commit compartilhado deve:
Uma regra prática:
O commit deve ser o menor possível, mas grande o suficiente para deixar o projeto funcionando.
Se um construtor passa a exigir uma dependência, por exemplo, o mesmo commit deve atualizar todos os lugares que constroem esse objeto. Separar a mudança do contrato de sua integração produz commits menores, mas não atômicos.
Separe quando as mudanças:
Mantenha juntas quando:
Commits temporários e incompletos podem ser úteis em uma branch pessoal. Antes de compartilhar ou integrar a branch, reorganize-os para produzir um histórico com estados válidos.
O título deve resumir a mudança de forma direta. O corpo, quando necessário, deve explicar motivação, restrições e consequências, sem apenas repetir o diff.
Um formato possível é Conventional Commits:
Tipos comuns:
feat: adiciona comportamento ou capacidade;fix: corrige comportamento incorreto;refactor: muda a estrutura sem mudar o comportamento esperado;test: altera somente testes;docs: altera somente documentação;chore: manutenção sem mudança funcional relevante;build ou ci: altera build, dependências ou automação.O tipo deve refletir o efeito da mudança, não apenas o tipo de arquivo alterado.
Não use comentários como substitutos de tickets, commits futuros como backlog ou documentação extensa como substituta de testes.
Evite lembretes sem contexto:
Prefira um identificador pesquisável e uma ação concreta:
Um bom TODO informa o que falta, por que não foi resolvido agora e onde o trabalho é acompanhado. Se não houver issue tracker, use um identificador único e registre o mesmo identificador no backlog do projeto.
Use um Architecture Decision Record (ADR) quando uma escolha tiver impacto duradouro, alternativas plausíveis ou consequências não óbvias.
Modelo mínimo:
Um ADR registra por que a arquitetura tomou determinada direção. Ele não deve ser apenas uma descrição da implementação atual.
Quando possível, reproduza um bug com um teste que falha antes de corrigi-lo:
O ticket preserva contexto e impacto. O teste preserva o comportamento esperado e protege contra regressões. Um não substitui o outro.
Para falhas difíceis de automatizar, registre passos de reprodução, ambiente, entradas, resultado atual e resultado esperado.
Execute as verificações relevantes para a área modificada:
Mudanças de alto risco exigem verificação mais ampla. Mudanças puramente documentais não precisam do mesmo conjunto de checks de uma migração de dados.
Verifique o estado de cada commit, não apenas o estado final da branch, quando os commits serão compartilhados individualmente.
Quando houver dúvida, use estas perguntas:
Só se ele bloquear, for uma dependência ou fizer parte inseparável do resultado atual. Caso contrário, registre-o e continue.
Provavelmente sim se precisam ser entregues, testadas e revertidas juntas. Provavelmente não se apenas estão próximas no código.
Sim, se deixa contratos sem consumidores atualizados, testes quebrados ou uma aplicação que não inicia.
Sim, se contém responsabilidades que podem ser verificadas e revertidas independentemente.
Documente o suficiente para preservar contexto, intenção e critérios. Evite registrar apenas fatos óbvios no código ou antecipar detalhes ainda incertos.
Um bom processo não tenta resolver toda descoberta imediatamente. Ele permite capturar tudo sem perder o foco, entregar mudanças completas em sequência e preservar decisões para quem trabalhar no sistema depois.
O objetivo não é produzir o maior número de commits nem o menor diff possível. É construir uma sequência compreensível de estados corretos, verificáveis e reversíveis.
incidentes e perda de dados
→ falhas que bloqueiam entregas
→ bugs de comportamento
→ requisitos planejados
→ dívida técnica com impacto conhecido
→ melhorias cosméticas1. Adicionar uma abstração completa e sua implementação, ainda sem consumidores.
2. Integrá-la a um fluxo completo, atualizando consumidores e testes.
3. Expor um novo comportamento apoiado nesse fluxo.
4. Refatorar estruturas internas sem alterar o comportamento.implementar → integrar → testar → commitalterar muitas áreas → acumular estados incompletos → tentar separar depoistipo(escopo): resumo imperativo
Motivação da mudança e contexto que não são óbvios no código.
Consequências, restrições ou decisões relevantes.TODO: melhorar issoTODO(#142): registrar tentativas de finalização para permitir retry.reproduzir → escrever teste que demonstra a falha → corrigir → verificar[ ] Entendi o problema e o resultado esperado.
[ ] Tenho evidência ou forma de reprodução.
[ ] Identifiquei dependências e consumidores afetados.
[ ] Separei descobertas adjacentes em registros próprios.
[ ] Dividi o trabalho em estados válidos e verificáveis.
[ ] Sei quais checks demonstrarão que cada etapa está correta.[ ] A unidade atual está implementada e integrada.
[ ] Todos os consumidores afetados foram atualizados.
[ ] Os testes e checks relevantes passam.
[ ] O commit contém uma responsabilidade coerente.
[ ] Descobertas não implementadas foram registradas.
[ ] Decisões importantes tiveram sua motivação documentada.[ ] Cada commit representa um estado válido do projeto.
[ ] Commits temporários foram reorganizados, combinados ou renomeados.
[ ] Não há arquivos, credenciais ou alterações locais acidentais.
[ ] As mensagens explicam intenção e motivação.
[ ] O conjunto completo atende aos critérios de aceitação.
[ ] A documentação e os testes refletem o comportamento entregue.# Título da decisão
## Contexto
Qual problema exige uma decisão e quais restrições existem.
## Decisão
O que foi escolhido.
## Alternativas consideradas
Quais opções foram avaliadas e por que não foram escolhidas.
## Consequências
Benefícios, custos, riscos e trabalhos futuros decorrentes da decisão.