Lore: Repurposing Git Commit Messages as a Structured Knowledge Protocol for AI Coding Agents

O artigo apresenta o Lore, um protocolo leve que transforma mensagens de commit do Git em registros de decisão estruturados, capturando o raciocínio descartado (Decision Shadow) para preservar o conhecimento institucional e habilitar agentes de IA a compreenderem o contexto e as restrições por trás das alterações de código sem exigir infraestrutura adicional.

O essencial

Imagine que você está construindo uma casa. Você decide usar tijolos vermelhos em vez de brancos porque o branco mancha fácil com a chuva local. Você constrói a parede, mas não escreve nenhum bilhete explicando por que escolheu os vermelhos.

Anos depois, um novo construtor (ou um robô inteligente) chega para reformar a casa. Ele vê a parede de tijolos vermelhos. Ele sabe o que está lá, mas não sabe por que está lá. Ele pode tentar pintar de branco, achando que é uma escolha estética, e estragar tudo porque esqueceu a regra da chuva.

Esse é o problema que o artigo "Lore" tenta resolver.

Aqui está uma explicação simples, usando analogias do dia a dia:

1. O Problema: A "Sombra da Decisão"

No mundo do software, quando alguém (ou uma Inteligência Artificial) muda um código, eles salvam a mudança (o "diff"). É como salvar a foto da parede pronta. Mas tudo o que aconteceu antes da foto — as dúvidas, as opções que foram descartadas, os avisos de perigo, o motivo da escolha — desaparece.

O autor chama isso de Sombra da Decisão. É o conhecimento invisível que fica para trás. Com o tempo, o código vira "código legado": funciona, mas ninguém sabe mais por que foi feito daquela maneira.

2. A Solução: O "Lore" (A Lenda Viva)

O autor propõe o Lore (que significa "conhecimento tradicional" ou "lenda" em inglês). A ideia é transformar a mensagem que acompanha cada mudança de código em um diário de bordo completo, e não apenas um título chato.

Hoje, as mensagens de commit são como etiquetas de mala: "Arrumou a mala" (Refatorou o código).
O Lore transforma essa etiqueta em um bilhete de viagem detalhado:

• "Arrumamos a mala porque o aeroporto estava lotado."
• "Tentamos usar um avião, mas era caro demais (Rejeitado)."
• "Cuidado: não tire a mala do lugar se chover (Restrição)."
• "Confiança alta de que isso vai funcionar."

3. Como Funciona na Prática? (Sem complicação)

A genialidade do Lore é que ele não precisa de novos softwares caros, bancos de dados ou servidores complexos. Ele usa algo que todo programador já tem: o Git (o sistema que salva o histórico de códigos).

• O Truque: O Git já tem uma funcionalidade chamada "trailers" (rótulos no final da mensagem). O Lore usa isso para criar campos padronizados.
• A Analogia: Imagine que o histórico do projeto é um livro de receitas. O Lore transforma as anotações rabiscadas na borda da página em uma lista de ingredientes e dicas de chefia que qualquer novo cozinheiro (ou robô) pode ler e entender imediatamente.

4. Por que isso é importante para a Inteligência Artificial?

Hoje, temos robôs (IA) escrevendo e lendo códigos.

• O Problema Atual: Se você pedir para um robô mudar um código antigo, ele lê o código e tenta adivinhar o motivo. Como a "Sombra da Decisão" sumiu, ele muitas vezes erra ou propõe soluções que já foram descartadas há 5 anos.
• Com o Lore: O robô chega, lê a mensagem do Lore e diz: "Ah, entendi! O código antigo foi feito assim porque o servidor de autenticação era lento. Não vou mudar isso, senão vai quebrar."
• O Ciclo Virtuoso: Quando o robô faz uma nova mudança, ele é obrigado a escrever sua própria "Sombra da Decisão" no Lore. Assim, o conhecimento da empresa nunca mais se perde.

5. Comparando com outras ideias

• ADRs (Documentos de Decisão): São como livros grossos de arquitetura. São ótimos para grandes decisões, mas ninguém lê para saber por que uma pequena função foi escrita de um jeito específico. O Lore é como um post-it colado exatamente no lugar da mudança.
• Comentários no Código: Comentários são como bilhetes deixados na geladeira; com o tempo, a comida estraga e o bilhete fica errado. O Lore é imutável: ele fica preso para sempre àquela versão específica do código, como um fóssil perfeito.

Resumo em uma frase

O Lore é um protocolo simples que transforma as mensagens de atualização de software em diários de decisão inteligentes, garantindo que, no futuro, nem humanos nem robôs precisem adivinhar "por que as coisas são assim", porque a resposta estará escrita, clara e organizada, exatamente ao lado do código.

É como dar uma "memória de elefante" para o projeto de software, garantindo que nenhuma lição aprendida (ou erro cometido) seja esquecida.

Resumo técnico

Resumo Técnico: Lore – Protocolo de Conhecimento Estruturado via Git

1. O Problema: A "Sombra da Decisão" (Decision Shadow)

O artigo identifica uma crise crítica na indústria de software impulsionada pela ascensão de agentes de IA como produtores e consumidores primários de código.

• A Perda de Conhecimento Tácito: Cada commit no Git captura o diff (a mudança no código), mas descarta todo o raciocínio por trás dela. Isso inclui definições de problemas, alternativas rejeitadas, restrições de negócio, níveis de confiança e avisos futuros. O autor chama esse contexto perdido de "Sombra da Decisão".
• O Colapso dos Pressupostos Atuais: O formato atual de mensagens de commit (como o Conventional Commits) foi projetado para humanos, focando no "o que" mudou, não no "porquê". Com a IA agora lendo o histórico para fazer modificações, mensagens vagas como refactor: clean up utils transmitem quase zero sinal útil.
• Aceleração da Destruição de Conhecimento: Como os agentes de IA geram commits baseados apenas no diff (uma compressão com perda de informação), o volume de código cresce, mas a proporção de conhecimento institucional registrado por unidade de código diminui, criando um legado de "código que funciona, mas cujo raciocínio foi perdido".

2. Metodologia e Proposta: O Protocolo Lore

O autor propõe o Lore, um protocolo leve que transforma a mensagem de commit existente em um registro de decisão estruturado e autocontido, sem exigir infraestrutura externa.

• Mecanismo de Implementação: O Lore utiliza Git Trailers (um recurso nativo do Git para dados chave-valor em mensagens de commit). Isso elimina a necessidade de parsers personalizados ou bancos de dados externos.
• Estrutura do "Lore Atom": Uma mensagem de commit Lore consiste em:
  1. Linha de Intenção: Explica por que a mudança foi feita (não o que mudou).
  2. Corpo Narrativo: Contexto descritivo.
  3. Trailers Estruturados: Metadados máquina-parseáveis que capturam o contexto da decisão.
• Vocabulário de Trailers (Exemplos):
  • Constraint: Regras que moldaram a decisão (ex: "API não suporta introspecção").
  • Rejected: Alternativas consideradas e descartadas, com motivos (ex: "Refresh em background: causa race condition").
  • Confidence: Avaliação do autor (baixa, média, alta).
  • Directive: Instruções futuras para modificadores (ex: "Não estreite o tratamento de erro sem verificar o upstream").
  • Not-tested: O que não foi verificado e por quê.
• Ferramenta CLI: Um utilitário de linha de comando (lore) permite que agentes e humanos consultem o histórico de decisões de forma eficiente (ex: lore context <caminho>, lore rejected <caminho>).

3. Contribuições Principais

1. Protocolo de Conhecimento Inter-Agente: Lore é a primeira proposta a usar a mensagem de commit como um canal estruturado e máquina-parseável otimizado para a comunicação entre agentes de IA ao longo do tempo.
2. Solução de Infraestrutura Zero: Diferente de soluções concorrentes que exigem grafos de conhecimento complexos ou arquivos separados, o Lore usa o que todo projeto já possui (Git) e o que todo agente já sabe usar (comandos de shell).
3. Modelo de Consumo para IA: Define um fluxo de trabalho onde o agente:
   • Descobre o protocolo via CLI.
   • Coleta restrições e diretrizes antes de modificar código.
   • Filtra "anti-padrões" (alternativas rejeitadas) para evitar loops de erro.
   • Serializa seu próprio contexto de decisão ao criar um novo commit Lore.
4. Distinção de Granularidade: O Lore preenche a lacuna entre os Architecture Decision Records (ADRs - decisões de alto nível) e os comentários de código (muitas vezes desatualizados), focando especificamente em decisões de implementação atomizadas e imutáveis.

4. Resultados e Validação (Proposta)

O artigo é uma proposta teórica e de design (data de publicação futura: 2026), portanto, não apresenta resultados empíricos finais, mas define um caminho de validação:

• Comparação com Abordagens Existentes: O Lore supera ADRs (que sofrem de dessincronização com o código), resumos de diff gerados por IA (que apenas descrevem o óbvio) e sistemas de "Digital Twin" (que são pesados demais para a maioria dos projetos).
• Caminho de Adoção: A adoção é projetada para ser "Agente-Primeiro". Como os agentes podem gerar os commits Lore automaticamente, a barreira de entrada é reduzida em comparação com o Conventional Commits (que exigia digitação humana).
• Métrica de Sucesso Futura: O autor propõe um estudo de 6 meses comparando duas equipes (uma com Lore, outra sem), medindo: taxa de sucesso de tarefas da IA, tempo para solução correta, taxa de repropor alternativas já rejeitadas e ciclos de revisão.

5. Significado e Impacto

O artigo argumenta que o Git commit é o "elo perdido" na cadeia de conhecimento do desenvolvimento de software assistido por IA.

• Mudança de Paradigma: Transforma o commit de um simples rótulo de versão para a unidade atômica de conhecimento institucional.
• Sustentabilidade do Código: Ao preservar a "Sombra da Decisão", o Lore permite que futuros agentes (e humanos) entendam não apenas o estado atual do código, mas a trajetória evolutiva e as restrições que o moldaram.
• Escalabilidade: Por ser leve e não depender de servidores ou índices externos, o Lore é escalável para qualquer projeto que utilize Git, oferecendo um "flywheel de conhecimento" onde o valor do histórico cresce com o tempo, em vez de se degradar.

Conclusão: O Lore propõe uma solução minimalista, porém poderosa, para o problema de perda de conhecimento tácito na era da IA, utilizando a infraestrutura existente do Git para garantir que o "porquê" do código seja tão preservado quanto o próprio código.