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

Este artículo presenta Lore, un protocolo ligero que transforma los mensajes de confirmación de Git en registros de decisiones estructurados mediante trailers nativos, permitiendo a los agentes de IA codificadores capturar y consultar el razonamiento, las restricciones y las alternativas descartadas que normalmente se pierden en el desarrollo de software.

Lo esencial

Imagina que estás construyendo una ciudad gigante, ladrillo a ladrillo. Cada vez que pones un ladrillo, dejas una nota rápida que dice: "Puse este ladrillo aquí". Pero nunca escribes por qué lo pusiste ahí, ni por qué decidiste no ponerlo en otro lugar, ni qué problemas imaginaste que podrían surgir si lo hicieras de otra manera.

Con el tiempo, tienes una ciudad enorme (tu código), pero nadie sabe por qué las calles están donde están o por qué algunos edificios tienen ventanas extrañas. Si un nuevo arquitecto (o un robot) intenta arreglar algo, solo ve los ladrillos, no las razones detrás de ellos. Se pierde la historia, la lógica y el "por qué".

Este es el problema que el investigador Ivan Stetsenko llama "La Sombra de la Decisión": toda la sabiduría que se pierde porque solo guardamos el resultado final, no el pensamiento.

¿Qué propone este papel? (La solución "Lore")

El autor propone una idea sencilla pero brillante llamada Lore.

Imagina que cada vez que pones un ladrillo (haces un cambio en el código), en lugar de solo escribir "Puse ladrillo", usas un formato especial para dejar una tarjeta de instrucciones pegada directamente al ladrillo. Esta tarjeta no es un libro separado que se puede perder; está atada al ladrillo para siempre.

Esta tarjeta tiene secciones mágicas que dicen cosas como:

• "No hagas esto": (Alternativas que probamos y descartamos).
• "Reglas estrictas": (Cosas que no podíamos romper, como "no podemos hacer que la app sea lenta").
• "Advertencia para el futuro": (Si alguien toca esto, ten cuidado porque...).
• "Confianza": (Qué tan seguro estoy de que esto funcionará).

¿Por qué es tan genial esta idea?

1. No necesitas construir nada nuevo:
   Imagina que tienes un cuaderno de bitácora (Git) que ya usas para todo. Lore no te pide comprar un nuevo edificio, ni instalar un servidor gigante, ni aprender un idioma nuevo. Solo te pide que uses las páginas que ya tienes, pero escribas un poco más de información en ellas. Es como si tu cuaderno de notas tuviera un código secreto que solo tú y tus robots pueden leer perfectamente.

2. Es para los robots (y para ti):
   Hoy en día, los programadores son cada vez más robots (Inteligencia Artificial). Estos robots son muy buenos leyendo código, pero muy malos adivinando por qué se hizo algo.

   • Sin Lore: El robot ve un código y piensa: "¿Por qué está así? ¡A ver si lo cambio!". Y rompe algo.
   • Con Lore: El robot lee la tarjeta pegada al código y dice: "¡Ah! Aquí el humano escribió que no podemos cambiar esto porque rompería la seguridad. ¡Entendido, no lo toco!".

3. El "Efecto Flywheel" (La rueda de la sabiduría):
   Cuantos más cambios haces con Lore, más sabiduría acumulada tiene tu proyecto. Cada nuevo robot que entra al proyecto aprende de los errores y decisiones de los robots anteriores. Es como si cada generación de constructores dejara un manual de instrucciones perfecto para la siguiente, sin tener que hablar con ellos.

Una analogía final: El Chef y la Receta

Imagina que eres un chef famoso.

• El método actual: Dejas una nota en la nevera que dice: "Hice la salsa con ajo". Si otro chef entra, sabe que hay ajo, pero no sabe si usaste ajo fresco o en polvo, si lo cortaste fino o grueso, o si casi usaste cebolla pero decidiste que no.
• El método Lore: Dejas una nota que dice: "Hice la salsa con ajo fresco picado fino. No usé cebolla porque el cliente es alérgico (Regla). Probé con ajo en polvo pero sabía a cartón (Alternativa rechazada). Si quieres cambiar esto, asegúrate de que el cliente siga sin alergias (Advertencia)."

En resumen

El papel dice: Dejemos de tirar la basura intelectual.

Cada vez que alguien (humano o robot) escribe código, está tomando decisiones importantes. Actualmente, tiramos esas decisiones a la basura y solo guardamos el código. Lore es un protocolo simple para guardar esas decisiones en el mismo lugar donde está el código, de forma que cualquier persona o robot del futuro pueda leerlas, entenderlas y no cometer los mismos errores.

Es como pasar de tener una ciudad oscura y confusa, a tener una ciudad con letreros luminosos en cada esquina que explican la historia de por qué todo está como está.

Resumen técnico

Aquí tienes un resumen técnico detallado del artículo "Lore: Repurposing Git Commit Messages as a Structured Knowledge Protocol for AI Coding Agents" (Lore: Reutilizando los mensajes de commit de Git como un protocolo de conocimiento estructurado para agentes de codificación con IA), escrito en español.

---

Resumen Técnico: Lore

1. El Problema: La "Sombra de la Decisión" (Decision Shadow)

El artículo identifica un problema crítico en el desarrollo de software asistido por IA: la pérdida acelerada de conocimiento institucional.

• El Fenómeno: Cada commit de Git captura el resultado final (el diff o cambio de código), pero descarta todo el proceso de razonamiento que llevó a esa decisión. Esta información perdida incluye definiciones de problemas, alternativas rechazadas, restricciones, niveles de confianza y advertencias futuras.
• La Sombra de la Decisión: El autor denomina a este contexto no registrado como la "Sombra de la Decisión". Con el tiempo, estas sombras se acumulan, creando "código legado" que funciona pero cuyo razonamiento estructural es incomprensible.
• La Urgencia: La situación se agrava por dos tendencias actuales:
  1. Los agentes de IA son los principales consumidores de código: Herramientas como Copilot o Cursor intentan inferir la intención a partir del código existente, pero los mensajes de commit tradicionales (ej. fix: corregir error) no proporcionan el contexto necesario ("el porqué").
  2. Los agentes de IA son los principales productores de código: Cuando los agentes generan commits, suelen resumir el diff de manera pérdida, sin añadir nuevo contexto de decisión, acelerando la destrucción del conocimiento.

2. Metodología: El Protocolo Lore

Lore propone una solución ligera que no requiere nueva infraestructura, sino reutilizar y estructurar un artefacto existente: el mensaje de commit de Git.

• Concepto Central (Lore Atom): Un commit debe ser la unidad atómica de conocimiento institucional, vinculada inmutablemente al cambio de código que describe.
• Implementación Técnica:
  • Uso de "Git Trailers": Lore aprovecha una función nativa de Git (los trailers, pares clave-valor al final del mensaje) para estructurar los datos. Esto evita el análisis sintáctico personalizado y garantiza compatibilidad con todas las herramientas de Git.
  • Estructura del Mensaje:
    • Línea de intención: Explica por qué se hizo el cambio (no qué cambió).
    • Cuerpo: Contexto narrativo.
    • Trailers (Metadatos): Datos parseables por máquina.
• Vocabulario de Trailers (Tabla 1):
  • Constraint: Reglas que moldearon la decisión.
  • Rejected: Alternativas evaluadas y descartadas con sus razones.
  • Confidence: Nivel de confianza del autor (baja, media, alta).
  • Scope-risk: Radio de impacto (narrow, moderate, wide).
  • Reversibility: Facilidad de reversión.
  • Directive: Instrucciones para futuros modificadores.
  • Tested / Not-tested: Cobertura de pruebas y lagunas conocidas.
• Herramienta CLI: Se propone una herramienta de línea de comandos (lore) que permite a los agentes y humanos consultar el historial de decisiones (lore context, lore rejected, lore stale) sin necesidad de servidores o bases de datos externas.

3. Contribuciones Clave

1. Protocolo de Comunicación Inter-Agente: Lore es la primera propuesta que utiliza el mensaje de commit en sí mismo como un canal estructurado, parseable por máquinas y optimizado para la comunicación entre agentes de IA a lo largo del tiempo.
2. Cero Infraestructura: A diferencia de soluciones anteriores que requieren grafos de conocimiento, sistemas de memoria de agentes o archivos ADR (Architecture Decision Records) externos, Lore funciona con el stack de Git existente.
3. Resolución del Problema de Sincronización: Al estar incrustado en el commit (objeto inmutable), el conocimiento nunca se desincroniza con el código, a diferencia de la documentación externa o los ADRs que suelen quedar obsoletos.
4. Modelo de Consumo para Agentes: Define un flujo de trabajo donde los agentes pueden "cosechar" restricciones, filtrar patrones anti-éticos (alternativas rechazadas) y absorber directivas antes de modificar código.

4. Resultados y Validación Propuesta

El artículo es teórico y de propuesta, por lo que no presenta resultados empíricos de un estudio a largo plazo, pero ofrece un plan de validación y análisis comparativo:

• Análisis Comparativo: Lore se posiciona superior a:
  • ADRs: Lore captura decisiones de implementación (más frecuentes) y evita la desincronización.
  • Resúmenes de Diff por IA: Lore añade información que nunca estuvo en el diff (restricciones, alternativas rechazadas).
  • Code Digital Twin: Lore ofrece una solución ligera frente a la infraestructura pesada de los gemelos digitales.
• Plan de Validación Empírica: Se propone un experimento de 6 meses con dos equipos en el mismo proyecto (uno usando Lore, otro commits convencionales) para medir:
  • Tasa de éxito de tareas de agentes.
  • Tiempo hasta la solución correcta.
  • Tasa de re-proposición de enfoques ya rechazados.
  • Ciclos de revisión antes de fusionar (merge).

5. Significado e Impacto

• Cambio de Paradigma: Lore transforma el commit de un simple registro de cambios a un registro de decisiones vivas.
• Escalabilidad del Conocimiento: Permite que el conocimiento acumulado crezca orgánicamente con el código sin sobrecargar a los desarrolladores humanos, ya que la carga de estructuración recae en la configuración de los agentes de IA.
• Sostenibilidad del Código: Al preservar la "Sombra de la Decisión", Lore mitiga el riesgo de que los repositorios se conviertan en "cajas negras" incomprensibles para futuras generaciones de desarrolladores y agentes de IA.
• Minimalismo como Ventaja: La simplicidad del protocolo (solo texto y Git) asegura una adopción rápida y una compatibilidad universal, evitando la complejidad de sistemas centralizados de gestión de conocimiento.

En conclusión, Lore propone que la solución a la crisis de conocimiento en la era de la IA no es construir sistemas más complejos, sino estructurar mejor la información que ya estamos generando en cada commit, asegurando que el "por qué" de una decisión de código viaje con el código mismo.