A sessão é a mensagem de commit

Um desenvolvedor herda uma base de código. git blame mostra 47 arquivos alterados em um único commit. A mensagem diz: “refactor auth module.” O autor do commit é listado como um desenvolvedor humano. O autor real foi um agente de codificação que rodou por 90 minutos, leu 200 arquivos, avaliou três abordagens alternativas, rejeitou duas delas por razões específicas e produziu um conjunto de mudanças que toca cada endpoint de autenticação. Os 90 minutos de decisões de design, alternativas rejeitadas e casos extremos discutidos se foram. O Git preservou o que mudou. Nada preservou o porquê.

Meu post sobre dívida cognitiva nomeou a lacuna entre a velocidade de produção do agente e a velocidade de compreensão do desenvolvedor como “dívida cognitiva” — um passivo que se acumula a cada commit não revisado.¹ O projeto Memento, que coletou 100 pontos no HN e 124 comentários, faz a próxima pergunta: se a sessão contém o raciocínio, a sessão deveria fazer parte do commit?²

Resumo

O Git captura O QUE mudou. Sessões de agentes capturam O PORQUÊ. Quando agentes escrevem código, a transcrição da sessão é o verdadeiro documento de design, e todo fluxo de trabalho que descarta a transcrição descarta a procedência. O Memento (uma extensão open-source do Git) anexa transcrições de sessões de IA a commits como git notes, criando uma cadeia de procedência do commit ao raciocínio. A nova integração LSP do Claude Code adiciona compreensão estrutural de código que torna as transcrições de sessão mais precisas: go-to-definition substitui o grep, e assinaturas de tipo substituem suposições. A seguir: a lacuna de procedência, quatro camadas de metadados de sessão, o que o Memento constrói, como o LSP muda a qualidade dos dados de sessão e práticas mínimas de procedência que você pode implementar hoje.

A lacuna de procedência

O Git rastreia cinco coisas sobre cada mudança: quem a fez, quando, quais arquivos mudaram, o diff e uma mensagem de commit. Para código escrito por humanos, a mensagem de commit faz a ponte entre o diff e a intenção. Uma boa mensagem explica por que a mudança existe. Uma mensagem ruim (“fix stuff”) deixa o revisor reconstruir a intenção a partir do código.

Código escrito por agentes tem uma estrutura de procedência diferente. A intenção não vive na cabeça do desenvolvedor. A intenção vive na sessão: o prompt que iniciou a tarefa, os arquivos que o agente leu, as alternativas que avaliou, as ferramentas que chamou e as evidências que citou ao reportar a conclusão. Uma mensagem de commit resumindo 90 minutos de raciocínio do agente em uma linha descarta 99,9% do contexto de decisão.

A perda não é teórica. Meu sistema de orquestração gera arquivos de estado de sessão (jiro.state.json, jiro.progress.json) que registram cada conclusão de história, veredito de revisor e resultado de porta de evidência.³ Quando um revisor pergunta “por que o agente usou exponential backoff em vez de circuit breaker?” o arquivo de estado de sessão contém a resposta: o agente avaliou ambos os padrões, descobriu que o serviço upstream retorna 503s com retry possível com um cabeçalho Retry-After e selecionou exponential backoff para honrar o valor do cabeçalho. A mensagem de commit diz “refactor: standardize retry patterns.” O estado de sessão diz por quê.

Sem procedência de sessão, a revisão de código de mudanças feitas por agentes se torna arqueologia. O revisor lê o diff, faz engenharia reversa do raciocínio e forma uma teoria sobre por que a mudança existe. A teoria pode estar errada. O raciocínio real do agente está disponível, registrado na transcrição da sessão. O fluxo de trabalho padrão da indústria (commit, push, revisar o diff) descarta o raciocínio.

O problema se multiplica com a composição de agentes. Meu sistema de orquestração cria subagentes especializados para revisão de código: um revisor de corretude, um revisor de segurança, um revisor de convenções.⁵ Cada subagente roda sua própria sessão, lê seus próprios arquivos, forma suas próprias conclusões. O agente principal agrega os vereditos. A mensagem final de commit diz “3 reviewers: approve.” As três sessões individuais de revisão — cada uma contendo descobertas específicas, análise de casos extremos e justificativa de aprovação — vivem em transcrições separadas que o commit nunca referencia. Cada camada de delegação de agente adiciona outra camada de raciocínio invisível.

O problema de procedência se conecta a três padrões de falha existentes. O firewall de fabricação identificou como agentes publicam alegações não verificadas quando nenhuma porta de saída existe.⁶ A procedência de sessão teria detectado a fabricação mais cedo: a transcrição da sessão mostrou o agente inventando uma metodologia de contagem de tokens que nenhum humano revisou. O agente invisível documentou como ações de agentes passam sem monitoramento sem instrumentação explícita.⁷ A procedência de sessão é a trilha de auditoria que a camada de visibilidade gera. O comentário público ao NIST recomendou registro padronizado de auditoria para ações de agentes.⁹ Git notes armazenando transcrições de sessão são uma implementação dessa recomendação.

A porta de evidência no meu sistema de qualidade exige que o agente cite provas específicas para cada critério de qualidade: nomear o padrão, explicar alternativas, listar casos extremos, colar a saída dos testes.¹⁰ A porta de evidência força o agente a gerar dados das camadas de Raciocínio e Verificação que, de outra forma, não existiriam. Sem a porta, o agente reporta “concluído” e a sessão contém apenas dados de Processo (chamadas de ferramenta). Com a porta, a sessão contém justificativa explícita que um revisor pode verificar contra o código.

O Git sozinho não consegue distinguir entre um commit de 47 arquivos que representa 90 minutos de raciocínio cuidadoso e um commit de 47 arquivos que representa um agente rodando sem restrições por 90 minutos sem revisão. A documentação do Git descreve notes como “informações extras sobre um objeto que podem ser anexadas sem alterar o próprio objeto.”⁸ Transcrições de sessão se encaixam exatamente nessa definição: informações extras sobre a procedência de um commit que não alteram o hash do commit, o diff ou o histórico.

A questão Memento

O projeto Memento responde à lacuna de procedência com uma extensão do Git.² A ferramenta captura transcrições de sessões de codificação com IA e as anexa a commits como git notes, armazenadas em refs/notes/commits e refs/notes/memento-full-audit.

O fluxo de trabalho: git memento init configura o repositório. git memento commit <session-id> substitui git commit, recuperando automaticamente a transcrição da sessão do provedor de IA configurado (Codex ou Claude Code) e armazenando-a como metadados estruturados no commit.

A discussão de 124 comentários no HN revelou quatro posições:

Posição 1: Sessões são contexto essencial. Sessões de agentes contêm o raciocínio que mensagens de commit não conseguem transmitir. Anexar sessões a commits preserva a cadeia de procedência. Revisores podem rastrear qualquer linha de código de volta ao commit, à sessão e ao prompt original.

Posição 2: Sessões são ruído. Uma transcrição de sessão de 90 minutos são milhares de linhas de conversa. A maior parte é irrelevante para o conjunto final de mudanças. Anexar a transcrição completa enterra o sinal no ruído e torna a revisão mais difícil, não mais fácil.

Posição 3: Resumos, não transcrições. A sessão deveria ser destilada em um resumo estruturado: descrição da tarefa, alternativas consideradas, justificativa da decisão, evidências citadas. O resumo preserva a procedência sem o ruído. O Memento gera resumos em markdown rotulados com turnos de usuário e assistente.

Posição 4: Preocupações com privacidade e segurança. Transcrições de sessão podem conter chaves de API, URLs internas, código proprietário de outros arquivos ou conteúdo conversacional que o desenvolvedor não gostaria em um registro permanente do Git. Sessões requerem sanitização antes da anexação.

Todas as quatro posições têm mérito. O valor de procedência das sessões é inegável. O problema do ruído é real. A preocupação com privacidade é estrutural. O Memento aborda as posições 1 e 3 (armazenamento de transcrições com conversão para markdown) e a posição 4 (tratando transcrições como dados não confiáveis para geração de resumos). A posição 2 permanece uma questão de design em aberto: quanto contexto de sessão é suficiente?

Uma ferramenta complementar adota uma abordagem diferente para o mesmo problema. O claude-replay converte transcrições de sessão do Claude Code em reprodução semelhante a vídeo, permitindo que revisores assistam ao trabalho do agente se desenrolar passo a passo em vez de ler uma transcrição estática.¹² Onde o Memento responde “o que devemos armazenar?” o claude-replay responde “como devemos revisar?” As duas ferramentas abordam partes diferentes do fluxo de procedência: o Memento preserva os dados (armazenamento), o claude-replay torna os dados compreensíveis (apresentação). O fato de ambos os projetos terem surgido independentemente no mesmo mês valida a tese: profissionais sentem a lacuna de procedência e estão construindo ferramentas para fechá-la.

Quatro camadas de procedência

Metadados de sessão de agentes se organizam em quatro camadas, cada uma respondendo a uma pergunta diferente sobre a mudança.

Cada camada adiciona custo. Armazenar a camada de Intenção completa (prompt original) é barato: um campo de texto. Armazenar a camada de Processo completa (cada chamada de ferramenta) para uma sessão de 90 minutos gera megabytes de JSON. Armazenar a camada de Raciocínio requer que o agente narre explicitamente seu processo de decisão, o que a maioria dos agentes não faz por padrão. Armazenar a camada de Verificação requer integração com o executor de testes e o sistema de revisão.

Meu sistema de orquestração captura todas as quatro camadas através de mecanismos diferentes.³ A infraestrutura de hooks que torna a captura possível abrange 84 hooks em 15 tipos de evento.⁵ Intenção: o hook UserPromptSubmit registra o prompt original. Processo: hooks PostToolUse registram cada chamada de ferramenta e resultado. Raciocínio: a porta de evidência exige que o agente cite justificativa específica para cada critério de qualidade. Verificação: o arquivo jiro.state.json registra a saída dos testes e vereditos dos revisores.

Os hooks também rastreiam quais skills o agente invocou e em qual sequência.¹¹ Um commit que resulta da skill /review seguida da skill /test tem um perfil de procedência diferente de um commit de uma única sessão não estruturada. A sequência de skills revela o padrão do fluxo de trabalho: revisão antes dos testes, ou testes antes da revisão? A ordem importa para entender a cobertura de garantia de qualidade. Os dados existem em múltiplos arquivos de estado. O problema é que nenhum deles se anexa ao commit do Git.

LSP como ponte de procedência

A nova integração LSP (Language Server Protocol) do Claude Code muda a qualidade dos dados de procedência de sessão.⁴

Antes do LSP, o Claude Code navegava em bases de código através de grep e leitura de arquivos. Quando o agente precisava encontrar a definição de uma função, ele buscava o nome da função em todos os arquivos. A busca retornava resultados difusos: múltiplas correspondências, correspondências parciais, arquivos de teste contendo o nome da função em comentários. O agente selecionava a correspondência mais provável. A transcrição da sessão registrava: “buscou por authenticate_user, encontrado em auth.py, test_auth.py e middleware.py.” Os dados de procedência contêm a busca, a ambiguidade e o melhor palpite do agente.

Com LSP, o agente chama goToDefinition e recebe o arquivo e número de linha exatos em ~50 milissegundos.⁴ A transcrição da sessão registra: “authenticate_user definido em auth.py:47.” Os dados de procedência são precisos, inequívocos e verificáveis por máquina. Um revisor lendo a sessão pode confiar que o agente encontrou a definição correta, não uma função com nome similar em um módulo diferente.

A melhoria se acumula ao longo da sessão. Um agente que lê 200 arquivos usando grep gera dados de sessão cheios de “buscou por X, encontrou correspondências potenciais A, B, C, selecionou A.” Um agente que lê 200 arquivos usando LSP gera dados de sessão que dizem “X definido em arquivo:linha, referências em arquivo:linha, arquivo:linha, arquivo:linha.” A sessão com suporte LSP é um mapa preciso da compreensão de código do agente. A sessão baseada em grep é uma aproximação difusa.

O LSP adiciona seis capacidades que melhoram a qualidade da procedência:

A implicação para procedência: transcrições de sessão de agentes com LSP habilitado são mais valiosas como documentos de design porque cada passo de navegação de código é verificável. Um revisor pode confirmar que a compreensão do agente sobre a base de código estava correta, não apenas plausível.

O projeto code-review-graph leva a compreensão estrutural mais adiante: um grafo de código persistente que sobrevive entre sessões, reduzindo o custo de tokens para re-compreender a base de código a cada invocação.¹³ Onde o LSP fornece consultas estruturais dentro de uma sessão, um grafo persistente fornece memória estrutural entre sessões. Para procedência, a implicação é que agentes futuros carregarão não apenas a transcrição da sessão, mas a compreensão estrutural que produziu as decisões. O grafo se torna outra camada de dados de procedência: não apenas “o agente encontrou authenticate_user em auth.py:47” mas “o grafo de código do agente já continha a hierarquia de chamadas, então ele pulou a navegação e foi direto para a implementação.” O conhecimento prévio do agente influencia suas decisões, e esse conhecimento prévio pertence à cadeia de procedência.

Como são os metadados de sessão

Um exemplo real do meu sistema de orquestração. História: “Adicionar rate limiting ao endpoint de autenticação.”

Camada de intenção (do 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."

Camada de processo (dos 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

Camada de raciocínio (da porta de evidência):

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)

Camada de verificação (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

A mensagem de commit para a mesma mudança: “feat: add rate limiting to auth endpoint.” Quatorze palavras. Os metadados de sessão contêm 2.300 palavras de procedência estruturada. A lacuna entre mensagem de commit e contexto de sessão é de duas ordens de magnitude.

O custo da procedência

Procedência de sessão não é gratuita. Três custos restringem a adoção.

Armazenamento. Uma sessão de agente de 90 minutos gera 500KB-2MB de transcrição bruta. Com 10 commits por dia, a transcrição completa adiciona 5-20MB diários ao repositório Git. Git notes armazenam os dados fora do histórico principal (não afetam o tamanho do git clone por padrão), mas a trilha de auditoria em refs/notes/memento-full-audit se acumula. A conversão para markdown do Memento reduz o tamanho bruto em aproximadamente 60%.²

Privacidade. Transcrições de sessão contêm tudo que o agente viu: conteúdo de arquivos, variáveis de ambiente, respostas de API, mensagens de erro com stack traces. Uma transcrição anexada a um repositório público expõe detalhes de implementação interna. O Memento trata transcrições como dados não confiáveis e instrui o modelo de resumo a ignorar instruções embutidas, mas a transcrição bruta na trilha de auditoria completa requer controle de acesso.²

Relação sinal-ruído. Uma sessão de 90 minutos onde o agente lê 200 arquivos para alterar 12 contém 188 arquivos de dados de processo irrelevantes. O desafio é distinguir navegação (ruído) de pontos de decisão (sinal). O modelo de quatro camadas ajuda: Intenção e Raciocínio são de alto sinal, Processo é misto, Verificação é de alto sinal. Um sistema de procedência que armazena Intenção e Raciocínio por padrão e Processo sob demanda reduz o ruído sem perder o contexto crítico de decisão.

O que você pode implementar hoje

Quatro práticas mínimas de procedência que não requerem novas ferramentas:

1. Mensagens de commit estruturadas. Substitua “refactor auth module” por um formato estruturado:

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

O formato é uma versão manual das quatro camadas de procedência. A mensagem responde intenção (tarefa), raciocínio (alternativas) e verificação (evidência) em quatro linhas. Nenhuma ferramenta necessária.

2. Salve transcrições de sessão junto com commits. Após uma sessão de agente, exporte a transcrição para um arquivo no repositório (ex.: .sessions/2026-03-02-auth-rate-limit.md). Adicione o arquivo ao .gitignore para repositórios públicos ou faça commit para repositórios internos. A transcrição fica disponível para revisão sem infraestrutura de git notes.

3. Marque commits feitos por agentes. Use um trailer do Git para marcar commits que um agente produziu:

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

O trailer cria um registro analisável por máquina do envolvimento do agente. git log --grep="Agent: Claude Code" lista todos os commits feitos por agentes. Os metadados possibilitam que ferramentas futuras reconstruam cadeias de procedência sem anotação retroativa.

4. Exija portas de evidência para commits de agentes. Antes de um agente fazer commit, exija que ele responda seis perguntas: Qual padrão o código segue? Quais alternativas mais simples existem? Quais casos extremos são tratados? Os testes passam? Quais arquivos você verificou para regressões? A mudança resolve o problema real?¹⁰ As respostas formam as camadas de Raciocínio e Verificação. Sem a porta, o agente reporta “concluído” e a sessão contém apenas dados de Processo. Com a porta, cada commit gera procedência estruturada como efeito colateral da garantia de qualidade.

A prática da porta de evidência se conecta ao argumento mais amplo de procedência. Um agente que deve justificar suas decisões antes de fazer commit gera metadados de sessão de maior qualidade do que um agente que roda sem restrições. A porta transforma procedência de um subproduto passivo (registrando o que aconteceu) em um sinal ativo de qualidade (exigindo que o agente explique o que aconteceu e por quê).

Principais conclusões

Para gerentes de engenharia: Cada commit feito por agente com uma mensagem de uma linha descarta o documento de design. A transcrição da sessão contém o raciocínio. Decida se esse raciocínio tem valor para os fluxos de revisão de código, onboarding e resposta a incidentes da sua equipe. Se a resposta for sim, implemente mensagens de commit estruturadas no mínimo.

Para desenvolvedores: Quando você herda código escrito por agentes, a mensagem de commit diz o que mudou. A transcrição da sessão (se preservada) diz por quê. Defenda a procedência de sessão no fluxo de trabalho de agentes da sua equipe. O projeto Memento oferece uma abordagem nativa do Git. Mensagens de commit estruturadas fornecem um ponto de partida sem infraestrutura.

Para construtores de ferramentas: A integração LSP torna transcrições de sessão mais valiosas ao substituir navegação difusa baseada em grep por referências de código precisas e verificáveis. Cada melhoria na compreensão de código do agente melhora a qualidade dos dados de procedência que as sessões geram. Construa formatos de exportação que preservem as quatro camadas de procedência.

Perguntas frequentes

O que é procedência de sessão? Procedência de sessão é o registro do processo de raciocínio de um agente de IA durante uma sessão de codificação: a tarefa original, arquivos lidos, alternativas avaliadas, decisões tomadas e evidências produzidas. A transcrição da sessão captura o “porquê” que mensagens de commit e diffs não conseguem.

O que é o Memento? Memento é uma extensão open-source do Git que captura transcrições de sessões de codificação com IA e as anexa a commits como git notes. A ferramenta suporta Codex e Claude Code, gera resumos em markdown e fornece uma GitHub Action para integração com PRs.²

Como o LSP melhora sessões de agentes? O Language Server Protocol dá aos agentes compreensão estrutural de código: definições exatas, referências tipadas, hierarquias de chamadas e diagnósticos em tempo real. Transcrições de sessão de agentes com LSP habilitado contêm dados de navegação de código precisos e verificáveis em vez de resultados difusos de grep.⁴

Transcrições de sessão devem ser commitadas no Git? A resposta depende dos requisitos de privacidade do repositório. Para repositórios internos, fazer commit das transcrições preserva a procedência. Para repositórios públicos, git notes (que não são transferidas por padrão no clone) ou armazenamento separado com referências ao commit são abordagens mais seguras.²

Quanto armazenamento a procedência de sessão requer? Uma sessão típica de agente de 30 minutos gera 200KB-800KB de transcrição bruta. Git notes armazenam os dados fora do banco de objetos principal, mantendo os tamanhos de git clone inalterados por padrão. A conversão para markdown do Memento reduz o tamanho bruto em aproximadamente 60%. Para equipes rodando 10-20 sessões de agente por dia, espere 2-10MB de dados de procedência diários, comparável a uma captura de tela de resolução média por sessão.²

Qual é a relação entre observabilidade de agentes e procedência de sessão? Observabilidade de agentes monitora o que os agentes fazem em tempo real: consumo de recursos, conformidade com políticas, comportamento em tempo de execução.⁷ Procedência de sessão registra o que os agentes decidiram e por quê, após o fato. Observabilidade responde “o agente está se comportando corretamente agora?” Procedência responde “por que o agente tomou essa decisão na terça-feira passada?” Os dois sistemas se complementam: observabilidade detecta problemas ao vivo, procedência os explica depois.

Fontes