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 alterações que toca cada endpoint de autenticação. Os 90 minutos de decisões de design, alternativas rejeitadas e casos extremos discutidos desapareceram. 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 pergunta seguinte: se a sessão contém o raciocínio, a sessão deveria fazer parte do commit?²

TL;DR

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 git open-source) 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 alteração: quem a fez, quando, quais arquivos mudaram, o diff e uma mensagem de commit. Para código escrito por humanos, a mensagem de commit preenche a lacuna entre o diff e a intenção. Uma boa mensagem explica por que a alteração 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, veredicto de revisor e resultado de portão de evidência.³ Quando um revisor pergunta “por que o agente usou backoff exponencial em vez de circuit breaker?”, o arquivo de estado da sessão contém a resposta: o agente avaliou ambos os padrões, descobriu que o serviço upstream retorna 503s com um header Retry-After, e selecionou backoff exponencial para honrar o valor do header. A mensagem de commit diz “refactor: standardize retry patterns.” O estado da sessão diz o porquê.

Sem procedência de sessão, a revisão de código de alterações 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 alteração 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) joga o raciocínio fora.

O problema se multiplica com a composição de agentes. Meu sistema de orquestração gera 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 veredictos. A mensagem final do 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 afirmações não verificadas quando nenhum portão 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 despercebidas sem instrumentação explícita.⁷ A procedência de sessão é a trilha de auditoria que a pilha de visibilidade gera. O comentário público ao NIST recomendou logging de auditoria padronizado para ações de agentes.⁹ Git notes armazenando transcrições de sessão são uma implementação dessa recomendação.

O portão 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 saída de testes.¹⁰ O portão 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 o portão, o agente reporta “concluído” e a sessão contém apenas dados de Processo (chamadas de ferramentas). Com o portão, 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ção extra sobre um objeto que pode ser anexada sem alterar o objeto em si.”⁸ Transcrições de sessão se encaixam exatamente na definição: informação extra sobre a procedência de um commit que não altera o hash do commit, o diff ou o histórico.

A Questão do Memento

O projeto Memento responde à lacuna de procedência com uma extensão 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 expressar. Anexar sessões a commits preserva a cadeia de procedência. Revisores podem rastrear qualquer linha de código de volta pelo commit, pela sessão e pelo prompt original.

Posição 2: Sessões são ruído. Uma transcrição de sessão de 90 minutos tem milhares de linhas de conversa. A maior parte é irrelevante para o conjunto final de alterações. 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 git permanente. 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ção com conversão para markdown) e a posição 4 (tratando transcrições como dados não confiáveis para geração de resumo). A posição 2 permanece uma questão de design em aberto: quanto contexto de sessão é suficiente?

Quatro Camadas de Procedência

Os metadados de sessão de agente se organizam em quatro camadas, cada uma respondendo a uma pergunta diferente sobre a alteração.

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 exige 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: o portão 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 saída de testes e veredictos de revisores.

Os hooks também rastreiam quais skills o agente invocou e em qual sequência.¹¹ Um commit que resulta da skill /review seguida pela skill /test tem um perfil de procedência diferente de um commit de uma sessão única não estruturada. A sequência de skills revela o padrão de 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 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 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 imprecisos: 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 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 o 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 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 LSP é um mapa preciso da compreensão de código do agente. A sessão com grep é uma aproximação imprecisa.

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.

Como São os Metadados de Sessão

Um exemplo real do meu sistema de orquestração. História: “Adicionar limitação de taxa 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 (do portão 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 alteração: “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 a mensagem de commit e o 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 diariamente ao repositório git. Git notes armazenam os dados fora do histórico principal (não afetam o tamanho de 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 internos de implementação. O Memento trata transcrições como dados não confiáveis e instrui o modelo de resumo a ignorar instruções incorporadas, 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 alto sinal, Processo é misto, Verificação é 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 exigem 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 (task), raciocínio (alternatives) e verificação (evidence) 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 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 legível por máquina do envolvimento do agente. git log --grep="Agent: Claude Code" lista todos os commits feitos por agentes. Os metadados permitem que ferramentas futuras reconstruam cadeias de procedência sem anotação retroativa.

4. Exija portões 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 alteração resolve o problema real?¹⁰ As respostas formam as camadas de Raciocínio e Verificação. Sem o portão, o agente reporta “concluído” e a sessão contém apenas dados de Processo. Com o portão, cada commit gera procedência estruturada como efeito colateral da garantia de qualidade.

A prática do portão de evidência se conecta ao argumento mais amplo de procedência. Um agente que precisa 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. O portão transforma a procedência de um subproduto passivo (registrar o que aconteceu) em um sinal ativo de qualidade (exigir 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 feito por agente, a mensagem de commit diz o que mudou. A transcrição da sessão (se preservada) diz o porquê. Defenda a procedência de sessão no fluxo de trabalho com agentes da sua equipe. O projeto Memento oferece uma abordagem nativa do git. Mensagens de commit estruturadas oferecem 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 imprecisa 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. Construam formatos de exportação que preservem as quatro camadas de procedência.

FAQ

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 expressar.

O que é o Memento? O Memento é uma extensão git open-source 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 imprecisos 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, commitar 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 agente e procedência de sessão? Observabilidade de agente 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 fez essa escolha na terça-feira passada?” Os dois sistemas se complementam: observabilidade detecta problemas ao vivo, procedência os explica depois.

Fontes