Já olhou para o seu projeto e se perguntou por que escolheu, sei lá, MariaDB ao invés de PostgreSQL? Ou por que aquela a biblioteca "batata" entrou nas suas dependências? Pois é, senta ai pra gente conversar.

O problema que eu estava cansado de resolver

Todos nós já passamos por isso. Você está integrando um novo desenvolvedor, ou revisitando código de seis meses atrás, e alguém pergunta: "Por que usamos esta biblioteca?" E você fica sem resposta. Talvez uma mensagem de commit vaga. Talvez um thread no Slack perdido... talvez apenas um encolher de ombros.

O fato é que tomamos dezenas de decisões técnicas toda semana. Algumas são grandes (trocar banco de dados), outras parecem pequenas (adicionar uma nova dependência). Mas todas têm contexto, trade-offs e razões. E a maior parte desse conhecimento simplesmente… evapora (ou fica preso na mente do desenvolvedor).

O Conselho: ADRs

Registros de Decisão de Arquitetura (ADRs) são ótimos e se você não sabe do que estou falando já deixa uma aba aberta pra pesquisar sobre e me agradeça depois. O ponto é que na teoria eles funcionam lindamente. Mas na prática?... Bem, quando estou imerso no processo, prestes a commitar código às 2 da manhã (como agora, 02:04), a última coisa que quero fazer é trocar de contexto para escrever um arquivo markdown do zero.

Então as decisões não são documentadas. O contexto se perde. E seis meses depois, estamos todos confusos.

E se a documentação acontecesse automaticamente?

Essa é a ideia central por trás do LDDL (Local Dev Decision Log — Registro de Decisões de Desenvolvimento Local). E se seu fluxo de git pudesse gentilmente te lembrar de documentar decisões no momento exato em que você as toma?

Veja como funciona:

1. Instale uma única vez

npm install -g lddl
cd seu-projeto
lddl init

Pronto. O LDDL instala hooks do git no seu repositório. Não é invasivo e nem é complicado. Apenas vai estar lá quando você precisa.

2. Faça Mudanças Normalmente

Você adiciona uma nova dependência. Você commita. E segue seu fluxo normal.

npm install express
git add .
git commit -m "Adiciona express"

3. Seja alertado (na hora certa)
   Aqui é onde a mágica acontece. O LDDL detecta que você adicionou uma dependência e pergunta:

📦 Novas dependências detectadas: express

Gostaria de criar um registro de decisão para isso? (s/N)

Se disser sim, você é questionado sobre o contexto:

Por que você adicionou essa dependência? (Contexto): Preciso de um framework web para API REST
Para que vai usá-la? (Decisão): Construir o servidor HTTP
Algum trade-off ou impacto? (Consequências): Adiciona ~500KB ao tamanho do pacote

E pronto. Decisão registrada. Sem troca de contexto. Sem arquivo separado para criar. Apenas uma conversa natural com seu fluxo de git.

4. Tudo Fica No Seu Repositório
   A decisão é salva como um arquivo markdown em .lddl/decisions/:

# Adicionar dependência express

**Data:** 2026-01-04T00:15:00.000Z

## Contexto

Preciso de um framework web para API REST

## Decisão

Construir o servidor HTTP

## Consequências

Adiciona ~500KB ao tamanho do pacote

É versionado. Viaja com seu código. É pesquisável. E é seu.

A Filosofia

O LDDL não tenta substituir a documentação arquitetural! Não tenta forçar você a seguir um processo. Apenas captura aquelas pequenas decisões que, eventualmente, escapariam pelos buracos.

Pense nele como uma rede de segurança para a memória coletiva da sua equipe (o Claude que sugeriu esse pitch, achei massa haha).

O Aprendizado

Git hooks são poderosos. Eles permitem que você se conecte ao fluxo natural do desenvolvedor sem ser invasivo. Em outras palavras, a chave é nunca bloquear commits. Embora o LDDL sempre permite que você pule ou ignore os prompts.

O timing é fundamental. Alertar durante prepare-commit-msg significa que o desenvolvedor já está no "modo de commit". O contexto está fresco na mente dele. Ele ainda não trocou de contexto.

Local-first importa. Tudo fica no seu repositório. Sem serviços externos, sem chamadas de API, sem vendor lock-in. Apenas arquivos markdown que funcionam offline, para sempre.

O Que Vem Por Aí

No momento, o LDDL detecta mudanças em dependências. Mas há muito mais a fazer:

• 🏗️ Mudanças de infraestrutura (Dockerfile, configurações de CI)
• 🏛️ Mudanças de arquitetura (novos módulos, estrutura de pastas)
• 🔄 Atualizações de processo (novos scripts npm, workflows)
• 🤖 Sugestões de contexto com IA
• 📊 Análises e padrões de decisões

O objetivo não é documentar tudo. É tornar a documentação das coisas importantes tão sem atrito que você realmente a faça naturalmente.

O verdadeiro valor

Há algumas semanas, um colega perguntou por que escolhemos uma biblioteca específica. Em vez de dizer "Não me lembro", digitei:

lddl list

E lá estava lindamente. Contexto, razões, trade-offs. Tudo capturado três meses atrás, quando a decisão era recente.

Essa é a verdadeira conquista. Contexto suficiente para não se sentir perdido na seu próprio app.

O LDDL é open source e está disponível no NPM. Então experimente e Feliz Ano Novo!

PS: If you'd like to read this article in English, you can check the original blog post here.