Produtos lembram estados melhor do que organizações lembram raciocínios.
O banco de dados pode mostrar a configuração atual. O Git pode mostrar qual código mudou. Uma ferramenta de projetos pode mostrar quais tarefas foram concluídas. Um arquivo de design pode mostrar a interface atual.
Nada disso necessariamente explica por que uma decisão importante foi tomada.
Quais evidências existiam? Quais alternativas foram descartadas? Qual restrição importava naquele momento? Qual premissa ainda era incerta? O que precisaria mudar para que o time devesse revisitar a decisão?
Quando esse contexto desaparece, a organização perde mais do que documentação.
Perde qualidade de decisão.
As decisões se deterioram mais rápido do que os artefatos
Um time de produto pode acumular anos de decisões:
- por que um fluxo exige aprovação;
- por que um fornecedor foi escolhido;
- por que um modelo de dados preserva o histórico;
- por que uma funcionalidade foi excluída intencionalmente;
- por que uma fronteira de serviço existe;
- por que um segmento de mercado foi adiado;
- por que um experimento fracassou.
O artefato visível frequentemente sobrevive enquanto a justificativa desaparece.
Isso cria uma situação perigosa, porque times posteriores encontram uma decisão sem saber se ela ainda é válida.
Eles têm duas opções ruins.
Podem preservá-la cegamente.
Ou podem revertê-la cegamente.
Michael Nygard descreveu esse problema no contexto da arquitetura de software ao apresentar os registros de decisão arquitetural, os ADRs. Eles preservam contexto, decisão, status e consequências para que times futuros entendam por que uma escolha estrutural existe.
O mesmo princípio vale para além da arquitetura.
Decisões de produto também precisam de memória.
Documentação não é o mesmo que memória das decisões
Organizações frequentemente têm uma quantidade enorme de documentação e uma memória frágil.
Uma wiki pode conter pesquisas antigas, notas de reuniões, apresentações de estratégia e requisitos. A dificuldade não é o armazenamento. É saber qual informação é atual, tem autoridade e está conectada a uma decisão.
A memória das decisões precisa de estrutura.
Um registro útil distingue:
Fatos
Premissas
Evidências
Questões em aberto
Decisão
Justificativa
Consequências
Condições para revisitar
Decisões substituídas
Essas categorias evitam uma das falhas mais comuns da documentação: tratar tudo o que foi escrito como igualmente verdadeiro.
Uma fala de cliente é evidência.
Uma interpretação dessa fala não é um fato.
Uma premissa de planejamento pode ser útil sem ter sido verificada.
Uma decisão pode continuar vigente mesmo quando as evidências que a sustentam mudam depois.
O sistema precisa preservar essas distinções.
O contexto canônico reduz a redescoberta
Times pagam repetidamente pelas mesmas perguntas quando o contexto está fragmentado.
Uma nova pessoa engenheira pergunta por que uma integração funciona de determinada maneira. Uma pessoa de produto reabre uma antiga questão de mercado. Um assistente de IA recebe um prompt parcial e propõe uma opção que o time descartou seis meses antes por um motivo conhecido.
O custo aparece como descoberta repetida.
Contexto canônico não significa um documento gigantesco.
Significa que existe uma representação mantida do contexto que a organização considera atualmente como referência oficial, com links para evidências e histórico.
Esse contexto pode incluir:
- fronteiras do produto;
- atores;
- definições do domínio;
- premissas atuais;
- decisões;
- questões em aberto;
- restrições;
- implicações arquiteturais;
- procedência das fontes.
O objetivo não é eliminar a conversa.
É fazer a conversa começar pelo estado conhecido mais recente, em vez de reconstruir o histórico.
Decisões substituídas não devem desaparecer
Quando uma decisão muda, os times frequentemente sobrescrevem o documento.
Isso destrói informação útil.
A decisão anterior pode explicar por que o sistema atual ainda contém determinada estrutura. Pode revelar o que mudou no ambiente. Pode impedir que o time volte a uma opção antiga sob a impressão equivocada de que ninguém a considerou.
O formato de ADR de Nygard lida com isso preservando os registros antigos e marcando-os como substituídos.
A memória das decisões de produto deveria fazer o mesmo.
Um registro de decisão pode passar por estados como:
Proposta
↓
Aceita
↓
Ativa
↓
Substituída
A decisão antiga continua fazendo parte do histórico sem continuar sendo a referência vigente.
Essa distinção é especialmente importante para sistemas de IA que recuperam conhecimento organizacional. Um sistema de busca que encontra uma decisão obsoleta sem metadados de status pode fazer um contexto histórico parecer atual.
As condições para revisitar costumam valer mais do que as datas
Um time pode decidir não construir uma capacidade porque poucos clientes precisam dela.
A decisão é válida sob uma condição.
Se a composição da base de clientes mudar, a decisão deve ser reconsiderada.
Um bom registro de decisão inclui, portanto, condições para revisitar:
- quando o volume de transações ultrapassar um limite;
- quando o fornecedor mudar os preços;
- quando uma nova jurisdição entrar em operação;
- quando uma integração se tornar uma dependência estratégica;
- quando o produto entrar em um segmento regulado;
- quando problemas recorrentes de suporte ultrapassarem um nível acordado.
Isso torna a decisão sensível à realidade.
Também impede que reuniões periódicas de estratégia reabram todas as perguntas antigas apenas porque o tempo passou.
A memória de produto melhora o contexto da IA
Sistemas de IA tornam o problema da memória mais visível porque a qualidade de suas saídas depende muito do contexto fornecido.
Um modelo solicitado a propor uma arquitetura sem conhecer restrições anteriores pode produzir uma resposta tecnicamente coerente e organizacionalmente errada.
Um modelo solicitado a resumir a estratégia de produto a partir de documentos históricos misturados pode combinar posições substituídas com posições atuais.
O problema não está apenas no modelo.
O sistema de conhecimento não tem metadados de autoridade.
Isso se conecta a A saída da IA não é verdade canônica. A IA pode ajudar a recuperar, resumir e raciocinar sobre o conhecimento de produto, mas deve operar sobre um contexto que distinga evidências, decisões, incertezas e histórico.
Prompts melhores não compensam inteiramente uma memória organizacional ruim.
Registros de decisão devem ser pequenos o suficiente para serem mantidos
Grandes sistemas de governança frequentemente fracassam porque mantê-los custa mais do que o valor percebido.
A memória das decisões precisa de uma unidade de baixo atrito.
Um registro útil de decisão de produto pode ser curto:
Decisão:
Permitir que a conta de um aluno sobreviva às mudanças de escola.
Contexto:
Alunos podem mudar de escola, mas seu histórico pessoal de conquistas deve permanecer contínuo.
Evidência:
A pesquisa de domínio mostra que o vínculo escolar é limitado no tempo, enquanto a identidade do aluno é persistente.
Decisão:
A identidade do aluno pertence ao modelo de contas da plataforma. O vínculo escolar é uma relação temporal separada.
Consequências:
O acesso aos dados privados da escola termina quando o vínculo acaba. O histórico pessoal continua visível conforme as permissões aplicáveis.
Questão em aberto:
Quais regras de retenção se aplicam a artefatos gerados pela escola após a saída?
Revisitar se:
Requisitos legais ou contratuais exigirem fronteiras de identidade pertencentes à instituição.
O valor vem de preservar o raciocínio, não da formatação.
A memória precisa de responsáveis
Documentação que pertence a todos frequentemente não pertence a ninguém.
A memória das decisões exige responsabilidade pela manutenção.
Ter um responsável não significa que uma pessoa aprove todas as mudanças. Significa que alguém ou algum papel é responsável por manter a coerência do contexto canônico.
Práticas úteis incluem:
- atribuir responsáveis às principais áreas de decisão;
- revisar premissas desatualizadas;
- conectar decisões às evidências;
- marcar explicitamente o que foi substituído;
- registrar novas perguntas quando evidências entrarem em conflito;
- incluir atualizações de decisões nas mudanças relevantes de produto.
O modelo de manutenção deve ser proporcional às consequências.
Um produto pequeno não precisa de um departamento corporativo de governança do conhecimento. Precisa de uma forma de evitar que raciocínios importantes se percam silenciosamente.
A memória deve apoiar a mudança, não congelá-la
Um registro de decisões pode se tornar burocrático se os times começarem a tratar decisões registradas como lei.
Isso é o oposto de seu propósito.
A memória das decisões deve tornar a mudança mais segura ao deixar visível o contexto anterior.
Um bom registro diz:
Foi isso que decidimos sob estas condições.
Ele não diz:
Esta decisão nunca pode mudar.
Os registros de decisão arquitetural são valiosos, em parte, porque tornam normal a substituição de decisões. Decisões de produto deveriam ter a mesma humildade.
A compreensão evolui.
As evidências mudam.
Restrições desaparecem.
Novas restrições surgem.
O sistema de memória deve ajudar a organização a mudar conscientemente.
Noesis e o problema da inteligência de produto
O Noesis da NILLKAI, o Product Intelligence System, atua nesse território conceitual.
O problema que ele aborda é mais amplo do que o armazenamento de documentos. Times de produto precisam de uma forma de preservar contexto, evidências, premissas, questões em aberto, decisões e procedência, para que raciocínios futuros comecem a partir de um estado compreensível.
O conceito continua sendo uma resposta estruturada a uma classe de problemas de inteligência de produto, e não uma afirmação de que um único framework elimina o esquecimento organizacional.
Sua utilidade depende do mesmo princípio descrito aqui:
O conhecimento de produto deve preservar não apenas aquilo em que a organização acredita atualmente, mas como essa crença se tornou uma referência oficial e o que justificaria alterá-la.
Isso é memória das decisões.
Preserve o raciocínio que torna a mudança inteligente
O software muda porque o contexto muda.
Organizações devem esperar que as decisões evoluam.
Mas evoluir sem memória é caro. Times redescobrem perguntas antigas, repetem erros, preservam restrições obsoletas e fornecem contexto incompleto tanto a pessoas quanto a sistemas de IA.
Um sistema útil de memória não tenta registrar tudo.
Ele preserva o raciocínio por trás das decisões que moldam as opções futuras.
O teste é simples:
Quando alguém encontrar uma decisão importante de produto ou arquitetura daqui a seis meses, conseguirá entender:
- o contexto;
- as evidências;
- as alternativas;
- a justificativa;
- a consequência;
- o status atual;
- as condições sob as quais ela deve ser revisitada?
Se a resposta for sim, a organização tem mais do que documentação.
Tem uma memória capaz de melhorar a próxima decisão.
Referências
- Michael Nygard. Documenting Architecture Decisions. 2011. https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
- ADR GitHub Organization. ADR Templates. https://adr.github.io/adr-templates/
- Google. Documentation Best Practices. Google Style Guides. https://google.github.io/styleguide/docguide/best_practices.html