# Sem documentação não significa sem evidência.

> Dá para assumir e evoluir um sistema sem documentação?

Um plano seguro para assumir software existente, reconstruir contexto, proteger fluxos críticos e evoluir por etapas sem prometer uma reescrita cega.

Canonical HTML: [https://yuriqueiroz.com.br/artigos/assumir-sistema-sem-documentacao](https://yuriqueiroz.com.br/artigos/assumir-sistema-sem-documentacao)

Sim, dá para assumir e evoluir um sistema sem documentação — **desde que o primeiro trabalho seja recuperar evidência, reproduzir o ambiente e limitar mudanças até entender os fluxos críticos**. Sem esse diagnóstico, prazo fechado e reescrita imediata são promessas frágeis.

Documentação ausente aumenta a incerteza, mas o sistema deixa outros rastros: código, configuração, banco, integrações, logs, testes, histórico de versão e conhecimento de quem opera.

## Critérios para decidir

### Existe acesso suficiente para investigar?

Antes de estimar uma mudança, confirme quais fontes estão disponíveis:

- repositório e histórico de alterações;
- instruções ou acesso seguro para executar o sistema;
- configuração por ambiente, sem expor segredos;
- estrutura e cópia sanitizada dos dados quando necessária;
- logs, monitoramento e registros de incidentes;
- contratos de APIs, filas, jobs e arquivos trocados;
- pessoas que usam, mantêm ou suportam a operação.

Se acessos essenciais ainda não existem, isso é um bloqueio do diagnóstico, não um detalhe a esconder dentro da estimativa.

### Qual é a criticidade real?

Mapeie quem é afetado quando o sistema para, quais dados ele trata, em que horários opera e que obrigações de segurança ou retenção existem. Um painel interno reconstruível aceita uma abordagem diferente de um fluxo financeiro, de identidade ou atendimento contínuo.

A criticidade determina profundidade de teste, estratégia de reversão, acesso a dados e tamanho seguro de cada mudança.

### O comportamento atual pode ser reproduzido?

O primeiro marco técnico é uma baseline:

1. registrar runtime, dependências e comandos;
2. executar build e testes existentes;
3. reproduzir um fluxo representativo;
4. separar falhas já presentes de regressões novas;
5. documentar dependências e estados observados.

Quando não há teste automatizado, registre casos de uso e crie testes de caracterização pela borda mais estável disponível. Eles descrevem o comportamento atual; não declaram que todo comportamento está correto.

### O conhecimento humano foi confrontado com dados?

Entrevistas ajudam a encontrar regras e exceções, mas memória institucional pode estar incompleta. Cruze o relato com telemetria, código, schema, configurações e exemplos reais sanitizados.

Uma documentação inicial útil pode ser pequena: mapa de componentes, fluxos críticos, dependências, rotina de execução, riscos conhecidos e decisões abertas. Ela deve crescer junto com a evidência, não tentar explicar o sistema inteiro antes da primeira correção.

## Riscos e limites

O maior risco é alterar uma regra invisível. Sistemas antigos acumulam exceções em jobs, procedures, planilhas, integrações e rotinas operacionais que não aparecem na interface principal.

Outros limites frequentes:

- ambiente que só funciona em uma máquina;
- dependência sem suporte ou sem acesso;
- banco sem backup testado;
- credenciais sob responsabilidade indefinida;
- ausência de observabilidade;
- dados pessoais usados indevidamente em teste;
- mudanças simultâneas que impedem localizar a regressão.

Não use dados de produção fora dos controles autorizados e não imprima segredos para acelerar o diagnóstico. Quando segurança, regulação ou recuperação não puderem ser avaliadas, registre a lacuna e reduza o escopo da intervenção.

## Uma sequência segura de entrada

Uma passagem de responsabilidade pode ser organizada em etapas:

1. **inventário:** pessoas, acessos, ambientes, componentes e dependências;
2. **baseline:** build, execução e falhas atuais registradas;
3. **mapa de risco:** fluxos críticos, dados, integrações e impacto;
4. **proteção:** testes de caracterização, logs necessários, backup e reversão;
5. **primeira mudança:** correção pequena, observável e com critério de aceite;
6. **evolução:** backlog priorizado por risco e valor, não por estética do código.

Essa sequência pode terminar com manutenção incremental, substituição de uma fronteira ou uma reconstrução maior. A decisão vem depois do mapa.

## O que a prova relacionada sustenta — e o que não sustenta

O case público de backend .NET financeiro regulado mostra uma abordagem centrada em regras de domínio, limites de organização, autorização e testes. Ele sustenta a capacidade de trabalhar com restrições explícitas e separar evidência de implementação de etapas posteriores.

O case **não prova** que o sistema de outra empresa tem as mesmas regras, não comprova acesso a um ambiente específico e não substitui diagnóstico. Build e testes de repositório também não demonstram, sozinhos, deploy, homologação, tráfego de produção ou integração externa real.

## Decisão prática

Antes de contratar uma evolução ampla, peça um diagnóstico com saída verificável: inventário, baseline, mapa de dependências, fluxos que não podem quebrar, riscos, lacunas de acesso e uma proposta de primeira mudança reversível.

Se o diagnóstico não consegue reproduzir o sistema ou proteger o comportamento crítico, o próximo passo é recuperar essas condições. Se consegue, avance em incrementos pequenos e atualize a documentação com o que foi comprovado.

## Fontes oficiais para aprofundar

- [Detailed application assessment](https://docs.aws.amazon.com/prescriptive-guidance/latest/application-portfolio-assessment-guide/detailed-application-assessment.html) — AWS Prescriptive Guidance. O roteiro cobre arquitetura, operação, ciclo de software, testes, resiliência, segurança, bancos e dependências, cruzando informação de ferramentas e responsáveis.
- [Testing and validating your applications](https://docs.aws.amazon.com/prescriptive-guidance/latest/migration-replatforming-cots-applications/testing-validating-application.html) — AWS Prescriptive Guidance. A recomendação é registrar casos de uso com testes comportamentais e automatizados, gerar uma baseline no ambiente atual e comparar resultados como critério de aceite.

## Resumo

É possível assumir software sem documentação quando há acesso para investigar e disciplina para não confundir hipótese com fato. Recupere a baseline, mapeie riscos, proteja fluxos e faça a primeira mudança pequena antes de prometer uma transformação maior.

## Conteúdo relacionado

- Serviço: [Evolução e manutenção de software](https://yuriqueiroz.com.br/servicos/evolucao-manutencao-software)
- Case: [Backend .NET em contexto financeiro regulado](https://yuriqueiroz.com.br/projetos/backend-dotnet-financeiro-regulado)
- Artigo: [Modernize o backend .NET sem apostar tudo em uma reescrita.](https://yuriqueiroz.com.br/artigos/como-modernizar-backend-dotnet-sem-reescrever-tudo)

## Próximo passo

Mapear riscos do sistema existente. [Entrar em contato](https://yuriqueiroz.com.br/contato).