O mesmo problema pode acontecer dentro do projeto
A Conecta sofria com informação espalhada. Imagine repetir isso na equipe: requisitos num arquivo, decisões no WhatsApp, regras em outro documento e ninguém sabendo qual versão vale.
Documentar não significa escrever um livro sobre o sistema
Também não significa guardar tudo. O objetivo é simples: preservar o conhecimento que alguém vai precisar para entender, manter ou mudar a solução.
Quase nada registrado
Quando uma pessoa sai, parte do conhecimento desaparece junto.
Documento demais
Centenas de páginas repetidas acabam ficando desatualizadas e ninguém consulta.
O melhor caminho fica no meio: documentação útil, localizada e atualizável.
O que não podemos esquecer?
- qual problema estamos resolvendo;
- quem usa e quem decide;
- o que está dentro e fora do escopo;
- requisitos e regras importantes;
- o significado dos termos;
- decisões relevantes e seus motivos;
- riscos e integrações;
- ligações entre origem, requisito, interface e teste.
Se cada pessoa usa uma palavra diferente, nasce outro problema
O atendente fala “OS”. O desenvolvedor fala “ticket”. O analista fala “atendimento”. Será que estão falando da mesma coisa?
OS é a abreviação de Ordem de Serviço. Ticket é uma palavra inglesa muito usada para chamado ou registro de atendimento.
Quando um termo pode gerar confusão, vale registrá-lo num glossário: uma lista curta com os significados combinados pela equipe.
E onde fica a versão principal da informação?
Se a mesma regra for copiada para quatro lugares, uma cópia pode mudar e as outras continuar antigas. Por isso precisamos decidir qual é a fonte principal de cada informação.
Os outros documentos podem apontar para essa fonte em vez de criar cópias concorrentes.
Documentação viva
Chamamos de documentação viva aquela que acompanha o sistema e continua útil conforme o produto muda.
Ela pode ser feita em arquivos de texto simples e versionados junto com o projeto.
Markdown
Um formato simples de texto para escrever títulos, listas e destaques.
Git
Um sistema de controle de versões que registra a evolução dos arquivos.
Commit
Um registro de mudança no Git, normalmente acompanhado de uma mensagem explicando o que mudou.
Esses nomes não são o objetivo da etapa. O importante é poder descobrir o que mudou, quando e por quê.
Imagine esta pergunta daqui a seis meses
“Por que decidimos usar um serviço externo de mensagens em vez de construir um?”
Se a resposta ficou apenas numa conversa antiga, perdemos o raciocínio. Para decisões importantes, podemos guardar um pequeno registro chamado ADR.
ADR vem de Architecture Decision Record, em português Registro de Decisão de Arquitetura.
Um ADR bem simples
Contexto: precisamos avisar clientes.
Alternativas: construir internamente ou contratar um serviço.
Decisão: usar serviço externo.
Consequência: implantação mais simples, mas com dependência do fornecedor.
O valor do ADR não está no nome sofisticado. Está em preservar por que a decisão foi tomada.
E a Inteligência Artificial, onde entra?
IA significa Inteligência Artificial.
Depois de muitas entrevistas e documentos, uma IA pode ajudar a organizar anotações, comparar versões, procurar contradições e sugerir perguntas.
Mas existe uma regra importante: uma frase bem escrita pela IA não vira verdade só porque parece convincente.
Veja um exemplo
A IA escreve: “Todo orçamento expira em sete dias.”
Onde descobrimos isso? Quem informou? Existe documento?
Se não existe fonte, a frase deve virar uma pergunta: “Existe prazo de validade do orçamento?”
Classifique antes de aceitar
| O que a IA produziu? | Como tratar? |
|---|---|
| Algo apoiado numa fonte real | Evidência — preserve a origem |
| Algo possível, mas não confirmado | Hipótese — investigue |
| Uma lacuna percebida | Pergunta — leve a quem sabe |
| Uma ideia de solução | Sugestão — avalie, não transforme em requisito automaticamente |
Antes de enviar dados para uma IA
Pergunte: posso enviar isso? Há informação pessoal? Há dado confidencial? Posso remover nomes e detalhes que identificam pessoas?
Anonimizar significa retirar ou substituir informações que identificam alguém.
E quando a IA faz parte do próprio sistema?
Também começamos pelo problema, não pela moda.
Regra comum
“Valor acima de determinado limite exige gerente.” Isso pode ser resolvido com uma regra clara. Não precisamos de IA.
Possível uso de IA
Sugerir uma categoria de defeito a partir de uma descrição livre pode exigir interpretação de linguagem e produzir apenas uma sugestão.
A pessoa continua participando da decisão
Quando a IA sugere e uma pessoa confirma, corrige ou rejeita, temos um humano no circuito. O termo em inglês é Human-in-the-loop.
E se a IA estiver indisponível? Precisamos de um caminho alternativo. Esse caminho é chamado de fallback.
RAG: só se realmente precisarmos
Aprofundamento RAG vem de Retrieval-Augmented Generation, em português Geração Aumentada por Recuperação.
Em linguagem simples: antes de responder, o sistema procura informações em fontes autorizadas e usa esses trechos como contexto.
Mesmo assim, precisamos decidir quais fontes são confiáveis e quem pode acessá-las.
Faça agora
- Escolha uma decisão importante da Conecta e escreva por que ela foi tomada.
- Crie cinco termos para o glossário.
- Explique Markdown, Git e commit sem usar definição de dicionário.
- Leia uma saída de IA e diga se ela é evidência, hipótese, pergunta ou sugestão.
- Transforme uma afirmação sem fonte em uma pergunta de investigação.
- Escolha um possível uso de IA e diga por que uma regra comum seria ou não suficiente.
O que precisa continuar compreensível daqui a meses
Organize as decisões, termos e fontes principais do projeto. Evite duplicar a mesma regra em vários lugares.
Checkpoint — A equipe consegue entender depois?
Se outra pessoa entrar no projeto amanhã, ela consegue descobrir o que decidimos, por que decidimos e de onde veio a informação?