O problema silencioso com o código escrito por IA: a intenção evapora

Há um problema com o código escrito por IA que ninguém comenta ainda, porque a maioria de nós não tem usado agentes de IA tempo suficiente para que isso nos afete.

O problema é o seguinte: os agentes de IA sabem exatamente por que tomaram cada decisão. E então a sessão termina.

O que acontece com o código humano

Quando humanos escrevem código, a intenção vaza por toda parte. Está na mensagem de commit ("Adicionar campo de telefone para a implementação do 2FA"), na descrição do PR, na thread do Slack que a precedeu, no comentário inline que explica o caso de borda estranho. Você pode reconstruir por que uma decisão foi tomada meses depois porque a trilha de evidências é espessa.

Isso funciona porque os humanos entendem que seu código vai durar mais do que sua memória de escrevê-lo.

O que acontece com o código escrito por IA

Um agente de IA tem clareza perfeita sobre por que está fazendo cada mudança — até que a conversa termine.

Execute git blame seis meses depois:

3e7a991 (Claude Code  2025-10-14)  user_tier_v2 VARCHAR(20)

Mensagem de commit: "Atualizar esquema"

O agente sabia por que. Ele adicionou user_tier_v2 para suportar uma flag de transição durante uma migração de preços. Ele armazenou o nível original para que você pudesse preencher descontos sem tocar no histórico de faturamento. Foi uma decisão cuidadosa e intencional — e esse contexto está completamente perdido.

Isso não é um hipotético. Se você tem usado ferramentas de codificação de IA por mais de alguns meses, você já encontrou essa barreira. Você pode apenas não ter percebido ainda.

O momento do pandas

Quando o pandas foi lançado, os cientistas de dados estavam fazendo manipulação de dados com loops de Python puro e NumPy. O problema não era que era impossível — era que não havia uma infraestrutura compartilhada para isso, então todos estavam reinventando os mesmos padrões de forma inadequada.

O pandas se tornou uma infraestrutura essencial. Não uma funcionalidade, não algo desejável — infraestrutura.

Acho que o rastreamento de mudanças no código é o mesmo problema para o desenvolvimento na era da IA. Neste momento, cada equipe que usa agentes de IA intensivamente está lentamente acumulando um código cheio de decisões que faziam perfeito sentido quando o agente as tomou e estão se tornando cada vez mais opacas para todos que tocam o código depois.

Selvedge

Eu construí Selvedge para capturar esse raciocínio antes que ele desapareça.

É um servidor MCP. Agentes de IA (começando com Claude Code) o chamam enquanto trabalham para registrar eventos de mudança estruturados — o que mudou, quando, qual agente, qual commit e, crucialmente: por que.

$ selvedge blame users.stripe_customer_id

  users.stripe_customer_id
  Alterado     2026-03-14 11:22:01
  Agente       claude-code
  Commit      9c3f441
  Raciocínio   O usuário pediu para adicionar cobrança Stripe — precisa do ID do cliente para vincular contas a assinaturas sem armazenar detalhes do cartão localmente.

Esse campo Raciocínio é capturado do contexto do agente no momento, antes que a sessão termine. Não é gerado pelo Selvedge — o Selvedge apenas captura o que o agente já sabe e armazena em algum lugar que você pode consultar mais tarde.

Como funciona

A configuração é feita em três etapas:

1. Instale:

pip install selvedge
cd seu-projeto && selvedge init

1. Adicione à sua configuração do Claude Code (~/.claude/config.json):

{
  "mcpServers": {
    "selvedge": { "command": "selvedge-server" }
  }
}

1. Adicione algumas linhas ao seu CLAUDE.md do projeto:

Você tem acesso ao Selvedge para rastreamento de mudanças.
Chame selvedge.log_change imediatamente após adicionar, modificar ou remover
qualquer coluna de DB, tabela, função, endpoint de API, dependência ou variável de ambiente.
Defina o raciocínio para o pedido original do usuário ou o problema que está sendo resolvido.

A partir de então, seu agente registra mudanças automaticamente enquanto trabalha.

Consultando seu histórico

A CLI é construída para como você realmente investiga bases de código:

# O que mudou na tabela users nos últimos 30 dias?
selvedge diff users --since 30d

# Qual foi a última mudança em payments.amount e por quê?
selvedge blame payments.amount

# Tudo relacionado à funcionalidade de cobrança Stripe
selvedge search "stripe"

# Com que frequência meu agente está realmente registrando mudanças?
selvedge stats

Há também um sistema de conjunto de mudanças — você pode marcar mudanças relacionadas sob um slug compartilhado ("add-stripe-billing") e reconstruir o escopo completo de uma funcionalidade em várias entidades depois:

selvedge history --changeset add-stripe-billing

Preenchendo projetos existentes

Se você já tem um projeto com arquivos de migração, não precisa começar do zero:

selvedge import ./migrations/

Ele analisa DDL SQL bruto e arquivos Python do Alembic e preenche seu histórico de esquema. Não tão rico quanto o raciocínio capturado, mas melhor do que nada.

O que vem a seguir

Atualmente, o Selvedge usa SQLite local, que funciona muito bem para desenvolvedores individuais e pequenas equipes com um volume compartilhado. A Fase 3 é um backend PostgreSQL e uma API REST HTTP para que equipes possam compartilhar um histórico entre máquinas — esse é o caminho para tornar isso uma ferramenta adequada para equipes.

A percepção central que continuo voltando: o diff é trabalho do git. O porquê é trabalho do Selvedge.

Se você tem usado Claude Code ou Cursor intensivamente e sentiu essa dor, eu adoraria saber como você tem lidado com isso (ou se você apenas tem convivido com isso). E se você experimentar o Selvedge, feedback sobre o que está faltando seria muito útil.

Versão atual: v0.3.1 — lançada hoje (23 de abril de 2026). É uma versão de estabilização: conexão com re-tentativa e PRAGMA busy_timeout = 5000 para que gravações simultâneas sejam seguras sob contenção (testado contra 8 threads escrevendo)