O primeiro bug registrado num projeto novinho em folha deveria ser o número um. Normalmente não é.
A maioria das ferramentas que nasce com um único contador compartilhado continua com ele, porque no começo só existe um projeto e a diferença não aparece. Aí chega o segundo cliente, abre o primeiro projeto, registra o primeiro bug, e ele recebe o número #913. Nada está quebrado. Só parece que a pessoa entrou no prédio de outra pessoa.
Lancei a numeração por projeto no BugDump esta semana, e o raciocínio por trás dela vale além do meu produto. O ID de um bug é uma das poucas partes do seu modelo de dados que as pessoas falam em voz alta, e isso muda o que ele precisa fazer bem.
Quanto custa de verdade um contador global
Ele vaza informação. Um número tirado de uma sequência compartilhada conta a quem o lê, mais ou menos, quanto tráfego o sistema tem no total. Dois bugs registrados com um mês de diferença no seu projeto revelam quantos bugs todos os outros registraram nesse intervalo. É o mesmo tipo de problema dos números de fatura sequenciais, e é por isso que as ferramentas de cobrança pararam de usá-los.
Ele vira ruído. #913 não significa nada para quem olha. Não é o 913º bug de nada que a pessoa consiga ver. O número é grande o bastante para ser difícil de guardar de cabeça e arbitrário o bastante para não dar para conferir se faz sentido.
Ele joga fora um sinal de graça. Quando a numeração é por projeto, o número também é uma contagem aproximada. BD-6 significa que o projeto teve um punhado de bugs. BD-2400 significa outra coisa bem diferente, e você descobre isso sem abrir um dashboard.
Nada disso é fatal. Muitas ferramentas boas usam um contador global por anos. Mas é um pequeno imposto pago em cada ID, para sempre, e a correção é barata.
Por que o prefixo merece o lugar
A numeração por projeto cria um problema novo: os números deixam de ser únicos. A tarefa 42 existe em todos os projetos que você tem.
O caminho na URL já resolve isso, porque ele carrega o projeto. Mas conversa não tem URL. Alguém diz «dá uma olhada no 42» num canal onde se discutem três projetos, e a frase é ambígua de verdade.
Uma chave curta na frente do número resolve isso no único lugar onde a ambiguidade de fato acontece: a conversa entre pessoas. BD-42 não deixa a dúvida que 42 deixa, e custa três caracteres. O Jira acerta nisso há vinte anos, e Linear, Shortcut e Sentry chegaram ao mesmo lugar cada um por conta própria.
A chave deveria ser derivada, não exigida. Pedir para alguém inventar uma chave de projeto no cadastro é um pequeno imposto num momento em que a pessoa está tentando fazer outra coisa. Derive a chave do nome do projeto (Bug Dump vira BD) e deixe as pessoas mudarem depois nas configurações, coisa que a maioria nunca vai fazer.
As três decisões de design que importam
Depois que você se compromete com números por projeto e um prefixo, três perguntas decidem se o resultado vai ser agradável ou irritante.
1. Os números são reaproveitados depois de uma exclusão?
Não. Nunca podem ser.
Se excluir a tarefa mais recente libera o número dela para a próxima, então um link, uma mensagem de commit ou uma thread no Slack que cita BD-9 pode começar a apontar, sem aviso, para outro bug. A falha é silenciosa e aparece com um atraso imprevisível, a pior combinação possível.
Mantenha um contador que só sobe. Buracos na sequência não são defeito; são a prova visível de que as referências antigas ainda significam o que diziam.
2. O prefixo faz parte do endereço ou é decoração?
Esta é a pergunta interessante, e as duas respostas são defensáveis.
Se o prefixo é decoração, BD-42 e 42 são duas grafias do mesmo endereço e as duas abrem a tarefa. Renomear a chave de um projeto então não custa nada: os rótulos se atualizam em todo lugar, os links continuam funcionando, ninguém percebe.
Se o prefixo faz parte do endereço, só o rótulo atual exato funciona. Renomear uma chave quebra todo link que carrega a antiga.
Fiquei com a segunda opção, de propósito, depois de começar pela primeira. O argumento que venceu: uma URL com um prefixo que não é a chave deste projeto é, em qualquer caso realista, um erro. Alguém colou um link do projeto errado, digitou errado ou está seguindo uma referência desatualizada. Abrir qualquer tarefa que por acaso tenha aquele número neste projeto não ajuda. Parece que funcionou e, em silêncio, mostra o bug errado.
Então um prefixo errado recebe um 404, assim como um número com zeros à esquerda, como BD-007, e um número que nenhuma tarefa tem. O número puro continua sendo um endereço permanente que nenhuma renomeação quebra, e é a forma que o produto coloca em todo link, e-mail e payload de webhook que gera.
O custo é real e merece ser dito com todas as letras: renomeie uma chave e os links compartilhados com a antiga param de funcionar. É a troca que você faz para nunca mostrar o bug errado a ninguém.
3. As duas formas funcionam em todo lugar?
Deveriam. As pessoas copiam o rótulo que estão vendo, não aquele que o seu app por acaso usa nos links.
Se a sua interface mostra BD-42 num cartão, então BD-42 colado na barra de endereço tem de funcionar, senão você criou uma pequena armadilha para quem faz o óbvio. Aceite as duas grafias, mantenha a que o visitante usou para chegar e gere você mesmo a canônica.
O que continua sendo número
O prefixo é para pessoas. Máquinas devem continuar recebendo inteiros.
No BugDump, payloads de webhook, respostas da API e argumentos das ferramentas MCP continuam trazendo o número, com o rótulo de exibição ao lado, num campo separado. Nada que já fazia parse de um payload precisou mudar, e ninguém precisa escrever um parser de string para descobrir a que bug um evento se refere.
Vale a pena preservar essa separação de propósito enquanto você constrói. O rótulo é uma questão de apresentação. No momento em que ele vaza para os contratos de integração, renomear a chave de um projeto vira uma mudança incompatível na API, e uma configuração cosmética vira algo em que ninguém ousa mexer.
Migrar sem quebrar o que as pessoas já mandaram
A parte chata de lançar isso é que os IDs já existem e já estão circulando, em e-mails, históricos de chat e tickets de outras pessoas.
Renumerar as tarefas existentes para que todo projeto comece certinho em 1 é tentador e errado. Toda referência antiga passa a apontar para outro lugar sem aviso. A alternativa é mais sem graça e correta: deixe os números existentes como estão, comece o contador de cada projeto acima do maior número dele e deixe os projetos antigos com IDs esparsos para sempre. Projetos novos ganham uma sequência limpa a partir de 1, links antigos continuam significando o que significavam, e ninguém precisa ser avisado de nada.
Numeração é uma funcionalidade pequena. Também é uma que cada pessoa da equipe usa dezenas de vezes por dia, o que é um bom argumento para gastar uma tarde acertando em vez de conviver com #913 indefinidamente.
Leia também
O nome de máquina que também era o nome de exibição — o que aconteceu quando a chave estável das prioridades virou também o valor enviado aos clientes, e o que foi preciso para tornar as prioridades editáveis.
Campos personalizados no bug tracker: o que adicionar e o que evitar — o teste que separa um campo que vale a pena de um que vai estar vazio em seis semanas.
Bug tracker leve para equipes pequenas: quando o Jira é demais — por que os issue trackers pesados não servem para equipes pequenas e o que um processo leve de bugs precisa ter.