Renan Montanari Blog
Voltar ao blog
DocumentaçãoArquitetura

Conhecimento Que Mora Numa Pessoa Só

Quando só uma pessoa sabe como o sistema funciona, férias viram risco. Três textos curtos que tiram o conhecimento da cabeça dela: como subir o ambiente, o que fazer quando algo falha e por que as decisões estranhas foram tomadas.

Renan Montanari

Renan Montanari

Engenheiro de Software Full-Stack

6 min de leitura

Introdução: O Sistema Que Depende de Uma Memória

Tem uma pessoa no seu time que sabe por que aquela integração foi feita daquele jeito. Sabe qual é a senha do servidor antigo. Sabe o que fazer quando o processo da madrugada falha.

Ela nunca escreveu nada disso. E não é culpa dela. Ninguém pediu, e sempre foi mais rápido perguntar.

Três Situações Comuns, Nenhuma Dramática

O problema aparece quando essa pessoa:

  • tira férias;
  • fica doente;
  • recebe uma proposta melhor.

A partir daí, tarefa simples vira arqueologia. Ninguém sabe onde fica a configuração, qual versão está em produção ou por que aquele campo existe. O sistema que funcionava entra em modo de não mexer em nada até ela voltar.

Isso se chama, em gestão de engenharia, bus factor: quantas pessoas precisam estar disponíveis para o trabalho não parar. Quando o número é um, o conhecimento está em uma pessoa só, independentemente do talento dela.

O Que Resolve: Três Textos Curtos

A solução não é documentação de cem páginas. Essa ninguém escreve e ninguém lê. O que funciona são três textos curtos, cada um com uma pergunta clara.

1. Como subir o ambiente do zero

Alguém novo, ou você mesmo num computador novo, deveria conseguir rodar o sistema seguindo um roteiro. Esse texto responde:

  • quais ferramentas e versões são necessárias;
  • quais variáveis de ambiente existem, e onde seus valores são obtidos (sem colar o valor no documento);
  • quais comandos sobem o banco, rodam as migrações e iniciam a aplicação;
  • como validar que está tudo funcionando.

Se o roteiro não funciona na primeira tentativa, ele está incompleto. Um bom teste é pedir para alguém que nunca viu o projeto seguir o texto sozinho.

2. O que fazer quando cada coisa crítica falha

Para cada parte que, se parar, afeta o negócio, o texto responde:

  • sintoma: como o problema aparece (alerta, cliente reclamando, fila crescendo);
  • verificação: o que olhar primeiro, e em qual painel ou log;
  • ação: o que fazer para estabilizar, incluindo reiniciar, reverter ou desligar algo;
  • quem avisar: a quem comunicar e em que prazo.

Esse é o texto que mais economiza madrugada. Ele transforma uma falha em um procedimento, em vez de uma aposta sobre quem está acordado.

3. Por que as decisões estranhas foram tomadas

Todo sistema tem decisões que parecem erradas para quem chega. Um campo duplicado, uma fila que não era necessária, uma integração feita de forma manual. Sem explicação, a tendência é “corrigir”, e a correção pode quebrar algo que existia por um motivo real.

Uma forma simples de registrar isso é o ADR (Architecture Decision Record), um texto curto com estrutura fixa:

# ADR-012: Integração de notas fiscais via fila

## Contexto
A emissora fiscal responde em até 40 segundos e, em horários de pico,
recusa requisições síncronas com erro 503.

## Decisão
Emitir notas por fila, com reprocessamento automático em caso de falha.

## Consequências
- Cliente vê o status "em processamento" em vez de uma resposta imediata.
- Falhas da emissora não derrubam o checkout.
- Exige monitorar o tamanho da fila.

## Alternativas consideradas
- Chamada síncrona com retry: descartada, causava timeout no checkout.

Repare que o ADR não precisa ser longo. Ele responde a pergunta mais difícil de responder depois: por que foi assim, e o que mudaria essa decisão.

Trade-offs: Documentar Também Envelhece

Documentação tem custo, e ela pode mentir com o tempo. Alguns cuidados:

  • Escreva perto do código. Roteiro de ambiente no próprio repositório envelhece junto com o projeto. Wiki isolada tende a ficar para trás.
  • Atualize como parte da mudança. Se uma decisão mudou, o ADR novo substitui o antigo, em vez de o antigo ser apagado. O histórico também é informação.
  • Não guarde segredos no documento. O texto deve dizer onde a senha fica e quem tem acesso, nunca o valor. Isso conversa com o que falamos sobre credenciais.
  • Não tente documentar tudo. Comece pelo que quebra o negócio se faltar. O resto pode ser descoberto com calma.

Checklist: Seu Sistema Sobrevive a Uma Ausência?

  • Existe um roteiro para subir o ambiente do zero que funciona para alguém de fora?
  • Cada parte crítica tem um procedimento de falha escrito?
  • As decisões que parecem estranhas têm registro do motivo?
  • Dá para saber quem tem acesso a cada sistema sem perguntar para uma pessoa só?
  • Alguém do time já seguiu o roteiro de falha em um exercício, e não só em teoria?

Se a maioria estiver sem resposta, o conhecimento ainda mora em uma pessoa, e não no sistema.

Conclusão: Um Teste Simples

Se a pessoa que mais entende do seu sistema sumisse por um mês, o que travaria primeiro?

A resposta costuma apontar exatamente onde escrever. Comece por esse ponto. Três textos curtos, bem escritos, valem mais do que um manual que ninguém abre.

Gostou? Compartilhe