The latest articles on DEV Community by Pardal (@pardalz7). https://dev.to/pardalz7 https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4187702%2Fdfdbeebb-8e2a-4323-b55e-cabc61cd85d9.png https://dev.to/pardalz7 en Pardal Fri, 16 Oct 2026 02:28:41 +0000 https://dev.to/pardalz7/por-que-as-decisoes-de-engenharia-se-perdem-e-como-estruturei-um-vault-de-obsidian-para-nao-3a7d https://dev.to/pardalz7/por-que-as-decisoes-de-engenharia-se-perdem-e-como-estruturei-um-vault-de-obsidian-para-nao-3a7d <p>Faz tempo que me incomoda uma pergunta que ninguém consegue responder seis meses depois: "por que fizemos assim?"</p> <p>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.</p> <p>Nos últimos dias montei um vault de Obsidian para resolver isso e resolvi documentar o que decidi e o que deu errado no caminho.</p> <h2> A estrutura </h2> <p><a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fr5thr3s4b1vl2loyc2tu.png" class="article-body-image-wrapper"><img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fr5thr3s4b1vl2loyc2tu.png" alt="Grafo de notas do exemplo SampleShop no Obsidian: sistemas, ADRs, RFCs, runbook e postmortems ligados pela propriedade system" width="799" height="639"></a></p> <p>Seis tipos de nota, cada um com pasta, prefixo e modelo próprios:</p> <ul> <li> <strong>Sistema</strong> (<code>SYS-</code>): a nota-mãe de cada serviço</li> <li> <strong>ADR</strong> (<code>ADR-0001-...</code>): uma decisão, com contexto, alternativas e consequências</li> <li> <strong>RFC</strong>: o desenho antes da decisão</li> <li> <strong>Runbook</strong> (<code>RB-</code>): o procedimento para operar</li> <li> <strong>Postmortem</strong> (<code>PM-AAAA-MM-DD-</code>): o que quebrou e por quê</li> <li> <strong>Diário</strong>: o registro do dia, com uma seção "Decisões a registrar"</li> </ul> <p>A cola entre tudo isso é uma única propriedade, <code>system</code>, que aponta para a nota do sistema. Com ela, uma tabela nativa do Obsidian (Bases) lista tudo o que cita aquele serviço.</p> <p>Regra que me impus: <strong>nenhum plugin de terceiros</strong>. Só Propriedades, Modelos e Bases. Cada plugin é uma coisa a mais que pode quebrar.</p> <h2> O que deu errado (e o que aprendi) </h2> <ul> <li> <strong>O título saía "Sem título".</strong> O plugin Modelos resolve <code>{{title}}</code> 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.</li> <li> <strong>Datas sem aspas.</strong> Uma revisão apontou que <code>{{date}}</code> 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.</li> <li> <strong>A tabela de "notas ligadas" mostrava mais do que eu queria.</strong> O filtro <code>file.hasLink</code> lista tudo que <em>menciona</em> o sistema, não só o que <em>pertence</em> a ele. Descobri isso quando um sistema listou ADRs de outro. Mantive, mas agora está documentado.</li> <li> <strong>"Nunca reutilize o número do ADR"</strong> só se sustenta se ninguém apagar ADRs. Passei a tratar ADR como imutável: em vez de apagar, muda o status para <code>superseded</code>.</li> </ul> <h2> A camada de IA </h2> <p>Escrevi um <code>CLAUDE.md</code> 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.</p> <p>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.</p> <h2> Para quem quiser olhar </h2> <p>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: <a href="https://github.com/PardalZ7/memoria-de-engenharia" rel="noopener noreferrer">https://github.com/PardalZ7/memoria-de-engenharia</a></p> <p>Há também uma versão com a camada de IA; os detalhes estão em <a href="https://pardalz7.github.io/" rel="noopener noreferrer">https://pardalz7.github.io/</a></p> <p>Se você já tentou manter ADRs ou runbooks e desistiu, me conta onde travou. É isso que quero melhorar a seguir.</p> obsidian documentation braziliandevs productivity