186 lines
9.6 KiB
Markdown
186 lines
9.6 KiB
Markdown
## Tech Debt
|
||
|
||
Analisa quantitativamente a dívida técnica do projeto e visualiza as pontuações de saúde junto com o impacto na eficiência de desenvolvimento. Acompanha melhorias mediante análise de tendências, calcula custos temporais e cria um plano de melhoria priorizado.
|
||
|
||
### Uso
|
||
|
||
```bash
|
||
# Verificar configuração do projeto para analisar dívida técnica
|
||
ls -la
|
||
"Analisar a dívida técnica deste projeto e criar um plano de melhoria"
|
||
```
|
||
|
||
### Painel de Saúde do Projeto
|
||
|
||
```text
|
||
Pontuação de Saúde do Projeto: 72/100
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
|
||
📊 Pontuações por Categoria
|
||
├─ Frescor das dependências: ████████░░ 82% (Atualizadas: 45/55)
|
||
├─ Completude da documentação: ███░░░░░░░ 35% (Faltam README, docs API)
|
||
├─ Cobertura de testes: ██████░░░░ 65% (Meta: 80%)
|
||
├─ Segurança: ███████░░░ 78% (Vulnerabilidades: 2 Medium)
|
||
├─ Arquitetura: ██████░░░░ 60% (Dependências circulares: 3 lugares)
|
||
└─ Qualidade do código: ███████░░░ 70% (Complexidade alta: 12 arquivos)
|
||
|
||
📈 Tendências (últimos 30 dias)
|
||
├─ Pontuação geral: 68 → 72 (+4) ↗️
|
||
├─ Itens melhorados: 12 ✅
|
||
├─ Nova dívida: 3 ⚠️
|
||
├─ Dívida resolvida: 8 🎉
|
||
└─ Velocidade de melhoria: +0.13/dia
|
||
|
||
⏱️ Impacto temporal da dívida
|
||
├─ Desaceleração do desenvolvimento: -20% (desenvolvimento de novas funcionalidades leva 1.25x o tempo normal)
|
||
├─ Tempo de correção de bugs: +15% (tempo médio de correção 2h → 2.3h)
|
||
├─ Revisão de código: +30% (tempo adicional por complexidade)
|
||
├─ Onboarding: +50% (tempo necessário para novos membros entenderem)
|
||
└─ Tempo de atraso acumulado: Equivalente a 40 horas/semana
|
||
|
||
🎯 Efeitos esperados da melhoria (baseados em tempo)
|
||
├─ Efeito imediato: Velocidade de desenvolvimento +10% (após 1 semana)
|
||
├─ Efeito a curto prazo: Taxa de bugs -25% (após 1 mês)
|
||
├─ Efeito a médio prazo: Velocidade de desenvolvimento +30% (após 3 meses)
|
||
├─ Efeito a longo prazo: Tempo de manutenção -50% (após 6 meses)
|
||
└─ ROI: Investimento 40 horas → Recuperação 120 horas (3 meses)
|
||
```
|
||
|
||
### Exemplos Básicos
|
||
|
||
```bash
|
||
# Análise detalhada da pontuação de saúde
|
||
find . -name "*.js" -o -name "*.ts" | xargs wc -l | sort -rn | head -10
|
||
"Calcular a pontuação de saúde do projeto e avaliar por categorias"
|
||
|
||
# Análise de impacto de dívida de TODO/FIXME
|
||
grep -r "TODO\|FIXME\|HACK\|XXX\|WORKAROUND" . --exclude-dir=node_modules --exclude-dir=.git
|
||
"Avaliar estes TODOs por impacto de dívida (tempo×importância)"
|
||
|
||
# Verificação de saúde das dependências
|
||
ls -la | grep -E "package.json|Cargo.toml|pubspec.yaml|go.mod|requirements.txt"
|
||
"Calcular pontuação de frescor das dependências e analisar riscos e efeitos de atualizações"
|
||
```
|
||
|
||
### Colaboração com Claude
|
||
|
||
```bash
|
||
# Análise integral de dívida técnica
|
||
ls -la && find . -name "*.md" -maxdepth 2 -exec head -20 {} \;
|
||
"Analisar a dívida técnica deste projeto sob essas perspectivas:
|
||
1. Qualidade do código (complexidade, duplicação, manutenibilidade)
|
||
2. Saúde das dependências
|
||
3. Riscos de segurança
|
||
4. Problemas de desempenho
|
||
5. Falta de cobertura de testes"
|
||
|
||
# Análise de dívida arquitetural
|
||
find . -type d -name "src" -o -name "lib" -o -name "app" | head -10 | xargs ls -la
|
||
"Identificar dívida técnica no nível arquitetural e propor um plano de refatoração"
|
||
|
||
# Plano de melhoria priorizado
|
||
"Avaliar a dívida técnica segundo esses critérios e apresentar em formato de tabela:
|
||
- Impacto (Alto/Médio/Baixo)
|
||
- Custo de correção (tempo)
|
||
- Risco técnico (possibilidade de falha do sistema, perda de dados)
|
||
- Efeito de redução de tempo por melhoria
|
||
- Momento recomendado de implementação"
|
||
```
|
||
|
||
### Exemplos Detalhados
|
||
|
||
```bash
|
||
# Detecção automática do tipo de projeto e análise
|
||
find . -maxdepth 2 -type f \( -name "package.json" -o -name "Cargo.toml" -o -name "pubspec.yaml" -o -name "go.mod" -o -name "pom.xml" \)
|
||
"Baseado no tipo de projeto detectado, analisar:
|
||
1. Dívida técnica específica da linguagem/framework
|
||
2. Desvios das melhores práticas
|
||
3. Oportunidades de modernização
|
||
4. Estratégia de melhoria gradual"
|
||
|
||
# Análise de métricas de qualidade do código
|
||
find . -type f -name "*" | grep -E "\.(js|ts|py|rs|go|dart|kotlin|swift|java)$" | wc -l
|
||
"Analisar a qualidade do código do projeto e apresentar essas métricas:
|
||
- Funções com alta complexidade ciclomática
|
||
- Detecção de código duplicado
|
||
- Arquivos/funções muito longos
|
||
- Falta de tratamento de erro adequado"
|
||
|
||
# Detecção de dívida de segurança
|
||
grep -r "password\|secret\|key\|token" . --exclude-dir=.git --exclude-dir=node_modules | grep -v ".env.example"
|
||
"Detectar dívida técnica relacionada à segurança e propor prioridade de correção e contramedidas"
|
||
|
||
# Análise de falta de testes
|
||
find . -type f \( -name "*test*" -o -name "*spec*" \) | wc -l && find . -type f -name "*.md" | xargs grep -l "test"
|
||
"Analisar a dívida técnica de cobertura de testes e propor estratégia de testes"
|
||
```
|
||
|
||
### Matriz de Prioridades da Dívida
|
||
|
||
```text
|
||
Prioridade = (Impacto × Frequência) ÷ Custo de correção
|
||
```
|
||
|
||
| Prioridade | Impacto no desenvolvimento | Custo de correção | Efeito de redução de tempo | Retorno do investimento | Prazo de resposta |
|
||
| -------------------------- | -------------------------- | ----------------- | -------------------------- | ----------------------------- | ------------------ |
|
||
| **[P0] Resposta imediata** | Alto | Baixo | > 5x | Investimento 1h→Redução 5h+ | Imediato |
|
||
| **[P1] Esta semana** | Alto | Médio | 2-5x | Investimento 1h→Redução 2-5h | Dentro de 1 semana |
|
||
| **[P2] Este mês** | Baixo | Alto | 1-2x | Investimento 1h→Redução 1-2h | Dentro de 1 mês |
|
||
| **[P3] Este trimestre** | Baixo | Baixo | < 1x | Investimento=tempo de redução | Dentro de 3 meses |
|
||
|
||
### Critérios de Avaliação por Tipo de Dívida
|
||
|
||
| Tipo de dívida | Método de detecção | Impacto no desenvolvimento | Tempo de correção |
|
||
| --------------------------------- | ----------------------------------------- | --------------------------------------------------- | ----------------- |
|
||
| **Dívida arquitetural** | Dependências circulares, alto acoplamento | Grande escopo de impacto em mudanças, teste difícil | 40-80h |
|
||
| **Dívida de segurança** | Scan CVE, OWASP | Risco de vulnerabilidades, conformidade | 8-40h |
|
||
| **Dívida de desempenho** | N+1, vazamentos de memória | Aumento tempo de resposta, consumo de recursos | 16-40h |
|
||
| **Dívida de testes** | Cobertura < 60% | Detecção tardia de bugs, qualidade instável | 20-60h |
|
||
| **Dívida de documentação** | Falta README, docs API | Tempo de onboarding aumentado | 8-24h |
|
||
| **Dívida de dependências** | Não atualizadas por 2+ anos | Risco de segurança, problemas de compatibilidade | 4-16h |
|
||
| **Dívida de qualidade do código** | Complexidade > 10 | Tempo de compreensão/correção aumentado | 2-8h |
|
||
|
||
### Cálculo de Impacto da Dívida Técnica
|
||
|
||
```text
|
||
Impacto = Σ(peso de cada elemento × valor medido)
|
||
|
||
📊 Indicadores de impacto mensuráveis:
|
||
├─ Impacto na velocidade de desenvolvimento
|
||
│ ├─ Tempo de compreensão do código: +X% (proporcional à complexidade)
|
||
│ ├─ Escopo de impacto em mudanças: Y arquivos (medido por acoplamento)
|
||
│ └─ Tempo de execução de testes: Z minutos (pipeline CI/CD)
|
||
│
|
||
├─ Impacto na qualidade
|
||
│ ├─ Taxa de ocorrência de bugs: +25% a cada 10 de complexidade
|
||
│ ├─ Tempo de revisão: linhas de código × coeficiente de complexidade
|
||
│ └─ Risco por falta de testes: Alto risco se cobertura < 60%
|
||
│
|
||
└─ Impacto na eficiência da equipe
|
||
├─ Tempo de onboarding: +100% por falta de documentação
|
||
├─ Concentração de conhecimento: Atenção necessária se taxa de contribuidor único >80%
|
||
└─ Locais de correção por duplicação de código: taxa de duplicação × frequência de mudança
|
||
```
|
||
|
||
### Cálculo de ROI baseado em tempo
|
||
|
||
```text
|
||
ROI = (tempo reduzido - tempo de investimento) ÷ tempo de investimento × 100
|
||
|
||
Exemplo: Resolução de dependências circulares
|
||
├─ Tempo de investimento: 16 horas (refatoração)
|
||
├─ Efeito de redução (mensal):
|
||
│ ├─ Tempo de compilação: -10 min/dia × 20 dias = 200 min
|
||
│ ├─ Tempo de debugging: -2 horas/semana × 4 semanas = 8 horas
|
||
│ └─ Adição de novas funcionalidades: -30% redução de tempo = 12 horas
|
||
├─ Tempo de redução mensal: 23.3 horas
|
||
└─ ROI em 3 meses: (70 - 16) ÷ 16 × 100 = 337%
|
||
```
|
||
|
||
### Notas
|
||
|
||
- Auto-detecta a linguagem e framework do projeto para realizar análises específicas
|
||
- Avalia a pontuação de saúde em escala de 0-100 pontos, considerando saudável 70+ pontos e necessitando melhoria <50 pontos
|
||
- Calcula custos temporais e efeitos de melhoria de forma específica, apoiando tomada de decisão baseada em dados
|
||
- Para conversão monetária, especificar separadamente o salário médio por hora da equipe ou coeficientes específicos do projeto
|