7 min leitura • Guide 286 of 877
Documentação de Dívida Técnica
Dívida técnica se acumula silenciosamente, desacelerando desenvolvimento até que equipes não possam ignorá-la. Documentação torna a dívida visível, quantificável e acionável. Dívida bem documentada permite trade-offs informados entre pagá-la e entregar features.
Elementos de Documentação
| Elemento | Propósito | Exemplo |
|---|---|---|
| Descrição | O que é a dívida | Sistema de auth legado |
| Localização | Onde vive | /src/auth/*.js |
| Impacto | Como prejudica | +2h por feature |
| Custo | Esforço para corrigir | 3 sprints |
| Risco | O que pode acontecer | Brecha de segurança |
Formato de Documentação de Dívida
Template Padrão
TEMPLATE DE ITEM DE DÍVIDA TÉCNICA
══════════════════════════════════
TÍTULO:
─────────────────────────────────────
Nome claro e conciso
"Sistema de autenticação legado"
"Suite de testes monolítica"
"Respostas de API inconsistentes"
DESCRIÇÃO:
─────────────────────────────────────
O que é a dívida?
Por que ela existe?
Quando foi introduzida?
Exemplo:
"Autenticação foi construída rapidamente para MVP.
Usa versão desatualizada de bcrypt, sem OAuth,
gerenciamento de sessão é customizado.
Introduzido: 2021 Q2, 3 desenvolvedores atrás."
LOCALIZAÇÃO:
─────────────────────────────────────
Quais arquivos/serviços/módulos?
├── /src/auth/
├── /src/middleware/session.js
├── /src/controllers/login.js
├── Relacionado: /tests/auth/*.test.js
└── Linhas afetadas: ~2000
IMPACTO:
─────────────────────────────────────
Como nos desacelera?
├── Novas features de auth levam +2 dias
├── Onboarding: 1 semana para entender
├── Reviews de segurança apontam sempre
├── CI roda 15 min a mais
└── Quantifique onde possível
CUSTO PARA CORRIGIR:
─────────────────────────────────────
O que a remediação levaria?
├── Esforço estimado: 3 sprints
├── Membros da equipe: 2 desenvolvedores
├── Externo: Review de segurança R$25K
├── Risco durante migração: Médio
└── Downtime: 2 horas planejadas
RISCO SE IGNORADO:
─────────────────────────────────────
O que pode dar errado?
├── Segurança: Exploração de vulnerabilidade
├── Escalabilidade: Não vai aguentar crescimento
├── Equipe: Desenvolvedor-chave sai
├── Negócio: Vazamento de dados de clientes
└── Severidade: Alta / Média / Baixa
RECOMENDAÇÃO DE PRIORIDADE:
─────────────────────────────────────
├── Urgência: Abordar nos próximos 2 trimestres
├── Comparar com outros itens de dívida
├── Considerar timing estratégico
└── Próximos passos: Incluir no planejamento Q3
Categorizando Dívida
Tipos de Dívida
CATEGORIAS DE DÍVIDA TÉCNICA
════════════════════════════
QUALIDADE DE CÓDIGO:
─────────────────────────────────────
├── Código duplicado
├── Funções complexas
├── Nomeação ruim
├── Abstrações faltando
├── Padrões inconsistentes
└── Corrigir: Sprints de refatoração
ARQUITETURA:
─────────────────────────────────────
├── Monolito precisando decomposição
├── Escolha errada de tecnologia
├── Limites de serviço faltando
├── Limitações de escalabilidade
├── Acoplamento forte
└── Corrigir: Iniciativas maiores
TESTES:
─────────────────────────────────────
├── Cobertura insuficiente
├── Testes lentos
├── Testes frágeis (flaky)
├── Sem testes de integração
├── Testes manuais onde deveria automatizar
└── Corrigir: Investimento gradual
INFRAESTRUTURA:
─────────────────────────────────────
├── Dependências desatualizadas
├── Ferramentas legadas
├── Processos manuais
├── Preocupações de segurança
└── Corrigir: Manutenção regular
DOCUMENTAÇÃO:
─────────────────────────────────────
├── Docs faltando
├── Informação desatualizada
├── Conhecimento tribal
├── Dor no onboarding
└── Corrigir: Frequentemente negligenciado
Medindo Impacto
Quantificando Dívida
MÉTRICAS DE IMPACTO:
┌─────────────────────────────────────────────────────────────┐
│ │
│ TEMPO PERDIDO: │
│ │
│ "Quanto tempo a mais uma tarefa leva por causa desta │
│ dívida?" │
│ │
│ Exemplo: │
│ Adicionar feature de auth: 5 dias → 8 dias (+60%) │
│ Por sprint: ~3 dias perdidos em média │
│ Por trimestre: ~18 dias perdidos │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ BUGS E INCIDENTES: │
│ │
│ "Quantos bugs são causados por esta dívida?" │
│ │
│ Bugs em área de auth no último trimestre: 12 │
│ Incidentes de produção relacionados: 2 │
│ Tempo médio de resolução: 4 horas │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ IMPACTO EM ONBOARDING: │
│ │
│ "Quanto tempo a mais novos devs levam por causa disso?" │
│ │
│ Tempo para entender módulo: 1 semana extra │
│ Perguntas frequentes sobre: Sim, toda semana │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ RISCO DE NEGÓCIO: │
│ │
│ Probabilidade de incidente de segurança: Alta │
│ Impacto se ocorrer: Crítico (dados de clientes) │
│ Compliance em risco: LGPD, PCI-DSS │
└─────────────────────────────────────────────────────────────┘
Documentando no GitScrum
Rastreando Dívida como Tarefas
DÍVIDA NO GITSCRUM:
┌─────────────────────────────────────────────────────────────┐
│ │
│ EPIC: Dívida Técnica │
│ ├── DEBT-001: Migrar sistema de autenticação │
│ ├── DEBT-002: Refatorar módulo de pagamentos │
│ ├── DEBT-003: Atualizar dependências frontend │
│ ├── DEBT-004: Melhorar cobertura de testes │
│ └── DEBT-005: Documentar API interna │
│ │
│ EXEMPLO DE TAREFA: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ DEBT-001: Migrar sistema de autenticação ││
│ │ ││
│ │ TIPO: Tech Debt ││
│ │ PRIORIDADE: Alta ││
│ │ ESTIMATIVA: 21 pts (3 sprints parciais) ││
│ │ ││
│ │ IMPACTO: ││
│ │ • +3 dias por feature de auth ││
│ │ • 2 incidentes de segurança no ano ││
│ │ • Bloqueia implementação de SSO ││
│ │ ││
│ │ LOCALIZAÇÃO: ││
│ │ /src/auth/*, /src/middleware/session.js ││
│ │ ││
│ │ TAGS: #tech-debt #security #high-impact ││
│ └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
Revisão Periódica
Mantendo Documentação Atualizada
PROCESSO DE REVISÃO:
┌─────────────────────────────────────────────────────────────┐
│ │
│ TRIMESTRAL: │
│ │
│ ☐ Revisar todos os itens de dívida documentados │
│ ☐ Atualizar estimativas de impacto │
│ ☐ Remover itens resolvidos │
│ ☐ Adicionar novos itens identificados │
│ ☐ Re-priorizar baseado em mudanças │
│ ☐ Comunicar status para stakeholders │
│ │
│ PERGUNTAS A FAZER: │
│ │
│ 1. Este item ainda é relevante? │
│ 2. O impacto mudou? │
│ 3. O custo de corrigir mudou? │
│ 4. O risco aumentou ou diminuiu? │
│ 5. Devemos priorizar diferente? │
│ │
│ APÓS RETROSPECTIVA: │
│ │
│ • Revisar se nova dívida foi criada │
│ • Documentar dívida identificada pela equipe │
│ • Atualizar itens existentes com novos insights │
└─────────────────────────────────────────────────────────────┘
Comunicando Dívida
Para Stakeholders
COMUNICAÇÃO DE DÍVIDA TÉCNICA:
┌─────────────────────────────────────────────────────────────┐
│ │
│ DASHBOARD DE DÍVIDA: │
│ │
│ Total de itens documentados: 23 │
│ ├── Críticos: 3 │
│ ├── Altos: 7 │
│ ├── Médios: 8 │
│ └── Baixos: 5 │
│ │
│ Impacto estimado: │
│ ~15% do tempo de desenvolvimento perdido │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ MENSAGEM PARA LIDERANÇA: │
│ │
│ "Temos 3 itens de dívida técnica críticos que │
│ impactam significativamente nossa velocidade. │
│ │
│ Se não abordarmos nos próximos 2 trimestres: │
│ • Risco de incidente de segurança aumenta │
│ • Features de auth levarão 60% mais tempo │
│ • Compliance pode ser comprometido │
│ │
│ Recomendação: Alocar 20% do próximo trimestre │
│ para remediar os 3 itens críticos." │
└─────────────────────────────────────────────────────────────┘