La sesión es el mensaje de commit

Un desarrollador hereda una base de código. 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 codificació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 denominó 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 recolectó 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 notas de Git, creando una cadena de procedencia del commit al razonamiento. La nueva integración LSP de Claude Code añade 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, lo que 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”) obliga al revisor a 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 vive en la cabeza del desarrollador. La intención vive 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 sola 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 puerta de evidencia.³ Cuando un revisor pregunta “¿por qué el agente usó backoff exponencial en lugar de circuit breaker?” el archivo de estado de sesión contiene la respuesta: el agente evaluó ambos patrones, descubrió que el servicio upstream devuelve errores 503 reintentables con un encabezado Retry-After, y seleccionó backoff 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, realiza ingeniería inversa del razonamiento 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) desecha 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 conteniendo 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 añade 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 de los agentes pasan sin monitoreo 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 notas de Git 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 resultados de pruebas.¹⁰ La puerta de evidencia obliga al agente a generar datos de las capas de Razonamiento y Verificación que de otra forma 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 ejecutándose sin restricciones durante 90 minutos sin revisión. La documentación de Git describe las notas como “información extra sobre un objeto que puede adjuntarse sin cambiar el objeto en sí.”⁸ Las transcripciones de sesión encajan exactamente en esa 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 codificación con IA y las adjunta a los commits como notas de Git, 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 son miles de líneas de conversación. La mayor parte es irrelevante para el conjunto final de cambios. Adjuntar la transcripción completa entierra la señal en ruido y dificulta la revisión, no la facilita.

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 la decisión, 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 la 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?

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 añade 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, lo cual la mayoría de los agentes no hacen 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 una justificación específica para cada criterio de calidad. Verificación: el archivo jiro.state.json registra los resultados de pruebas y 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 un commit de una sesión única no estructurada. La secuencia de skills revela el patrón del flujo de trabajo: ¿revisión antes de pruebas, o pruebas antes de revisión? El orden importa para entender la cobertura de aseguramiento de calidad. Los datos existen en múltiples archivos de estado. El problema es que ninguno de ellos 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 las bases de código 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 devolvía 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: “searched for authenticate_user, found in auth.py, test_auth.py, and 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 exacto y el número de línea en ~50 milisegundos.⁴ La transcripción de la sesión registra: “authenticate_user defined at 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 “searched for X, found potential matches A, B, C, selected A.” Un agente que lee 200 archivos usando LSP genera datos de sesión que dicen “X defined at file:line, references at file:line, file:line, file:line.” 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 añade seis capacidades que mejoran la calidad de la procedencia:

La implicación para la procedencia: las transcripciones de sesión de agentes habilitados con LSP 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 agente sobre la base de código era correcta, no solo plausible.

Cómo se ven los metadatos de sesión

Un ejemplo real de mi sistema de orquestación. Historia: “Añadir 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 su 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 añade 5-20MB diarios al repositorio Git. Las notas de Git 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 en aproximadamente un 60%.²

Privacidad. Las transcripciones de sesión contienen todo lo que el agente vio: contenidos 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 de implementación interna. 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 alta señal, Proceso es mixto, Verificación es alta señal. Un sistema de procedencia que almacena Intención y Razonamiento por defecto y Proceso bajo demanda reduce el ruido sin perder el contexto crítico de decisión.

Lo que 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 se requiere ninguna herramienta.

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). Añada 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 notas de Git.

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 permiten que herramientas futuras reconstruyan 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ó para detectar 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 se ejecuta sin restricciones. La puerta transforma la procedencia de un subproducto pasivo (registrar lo que sucedió) en una señal activa de calidad (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 revisión de código, incorporación de nuevos miembros y 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é. Abogue por 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 que las transcripciones de sesión sean 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 codificació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 codificación con IA y las adjunta a los commits como notas de Git. La herramienta soporta Codex y Claude Code, genera resúmenes en markdown y proporciona una GitHub Action para integración con PRs.²

¿Cómo mejora LSP las sesiones de agentes? Language Server Protocol brinda 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 habilitados con LSP 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 commits de Git? La respuesta depende de los requisitos de privacidad del repositorio. Para repositorios internos, hacer commit de las transcripciones preserva la procedencia. Para repositorios públicos, las notas de Git (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 típica de agente de 30 minutos genera 200KB-800KB de transcripción sin procesar. Las notas de Git almacenan los datos fuera de la base de datos principal de objetos, manteniendo sin cambios los tamaños de git clone por defecto. La conversión a markdown de Memento reduce el tamaño sin procesar en 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 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