La sesión es el mensaje de commit

Un desarrollador hereda un código base. git blame muestra 47 archivos modificados en un solo commit. El mensaje dice: “refactor auth module.” El autor del commit aparece como un desarrollador humano. El autor real fue un agente de programación que ejecutó durante 90 minutos, leyó 200 archivos, evaluó tres enfoques alternativos, rechazó dos de ellos por razones específicas, y produjo un conjunto de cambios que afecta cada endpoint de autenticación. Los 90 minutos de decisiones de diseño, alternativas rechazadas y casos límite discutidos desaparecieron. Git preservó qué cambió. Nada preservó por qué.

Mi publicación sobre deuda cognitiva nombró la brecha entre la velocidad de producción del agente y la velocidad de comprensión del desarrollador como “deuda cognitiva” — un pasivo que se acumula con cada commit sin revisar.¹ El proyecto Memento, que obtuvo 100 puntos en HN y 124 comentarios, plantea la siguiente pregunta: si la sesión contiene el razonamiento, ¿debería la sesión ser parte del commit?²

TL;DR

Git captura QUÉ cambió. Las sesiones de agentes capturan POR QUÉ. Cuando los agentes escriben código, la transcripción de la sesión es el verdadero documento de diseño, y cada flujo de trabajo que descarta la transcripción descarta la procedencia. Memento (una extensión de git de código abierto) adjunta transcripciones de sesiones de IA a los commits como git notes, creando una cadena de procedencia del commit al razonamiento. Claude Code nueva integración LSP agrega comprensión estructural del código que hace las transcripciones de sesión más precisas: go-to-definition reemplaza a grep, y las firmas de tipo reemplazan las suposiciones. A continuación: la brecha de procedencia, cuatro capas de metadatos de sesión, qué construye Memento, cómo LSP cambia la calidad de los datos de sesión, y prácticas mínimas de procedencia que puede implementar hoy.

La brecha de procedencia

Git rastrea cinco cosas sobre cada cambio: quién lo hizo, cuándo, qué archivos cambiaron, el diff y un mensaje de commit. Para código escrito por humanos, el mensaje de commit cierra la brecha entre el diff y la intención. Un buen mensaje explica por qué existe el cambio. Un mal mensaje (“fix stuff”) deja al revisor reconstruir la intención a partir del código.

El código escrito por agentes tiene una estructura de procedencia diferente. La intención no reside en la cabeza del desarrollador. La intención reside en la sesión: el prompt que inició la tarea, los archivos que el agente leyó, las alternativas que evaluó, las herramientas que invocó y la evidencia que citó al reportar la finalización. Un mensaje de commit que resume 90 minutos de razonamiento del agente en una línea descarta el 99,9% del contexto de decisión.

La pérdida no es teórica. Mi sistema de orquestación genera archivos de estado de sesión (jiro.state.json, jiro.progress.json) que registran cada finalización de historia, veredicto de revisor y resultado de la puerta de evidencia.³ Cuando un revisor pregunta “¿por qué el agente usó retroceso exponencial en lugar de circuit breaker?” el archivo de estado de sesión contiene la respuesta: el agente evaluó ambos patrones, encontró que el servicio upstream retorna 503s con reintentos posibles con un encabezado Retry-After, y seleccionó retroceso exponencial para respetar el valor del encabezado. El mensaje de commit dice “refactor: standardize retry patterns.” El estado de sesión dice por qué.

Sin procedencia de sesión, la revisión de código de cambios escritos por agentes se convierte en arqueología. El revisor lee el diff, reconstruye el razonamiento en reversa y forma una teoría sobre por qué existe el cambio. La teoría puede estar equivocada. El razonamiento real del agente está disponible, registrado en la transcripción de la sesión. El flujo de trabajo estándar de la industria (commit, push, revisar el diff) descarta el razonamiento.

El problema se multiplica con la composición de agentes. Mi sistema de orquestación genera subagentes especializados para revisión de código: un revisor de corrección, un revisor de seguridad, un revisor de convenciones.⁵ Cada subagente ejecuta su propia sesión, lee sus propios archivos, forma sus propias conclusiones. El agente padre agrega los veredictos. El mensaje de commit final dice “3 reviewers: approve.” Las tres sesiones de revisión individuales — cada una con hallazgos específicos, análisis de casos límite y justificación de aprobación — viven en transcripciones separadas que el commit nunca referencia. Cada capa de delegación del agente agrega otra capa de razonamiento invisible.

El problema de procedencia se conecta con tres patrones de fallo existentes. El firewall de fabricación identificó cómo los agentes publican afirmaciones no verificadas cuando no existe una puerta de salida.⁶ La procedencia de sesión habría detectado la fabricación antes: la transcripción de la sesión mostró al agente inventando una metodología de conteo de tokens que ningún humano revisó. El agente invisible documentó cómo las acciones del agente pasan desapercibidas sin instrumentación explícita.⁷ La procedencia de sesión es la pista de auditoría que genera la pila de visibilidad. El comentario público al NIST recomendó registro de auditoría estandarizado para acciones de agentes.⁹ Las git notes que almacenan transcripciones de sesión son una implementación de esa recomendación.

La puerta de evidencia en mi sistema de calidad requiere que el agente cite pruebas específicas para cada criterio de calidad: nombrar el patrón, explicar alternativas, listar casos límite, pegar la salida de las pruebas.¹⁰ La puerta de evidencia obliga al agente a generar datos de las capas de Razonamiento y Verificación que de otro modo no existirían. Sin la puerta, el agente reporta “listo” y la sesión contiene solo datos de Proceso (llamadas a herramientas). Con la puerta, la sesión contiene justificación explícita que un revisor puede verificar contra el código.

Git por sí solo no puede distinguir entre un commit de 47 archivos que representa 90 minutos de razonamiento cuidadoso y un commit de 47 archivos que representa un agente ejecutando sin restricciones durante 90 minutos sin revisión. La documentación de git describe las notes como “información extra sobre un objeto que puede adjuntarse sin cambiar el objeto en sí.”⁸ Las transcripciones de sesión encajan exactamente en la definición: información extra sobre la procedencia de un commit que no altera el hash del commit, el diff ni el historial.

La pregunta de Memento

El proyecto Memento responde a la brecha de procedencia con una extensión de git.² La herramienta captura transcripciones de sesiones de programación con IA y las adjunta a los commits como git notes, almacenadas en refs/notes/commits y refs/notes/memento-full-audit.

El flujo de trabajo: git memento init configura el repositorio. git memento commit <session-id> reemplaza a git commit, recuperando automáticamente la transcripción de la sesión del proveedor de IA configurado (Codex o Claude Code) y almacenándola como metadatos estructurados en el commit.

La discusión de 124 comentarios en HN reveló cuatro posiciones:

Posición 1: Las sesiones son contexto esencial. Las sesiones de agentes contienen el razonamiento que los mensajes de commit no pueden. Adjuntar sesiones a los commits preserva la cadena de procedencia. Los revisores pueden rastrear cualquier línea de código a través del commit, la sesión y el prompt original.

Posición 2: Las sesiones son ruido. Una transcripción de sesión de 90 minutos tiene miles de líneas de conversación. La mayoría es irrelevante para el conjunto de cambios final. Adjuntar la transcripción completa entierra la señal en ruido y hace la revisión más difícil, no más fácil.

Posición 3: Resúmenes, no transcripciones. La sesión debería destilarse en un resumen estructurado: descripción de la tarea, alternativas consideradas, justificación de decisiones, evidencia citada. El resumen preserva la procedencia sin el ruido. Memento genera resúmenes en markdown etiquetados con turnos de usuario y asistente.

Posición 4: Preocupaciones de privacidad y seguridad. Las transcripciones de sesión pueden contener claves API, URLs internas, código propietario de otros archivos, o contenido conversacional que el desarrollador no querría en un registro permanente de git. Las sesiones requieren sanitización antes de adjuntarse.

Las cuatro posiciones tienen mérito. El valor de procedencia de las sesiones es innegable. El problema del ruido es real. La preocupación por la privacidad es estructural. Memento aborda las posiciones 1 y 3 (almacenamiento de transcripciones con conversión a markdown) y la posición 4 (tratando las transcripciones como datos no confiables para generación de resúmenes). La posición 2 sigue siendo una pregunta de diseño abierta: ¿cuánto contexto de sesión es suficiente?

Una herramienta complementaria adopta un enfoque diferente al mismo problema. claude-replay convierte las transcripciones de sesión de Claude Code en reproducción tipo video, permitiendo a los revisores ver el trabajo del agente desarrollarse paso a paso en lugar de leer una transcripción estática.¹² Donde Memento responde “¿qué deberíamos almacenar?”, claude-replay responde “¿cómo deberíamos revisarlo?” Las dos herramientas abordan diferentes partes del flujo de trabajo de procedencia: Memento preserva los datos (almacenamiento), claude-replay hace los datos comprensibles (presentación). El hecho de que ambos proyectos surgieron independientemente en el mismo mes valida la tesis: los profesionales sienten la brecha de procedencia y están construyendo herramientas para cerrarla.

Cuatro capas de procedencia

Los metadatos de sesión de agentes se organizan en cuatro capas, cada una respondiendo una pregunta diferente sobre el cambio.

Cada capa agrega costo. Almacenar la capa de Intención completa (prompt original) es económico: un campo de texto. Almacenar la capa de Proceso completa (cada llamada a herramienta) para una sesión de 90 minutos genera megabytes de JSON. Almacenar la capa de Razonamiento requiere que el agente narre explícitamente su proceso de decisión, algo que la mayoría de los agentes no hace por defecto. Almacenar la capa de Verificación requiere integración con el ejecutor de pruebas y el sistema de revisión.

Mi sistema de orquestación captura las cuatro capas a través de diferentes mecanismos.³ La infraestructura de hooks que hace posible la captura abarca 84 hooks en 15 tipos de eventos.⁵ Intención: el hook UserPromptSubmit registra el prompt original. Proceso: los hooks PostToolUse registran cada llamada a herramienta y resultado. Razonamiento: la puerta de evidencia requiere que el agente cite justificación específica para cada criterio de calidad. Verificación: el archivo jiro.state.json registra la salida de pruebas y los veredictos de revisores.

Los hooks también rastrean qué skills invocó el agente y en qué secuencia.¹¹ Un commit que resulta del skill /review seguido del skill /test tiene un perfil de procedencia diferente al de una sesión única no estructurada. La secuencia de skills revela el patrón de flujo de trabajo: ¿revisión antes de pruebas, o pruebas antes de revisión? El orden importa para comprender la cobertura del aseguramiento de calidad. Los datos existen en múltiples archivos de estado. El problema es que ninguno se adjunta al commit de git.

LSP como puente de procedencia

La nueva integración LSP (Language Server Protocol) de Claude Code cambia la calidad de los datos de procedencia de sesión.⁴

Antes de LSP, Claude Code navegaba los códigos base mediante grep y lectura de archivos. Cuando el agente necesitaba encontrar la definición de una función, buscaba el nombre de la función en todos los archivos. La búsqueda retornaba resultados difusos: múltiples coincidencias, coincidencias parciales, archivos de prueba que contenían el nombre de la función en comentarios. El agente seleccionaba la coincidencia más probable. La transcripción de la sesión registraba: “buscó authenticate_user, encontrado en auth.py, test_auth.py y middleware.py.” Los datos de procedencia contienen la búsqueda, la ambigüedad y la mejor suposición del agente.

Con LSP, el agente llama a goToDefinition y recibe el archivo y número de línea exactos en ~50 milisegundos.⁴ La transcripción de la sesión registra: “authenticate_user definido en auth.py:47.” Los datos de procedencia son precisos, inequívocos y verificables por máquina. Un revisor que lee la sesión puede confiar en que el agente encontró la definición correcta, no una función con nombre similar en un módulo diferente.

La mejora se acumula a lo largo de la sesión. Un agente que lee 200 archivos usando grep genera datos de sesión llenos de “buscó X, encontró coincidencias potenciales A, B, C, seleccionó A.” Un agente que lee 200 archivos usando LSP genera datos de sesión que dicen “X definido en archivo:línea, referencias en archivo:línea, archivo:línea, archivo:línea.” La sesión respaldada por LSP es un mapa preciso de la comprensión del código por parte del agente. La sesión respaldada por grep es una aproximación difusa.

LSP agrega seis capacidades que mejoran la calidad de la procedencia:

La implicación para la procedencia: las transcripciones de sesión de agentes con LSP habilitado son más valiosas como documentos de diseño porque cada paso de navegación de código es verificable. Un revisor puede confirmar que la comprensión del código base por parte del agente fue correcta, no solo plausible.

El proyecto code-review-graph lleva la comprensión estructural más allá: un grafo de código persistente que sobrevive entre sesiones, reduciendo el costo en tokens de re-comprender el código base en cada invocación.¹³ Donde LSP proporciona consultas estructurales dentro de una sesión, un grafo persistente proporciona memoria estructural entre sesiones. Para la procedencia, la implicación es que los agentes futuros llevarán consigo no solo la transcripción de la sesión sino la comprensión estructural que produjo las decisiones. El grafo se convierte en otra capa de datos de procedencia: no solo “el agente encontró authenticate_user en auth.py:47” sino “el grafo de código del agente ya contenía la jerarquía de llamadas, así que omitió la navegación y fue directamente a la implementación.” El conocimiento previo del agente influye en sus decisiones, y ese conocimiento previo pertenece a la cadena de procedencia.

Cómo lucen los metadatos de sesión

Un ejemplo real de mi sistema de orquestación. Historia: “Agregar limitación de tasa al endpoint de autenticación.”

Capa de intención (del hook UserPromptSubmit):

Prompt: "Implement rate limiting on POST /auth/login.
  Use sliding window, 5 attempts per minute per IP.
  Return 429 with Retry-After header."

Capa de proceso (de los hooks PostToolUse):

Files read: 14 (auth/, middleware/, tests/)
Files written: 3 (rate_limiter.py, auth.py, test_rate_limit.py)
Bash commands: 7 (pytest x3, pip install x1, curl x3)
Duration: 23 minutes
Token usage: 87K input, 24K output

Capa de razonamiento (de la puerta de evidencia):

Pattern: Sliding window (token bucket rejected
  because per-IP granularity requires separate
  counters, sliding window handles this natively)
Edge cases: IPv6 normalization, proxy headers
  (X-Forwarded-For validated against trusted proxy list)

Capa de verificación (de jiro.state.json):

Tests: 12 passed, 0 failed, 0 skipped
Reviewers: correctness (approve), security (approve),
  conventions (approve with note: add docstring to
  rate_limiter.py:RateLimiter class)
Evidence gate: 6/6 criteria met

El mensaje de commit para el mismo cambio: “feat: add rate limiting to auth endpoint.” Catorce palabras. Los metadatos de sesión contienen 2.300 palabras de procedencia estructurada. La brecha entre el mensaje de commit y el contexto de sesión es de dos órdenes de magnitud.

El costo de la procedencia

La procedencia de sesión no es gratuita. Tres costos limitan la adopción.

Almacenamiento. Una sesión de agente de 90 minutos genera 500KB-2MB de transcripción sin procesar. Con 10 commits por día, la transcripción completa agrega 5-20MB diarios al repositorio de git. Las git notes almacenan los datos fuera del historial principal (no afectan el tamaño de git clone por defecto), pero la pista de auditoría en refs/notes/memento-full-audit se acumula. La conversión a markdown de Memento reduce el tamaño sin procesar aproximadamente un 60%.²

Privacidad. Las transcripciones de sesión contienen todo lo que el agente vio: contenido de archivos, variables de entorno, respuestas de API, mensajes de error con trazas de pila. Una transcripción adjunta a un repositorio público expone detalles internos de implementación. Memento trata las transcripciones como datos no confiables e instruye al modelo de resumen a ignorar instrucciones incrustadas, pero la transcripción sin procesar en la pista de auditoría completa requiere control de acceso.²

Relación señal-ruido. Una sesión de 90 minutos donde el agente lee 200 archivos para cambiar 12 contiene 188 archivos de datos de proceso irrelevantes. El desafío es distinguir la navegación (ruido) de los puntos de decisión (señal). El modelo de cuatro capas ayuda: Intención y Razonamiento son señal alta, Proceso es mixto, Verificación es señal alta. Un sistema de procedencia que almacena Intención y Razonamiento por defecto y Proceso bajo demanda reduce el ruido sin perder el contexto de decisión crítico.

Qué puede implementar hoy

Cuatro prácticas mínimas de procedencia que no requieren herramientas nuevas:

1. Mensajes de commit estructurados. Reemplace “refactor auth module” con un formato estructurado:

feat: add rate limiting to auth endpoint

Task: sliding window rate limiter, 5/min per IP
Alternatives: token bucket (rejected: per-IP overhead)
Evidence: 12 tests pass, 3 reviewers approve
Session: 23 min, 87K tokens, 14 files read

El formato es una versión manual de las cuatro capas de procedencia. El mensaje responde intención (tarea), razonamiento (alternativas) y verificación (evidencia) en cuatro líneas. No requiere herramientas.

2. Guarde las transcripciones de sesión junto a los commits. Después de una sesión de agente, exporte la transcripción a un archivo en el repositorio (por ejemplo, .sessions/2026-03-02-auth-rate-limit.md). Agregue el archivo a .gitignore para repositorios públicos o haga commit para repositorios internos. La transcripción está disponible para revisión sin infraestructura de git notes.

3. Etiquete los commits escritos por agentes. Use un trailer de git para marcar los commits que un agente produjo:

Agent: Claude Code (Opus)
Session-Duration: 23m
Files-Read: 14
Files-Written: 3

El trailer crea un registro analizable por máquina de la participación del agente. git log --grep="Agent: Claude Code" lista todos los commits escritos por agentes. Los metadatos habilitan herramientas futuras para reconstruir cadenas de procedencia sin anotación retroactiva.

4. Requiera puertas de evidencia para commits de agentes. Antes de que un agente haga commit, requiera que responda seis preguntas: ¿Qué patrón sigue el código? ¿Qué alternativas más simples existen? ¿Qué casos límite se manejan? ¿Pasan las pruebas? ¿Qué archivos revisó buscando regresiones? ¿El cambio resuelve el problema real?¹⁰ Las respuestas forman las capas de Razonamiento y Verificación. Sin la puerta, el agente reporta “listo” y la sesión contiene solo datos de Proceso. Con la puerta, cada commit genera procedencia estructurada como efecto secundario del aseguramiento de calidad.

La práctica de la puerta de evidencia se conecta con el argumento más amplio de procedencia. Un agente que debe justificar sus decisiones antes de hacer commit genera metadatos de sesión de mayor calidad que un agente que ejecuta sin restricciones. La puerta transforma la procedencia de un subproducto pasivo (registrar lo que sucedió) en una señal de calidad activa (requerir que el agente explique qué sucedió y por qué).

Conclusiones clave

Para gerentes de ingeniería: Cada commit escrito por un agente con un mensaje de una línea descarta el documento de diseño. La transcripción de la sesión contiene el razonamiento. Decida si ese razonamiento tiene valor para los flujos de trabajo de revisión de código, incorporación de personal e respuesta a incidentes de su equipo. Si la respuesta es sí, implemente mensajes de commit estructurados como mínimo.

Para desarrolladores: Cuando hereda código escrito por agentes, el mensaje de commit le dice qué cambió. La transcripción de la sesión (si se preservó) le dice por qué. Impulse la procedencia de sesión en el flujo de trabajo de agentes de su equipo. El proyecto Memento proporciona un enfoque nativo de git. Los mensajes de commit estructurados proporcionan un punto de partida sin infraestructura.

Para creadores de herramientas: La integración LSP hace las transcripciones de sesión más valiosas al reemplazar la navegación difusa basada en grep con referencias de código precisas y verificables. Cada mejora en la comprensión del código por parte del agente mejora la calidad de los datos de procedencia que generan las sesiones. Construya formatos de exportación que preserven las cuatro capas de procedencia.

Preguntas frecuentes

¿Qué es la procedencia de sesión? La procedencia de sesión es el registro del proceso de razonamiento de un agente de IA durante una sesión de programación: la tarea original, los archivos leídos, las alternativas evaluadas, las decisiones tomadas y la evidencia producida. La transcripción de la sesión captura el “por qué” que los mensajes de commit y los diffs no pueden.

¿Qué es Memento? Memento es una extensión de git de código abierto que captura transcripciones de sesiones de programación con IA y las adjunta a los commits como git notes. La herramienta soporta Codex y Claude Code, genera resúmenes en markdown y proporciona un GitHub Action para integración con PR.²

¿Cómo mejora LSP las sesiones de agentes? Language Server Protocol otorga a los agentes comprensión estructural del código: definiciones exactas, referencias tipadas, jerarquías de llamadas y diagnósticos en tiempo real. Las transcripciones de sesión de agentes con LSP habilitado contienen datos de navegación de código precisos y verificables en lugar de resultados difusos de grep.⁴

¿Deberían las transcripciones de sesión incluirse en los commits de git? La respuesta depende de los requisitos de privacidad del repositorio. Para repositorios internos, incluir las transcripciones preserva la procedencia. Para repositorios públicos, las git notes (que no se transfieren por defecto al clonar) o el almacenamiento separado con referencias al commit son enfoques más seguros.²

¿Cuánto almacenamiento requiere la procedencia de sesión? Una sesión de agente típica de 30 minutos genera 200KB-800KB de transcripción sin procesar. Las git notes almacenan los datos fuera de la base de datos principal de objetos, manteniendo los tamaños de git clone sin cambios por defecto. La conversión a markdown de Memento reduce el tamaño sin procesar aproximadamente un 60%. Para equipos que ejecutan 10-20 sesiones de agente por día, espere 2-10MB de datos de procedencia diarios, comparable a una captura de pantalla de resolución media por sesión.²

¿Cuál es la relación entre la observabilidad de agentes y la procedencia de sesión? La observabilidad de agentes monitorea lo que hacen los agentes en tiempo real: consumo de recursos, cumplimiento de políticas, comportamiento en tiempo de ejecución.⁷ La procedencia de sesión registra qué decidieron los agentes y por qué, después del hecho. La observabilidad responde “¿se está comportando correctamente el agente ahora mismo?” La procedencia responde “¿por qué el agente tomó esta decisión el martes pasado?” Los dos sistemas se complementan: la observabilidad detecta problemas en vivo, la procedencia los explica después.

Fuentes