Por que decisões de engenharia se perdem

Faz tempo que me incomoda uma pergunta que ninguém consegue responder seis meses depois: "por que fizemos assim?"

A decisão foi tomada numa reunião, discutida num chat, e o único registro é a memória de quem estava lá. Quando essa pessoa sai do time, a razão some. O código fica; o porquê não.

Nos últimos dias montei um vault de Obsidian para resolver isso e resolvi documentar o que decidi e o que deu errado no caminho.

A estrutura

Seis tipos de nota, cada um com pasta, prefixo e modelo próprios:

• Sistema (SYS-): a nota-mãe de cada serviço
• ADR (ADR-0001-...): uma decisão, com contexto, alternativas e consequências
• RFC: o desenho antes da decisão
• Runbook (RB-): o procedimento para operar
• Postmortem (PM-AAAA-MM-DD-): o que quebrou e por quê
• Diário: o registro do dia, com uma seção "Decisões a registrar"

A cola entre tudo isso é uma única propriedade, system, que aponta para a nota do sistema. Com ela, uma tabela nativa do Obsidian (Bases) lista tudo o que cita aquele serviço.

Regra que me impus: nenhum plugin de terceiros. Só Propriedades, Modelos e Bases. Cada plugin é uma coisa a mais que pode quebrar.

O que deu errado (e o que aprendi)

• O título saía "Sem título". O plugin Modelos resolve {{title}} na hora de inserir. Se você aplica o modelo antes de nomear a nota, o título fica errado. Solução: nomear primeiro, depois aplicar.
• Datas sem aspas. Uma revisão apontou que {{date}} sem aspas no YAML dos modelos pode ser reescrito quando você edita o modelo pelo painel de propriedades. Não reproduzi o problema, mas por precaução passei a usar aspas e a editar modelos no modo Fonte.
• A tabela de "notas ligadas" mostrava mais do que eu queria. O filtro file.hasLink lista tudo que menciona o sistema, não só o que pertence a ele. Descobri isso quando um sistema listou ADRs de outro. Mantive, mas agora está documentado.
• "Nunca reutilize o número do ADR" só se sustenta se ninguém apagar ADRs. Passei a tratar ADR como imutável: em vez de apagar, muda o status para superseded.

A camada de IA

Escrevi um CLAUDE.md com as regras do vault e oito comandos para o Claude Code que criam, conectam e revisam notas. As regras principais: não inventar fatos, não criar links para notas que não existem, e pedir confirmação antes de editar uma nota existente.

Testei de propósito: dei entradas vagas para ver se ele inventava contexto. Não inventou, e deixou as seções vazias com o comentário do modelo. Isso é regra de comportamento, não garantia: continuo revisando tudo.

Para quem quiser olhar

Publiquei uma versão gratuita (MIT) com a estrutura, os modelos, a tabela de notas ligadas e um exemplo navegável com uma empresa fictícia: https://github.com/PardalZ7/memoria-de-engenharia

Há também uma versão com a camada de IA; os detalhes estão em https://pardalz7.github.io/

Se você já tentou manter ADRs ou runbooks e desistiu, me conta onde travou. É isso que quero melhorar a seguir.