whyso — o que o git blame não mostra

git blame mostra quem, quando e o que foi alterado. whyso mostra por quê.

O problema

Quando queremos entender por que uma linha de código ficou do jeito que ficou, o que podemos fazer é olhar o git blame e a mensagem de commit.

$ git blame internal/handler/page.go
a3f1b2c (parkjunwoo 2026-03-08) func CreatePage(c *gin.Context) {

Quem, quando e o que foi alterado aparecem. Por que foi alterado não aparece.

“Mas é só escrever o motivo na mensagem de commit”, dirão alguns. A realidade é outra:

fix: update handler
refactor: clean up
wip

Escrever boas mensagens de commit é uma questão de disciplina. Por mais que a equipe defina convenções, poucos param às três da manhã consertando um bug para pensar: “Preciso registrar o contexto e a justificativa desta mudança na mensagem de commit”.

Mas na era do AI coding, o cenário é diferente. O motivo da alteração já está registrado.

Os dados de sessão do Claude Code

O Claude Code salva todas as conversas em arquivos JSONL sob ~/.claude/projects/. Cada registro contém a mensagem do usuário, a resposta da IA, as chamadas de tool_use (Write, Edit, Bash) e a cadeia de parentUuid que os conecta.

Usuário: "comece a implementar o comando whyso validate"
  → IA: Write internal/crosscheck/crosscheck.go
    → IA: Edit internal/crosscheck/crosscheck.go
      → IA: "pacote crosscheck inicial criado — validação de correspondência SSaC↔OpenAPI operationId"

Por que o arquivo foi criado e por que foi modificado ficam registrados na própria conversa. É mais rico do que uma mensagem de commit e não precisa ser escrito intencionalmente — basta ter feito a conversa para que seja registrado automaticamente.

whyso analisa esses dados e extrai o histórico de alterações por arquivo.

A vida inteira de um arquivo fica visível

file: internal/crosscheck/crosscheck.go
created: 2026-03-08T14:23:01Z
history:
  - timestamp: 2026-03-08T14:23:01Z
    session: 09351222-d7be-41fe-994f-87c2d7067e5d
    user_request: "comece a implementar o comando whyso validate"
    answer: "pacote crosscheck inicial criado — validação de correspondência SSaC↔OpenAPI operationId"
    tool: Write

  - timestamp: 2026-03-09T10:15:33Z
    session: 4e9b4e5e-3a50-43f2-be6e-e5db228ecc3b
    user_request: "adicione validação para verificar se a coluna x-sort existe no DDL"
    answer: "validação cruzada coluna x-sort/x-filter → DDL adicionada"
    tool: Edit

  - timestamp: 2026-03-10T09:41:22Z
    session: b2e43b4f-cb21-4286-975d-1eb9de8a16c0
    user_request: "adicione também a validação cruzada da especificação Func"
    answer: "validação cruzada @call ↔ especificação Func (número e tipo de argumentos) adicionada"
    tool: Edit

Por que foi criado e como evoluiu a partir de cada solicitação. A vida inteira de um único arquivo fica visível.

Por que isso é necessário

A lacuna do code review

Durante a revisão de um PR, há momentos em que nos perguntamos: “Por que essa alteração foi feita?”. Se o motivo não está na mensagem de commit, precisamos perguntar ao autor. Se o autor não se lembra, precisamos reler o código para tentar deduzir.

No ambiente de AI coding, a resposta para essa pergunta está nos dados de sessão. whyso extrai essa resposta.

Onboarding

A maneira mais rápida de um novo membro da equipe entender a base de código é saber “por que o código ficou assim”. O git log é uma lista cronológica de alterações, e a documentação é um snapshot do estado atual. O histórico por arquivo do whyso mostra o que fica entre eles — a cadeia de intenções.

Registro pessoal

Mesmo desenvolvendo sozinho, chega o momento em que você não consegue se lembrar por que escreveu algo de determinada forma três meses atrás. whyso restaura a conversa entre você do passado e a IA. O contexto que você não escreveu na mensagem de commit está lá.

A relação com o git blame

whyso não substitui o git blame. Complementa.

Se o git blame é o “registro oficial” baseado em commits, o whyso é o “diário de trabalho” baseado em conversas. O contexto que não cabia no registro oficial fica preservado no diário de trabalho.

A estrutura em que a IA lê seus próprios registros

O caso de uso mais interessante do whyso não é o ser humano lendo — é a própria IA lendo.

O Claude Code esquece tudo ao final de uma sessão. Na próxima sessão, ao abrir o mesmo projeto, não há nada: por que eu escrevi aquilo ontem, quais opções foram consideradas e descartadas, em que contexto o usuário fez o pedido. Só resta ler o código e tentar deduzir.

Imagine adicionar uma linha ao CLAUDE.md:

Antes de modificar qualquer arquivo, execute `whyso history <file>`. Se houver histórico, leia antes de modificar.

O que essa linha muda:

Saber quais alterações não devem ser desfeitas

Você está lendo um arquivo para modificá-lo e encontra um código que parece estranho. Olhando apenas o estado atual, você quer corrigir o que parece um erro. Mas se o histórico do whyso registrar “o usuário solicitou explicitamente essa estrutura, e o motivo não foi performance mas legibilidade”, você não toca.

Não propor novamente opções já descartadas

Em uma sessão anterior houve a conversa “vamos tentar a abordagem A?” → “não, vamos com B”. A IA da nova sessão não sabe disso. E propõe A de novo. Para o usuário, isso é frustrante. Com whyso, a IA já sabe quais direções foram consideradas e rejeitadas.

Dar continuidade ao contexto de trabalhos encadeados

“Continue o refactoring de ontem” — hoje isso exige olhar o diff e deduzir. Com o histórico do whyso, a IA lê diretamente as solicitações do usuário da sessão anterior e o raciocínio por trás das decisões da IA. Em vez de dedução, o trabalho contínuo se baseia em fatos.

O registro acumula entre sessões

Com essa estrutura, o histórico do whyso se acumula a cada sessão. O motivo das alterações desta sessão também é transmitido para a IA da próxima sessão. O problema da falta de memória entre sessões é resolvido no nível do arquivo — sem nenhum sistema de memória externo.

O que está registrado no whyso é trabalho da IA. Mas a IA não consegue se lembrar disso. O registro que ela mesma criou é o que ela mais precisa. Esse é o ponto singular do whyso quando combinado com ferramentas de AI coding.

Para o ser humano, whyso é “uma ferramenta que deixa automaticamente boas mensagens de commit”. Para a IA, whyso é memória que atravessa sessões.

Como usar

Instalação

go install github.com/park-jun-woo/whyso/cmd/whyso@latest

Consultar o histórico de um arquivo

# Arquivo único
whyso history README.md

# Diretório inteiro
whyso history internal/ --all

# Saída espelhando a estrutura de arquivos
whyso history . --all --output .file-histories/

# Formato JSON
whyso history README.md --format json

Lista de sessões

whyso sessions

Como funciona

Rastreamento reverso pela cadeia parentUuid

Todos os registros do JSONL estão conectados por uuid e parentUuid. A partir do tool_use que modificou um arquivo, subindo pela cadeia de parentUuid, chegamos à solicitação original do usuário que desencadeou a modificação.

user message (uuid: A)          ← "adicione validação para verificar se a coluna x-sort existe no DDL"
  → assistant tool_use (parentUuid: A)
    → tool_result (parentUuid: B)
      → assistant Edit (parentUuid: C)  ← motivo desta modificação = A

Como há mensagens do tipo tool_result no meio, extraindo apenas aquelas em que type == "user" e content é uma string, encontramos a solicitação real do usuário.

Decisões de design

Rastreia apenas Write/Edit. As tool_use Write e Edit do Claude Code incluem explicitamente o caminho do arquivo e o conteúdo da alteração. Manipulações de arquivo via comandos Bash (rm, mv, cp) são detectadas por heurística, mas Write/Edit são o principal alvo de rastreamento. O Claude Code é projetado para usar Write/Edit ao modificar arquivos, então esses dois comandos já capturam a maioria das alterações.

Inclui subagentes. Quando o Claude Code lida com tarefas complexas, pode criar subagentes. As sessões dos subagentes são salvas dentro do diretório da sessão pai. whyso também analisa essas sessões de subagentes para construir um histórico completo.

Atualizações incrementais. Ao usar a opção --output para gravar em um diretório, sessões já analisadas são ignoradas. Mesmo que o número de sessões cresça para centenas, não é necessário reanalisar tudo do zero a cada vez.

Números

Resultado do rastreamento do próprio processo de desenvolvimento do whyso com o whyso:

17 sessões, histórico de alterações de 480 arquivos extraído. Em cada arquivo, registrado “por que foi criado e por que foi alterado”.

Limitações

• Exclusivo para Claude Code. Dados de sessão de outras ferramentas de AI coding têm formatos diferentes. Atualmente, apenas o formato JSONL do Claude Code é suportado.
• Rastreia apenas arquivos de texto. As tool_use Write/Edit têm como alvo arquivos de texto. Alterações em imagens e arquivos binários não são rastreadas.
• Os dados de sessão precisam estar localmente. Os arquivos de sessão precisam estar em ~/.claude/projects/. Se foram excluídos ou o trabalho foi feito em outra máquina, esses registros não existem.

Resumo

Na era de escrever código junto com a IA, o motivo das alterações não precisa mais depender apenas das mensagens de commit. A própria conversa é o registro, e a partir desse registro é possível extrair automaticamente o histórico de alterações por arquivo.

Se git blame mostra “quem, quando e o que foi alterado”, whyso mostra “por quê foi alterado”.

Código: github.com/park-jun-woo/whyso