Etiquetando dívida técnica pra ela ser paga de verdade

TL;DR - A dívida técnica era invisível: alguns TODOs no código e muita reclamação. Dei a ela uma label, um tipo e um link entre o código e a issue. Agora ela aparece no planejamento com um custo do lado, e disputa tempo da sprint como qualquer outro trabalho.

Qualquer dev do time sabia dizer quais eram as piores partes do código. Nada disso estava escrito em lugar útil. Tinha comentário TODO sem dono, sem data e sem contexto. Quando eu pedia “tempo pra dívida técnica” no planejamento, não tinha lista pra mostrar nem como dizer quanto aquilo estava custando.

Uma label com tipo

No GitLab criei uma label tech-debt e algumas labels de tipo do lado:

• debt-security: dependência desatualizada com CVE, secret no lugar errado.
• debt-reliability: algo que falha em produção de vez em quando.
• debt-speed: código que deixa toda mudança lenta.
• debt-tooling: build velho, runtime velho, biblioteca velha.

Cada issue também responde duas perguntas na descrição: o que dói hoje, e o que acontece se a gente deixar isso por seis meses. É essa segunda resposta que faz a issue ser priorizada.

Ligando o código à issue

Os TODOs viraram um padrão que o time consegue buscar com grep:

// TECH-DEBT(PAT-1234): retry logic duplicated in three integrations

Comentário sem número de issue não entra. Um grep simples por TECH-DEBT( lista todo atalho conhecido no repo, e cada um aponta para uma issue que explica o porquê. No review, quando aparece um novo sem issue, o revisor pede.

flowchart LR
  Code[Comentário TECH-DEBT no código] --> Issue[Issue com label tech-debt]
  Issue --> Board[Board de dívida por tipo]
  Board --> Sprint[Fatia de cada sprint]
  Sprint --> Done[Corrigido, comentário removido]

De onde sai o tempo

Prefiro uma fatia pequena e constante de toda sprint para dívida do que uma “sprint de dívida” a cada trimestre, que sempre é cancelada quando um cliente pede alguma coisa. O time escolhe do board, começando por segurança e confiabilidade.

O que mudou

As conversas de planejamento ficaram mais fáceis. Em vez de “o código está ruim”, posso mostrar uma issue marcada como reliability com as falhas linkadas. Isso ganha um sim bem mais rápido. A dívida não foi a zero, e não vai. Mas parou de crescer no escuro.