Conceitos & Pilares da Manutenção de Software

Os 7 pilares que sustentam a capacidade de um time manter software com saúde. São a base conceitual do framework — o o quê e o porquê. A ordem de implementação está no roadmap-maturidade.md, e como medi-los em metricas.md.

Regra mental: cada pilar responde a uma pergunta. Se você não sabe responder, é aí que está seu maior risco.

Pilar 1 — Visibilidade & Monitoramento

Pergunta: "Eu descubro os problemas antes ou depois do cliente reclamar?"

Definição: Capacidade de enxergar o que acontece no software em produção — logs, métricas, alertas, rastreamento de erros.

Por que importa: Você não conserta o que não vê. Sem visibilidade, toda manutenção é reativa e você opera no escuro. É o pilar mais fundamental — vem antes de tudo.

Sintomas de ausência:

• O cliente avisa que o sistema caiu antes de você saber
• "Funciona na minha máquina" é a resposta padrão
• Diagnosticar um bug leva horas de adivinhação

Primeiras ações práticas:

• Centralizar logs (não ficar catando log em servidor)
• Ferramenta de rastreamento de erros (ex: Sentry ou similar)
• Alertas básicos: sistema fora do ar, taxa de erro, uso de recursos
• Um dashboard mínimo com os sinais vitais do sistema

Pilar 2 — Qualidade Automatizada

Pergunta: "Eu tenho confiança de fazer uma mudança sem quebrar o que já funciona?"

Definição: A rede de segurança que pega problemas antes de chegarem em produção — testes automatizados, CI/CD e code review.

Por que importa: É o maior aliado da manutenção. Sem testes, toda mudança é um risco e o medo de mexer no código paralisa a evolução. CI/CD reduz erro humano; code review espalha conhecimento e pega problemas cedo.

Sintomas de ausência:

• Deploy é um evento tenso, feito "na mão" e de madrugada
• Toda correção gera dois bugs novos
• Ninguém mexe em certos trechos por medo de quebrar

Primeiras ações práticas:

• Testes automatizados começando pelos fluxos críticos (não busque 100% de cara)
• Pipeline de CI que roda os testes a cada mudança
• Deploy automatizado (CD), reproduzível e reversível
• Code review obrigatório antes de mergear

Pilar 3 — Dívida Técnica sob Controle

Pergunta: "Minha dívida técnica é uma escolha consciente ou uma bomba-relógio invisível?"

Definição: Gestão deliberada dos atalhos e imperfeições acumuladas no código. Dívida técnica não é o inimigo — dívida invisível e sem controle é.

Por que importa: Como dívida financeira, ela cobra "juros": cada feature nova fica mais lenta e cara. Se você só entrega features e nunca refatora, o produto apodrece. Regra prática comum: reservar ~20% da capacidade do time para manutenção/melhoria contínua.

Sintomas de ausência:

• A velocidade do time cai a cada trimestre sem explicação
• "Depois a gente arruma" que nunca chega
• Estimativas de tarefas simples explodem

Primeiras ações práticas:

• Tornar a dívida visível: um registro/backlog de dívida técnica
• Reservar capacidade fixa por ciclo (~20%) para pagá-la
• Priorizar dívida por dor real (frequência de contato × risco), não por perfeccionismo
• Aplicar a "regra do escoteiro": deixe o código um pouco melhor do que encontrou

🧩 Template pronto: Registro de Dívida Técnica.

Pilar 4 — Segurança & Dependências

Pergunta: "Uma biblioteca desatualizada ou um fornecedor podem me derrubar amanhã?"

Definição: Manter dependências atualizadas e gerenciar riscos externos — bibliotecas de terceiros, APIs de fornecedores, brechas de segurança.

Por que importa: Versões desatualizadas = brecha de segurança e dívida silenciosa que só cresce. Um fornecedor que muda uma API ou uma tecnologia que fica obsoleta pode virar uma crise se você não tiver um plano.

Sintomas de ausência:

• Dependências travadas em versões antigas há anos ("não dá pra atualizar")
• Nenhum inventário de bibliotecas e suas versões
• Segurança só é lembrada depois de um incidente

Primeiras ações práticas:

• Verificação automática de vulnerabilidades nas dependências (ex: scanners no CI)
• Rotina de atualização incremental (pequena e frequente > big-bang raro e arriscado)
• Nunca hardcodar segredos — usar variáveis de ambiente ou gerenciador de segredos
• Mapear dependências críticas de terceiros e ter um plano B para as mais arriscadas

Pilar 5 — Conhecimento Distribuído

Pergunta: "Se a pessoa-chave sair de férias (ou da empresa) amanhã, o que quebra?"

Definição: Reduzir o bus factor — o número de pessoas que, se sumissem, paralisariam parte do sistema. Feito com documentação mínima viável e compartilhamento de conhecimento.

Por que importa: É o maior risco em time pequeno: uma pessoa só sabe como um sistema funciona. Se ela sai, o software vira uma caixa-preta. Conhecimento concentrado é uma dívida tão perigosa quanto código ruim.

Sintomas de ausência:

• "Só o Fulano mexe nessa parte"
• Zero documentação, ou documentação desatualizada que ninguém confia
• Onboarding de um novo dev leva meses

Primeiras ações práticas:

• Documentação mínima viável: como rodar, como fazer deploy, decisões importantes (ADRs)
• Code review como ferramenta de disseminação de conhecimento (não só de qualidade)
• Rotacionar responsabilidades sobre módulos críticos
• Registrar o "porquê" das decisões, não só o "como" (o como está no código)

🧩 Template pronto: ADR — Architecture Decision Record.

📚 Quando o conhecimento preso já força o suporte a interromper a manutenção a cada dúvida, veja Conhecimento Preso — como extrair regras de negócio sem documentação.

Pilar 6 — Arquitetura Manutenível

Pergunta: "Minha arquitetura facilita ou dificulta a próxima mudança?"

Definição: Escolher estruturas simples, coesas e de baixo acoplamento, priorizando a facilidade de manutenção sobre a sofisticação técnica.

Por que importa: A arquitetura define o custo de toda mudança futura. Numa empresa pequena/média, complexidade desnecessária é o inimigo: um monólito bem feito costuma ser mais fácil de manter do que microsserviços mal feitos.

Sintomas de ausência:

• Uma mudança simples exige tocar em dezenas de arquivos espalhados
• Ninguém consegue explicar como os módulos se relacionam
• Adotou-se uma tecnologia "moderna" que ninguém domina de fato

Primeiras ações práticas:

• Preferir soluções simples e comprovadas às da moda
• Muitos arquivos pequenos e coesos > poucos arquivos gigantes
• Baixo acoplamento entre módulos (mudar um não deve quebrar os outros)
• Ao decidir arquitetura, perguntar: "isso será fácil de manter daqui a 12 meses?"

Pilar 7 — Priorização & Equilíbrio

Pergunta: "Como eu decido, hoje, entre corrigir/manter e construir algo novo?"

Definição: O framework de decisão que resolve o dilema central — manutenção vs. features novas — de forma consciente em vez de reativa.

Por que importa: É o pilar que costura todos os outros. Sem um critério explícito, o time apaga incêndios o dia todo e nunca investe no que evita o próximo incêndio. Este é o trabalho mais estratégico do CTO na manutenção.

Sintomas de ausência:

• Prioridade = "quem grita mais alto" (cliente, vendas, o CEO)
• O time nunca tem tempo para preventiva
• Decisões de trade-off não são registradas nem explicadas

Primeiras ações práticas:

• Avaliar cada item por Impacto × Risco × Esforço
• Reservar capacidade fixa por ciclo para manutenção (~20%) — inegociável
• Separar o urgente (corretiva) do importante (preventiva) e proteger espaço para o importante
• Tornar os trade-offs transparentes para o negócio: mostrar o custo de adiar manutenção

🧩 Template pronto: Matriz de Priorização (Impacto × Risco × Esforço), com exemplo numérico manutenção vs. feature.

🔥 Quando a pressão é extrema e tudo vira urgente, este pilar sozinho não basta — veja Modo Crise.

Resumo dos pilares

➡️ Próximo passo: veja em qual fase de maturidade você está no roadmap-maturidade.md.