A melhor explicação do seu código está enterrada em um log de chat

Você passou quarenta e cinco minutos com Claude projetando um circuito de retry. Você explicou os modos de falha, rejeitou o backoff exponencial porque esconde a pressão em cascata, decidiu pelo token-bucket rate limiting com jitter e gerou uma implementação funcional. A explicação foi clara, o raciocínio foi sólido e o código realmente passou nos testes.

Então você fechou a aba.

Duas semanas depois, um colega pergunta por que a lógica de retry usa jitter em vez de backoff exponencial. Você abre uma nova sessão do Claude e reconstrói o argumento de memória. A nova explicação é parecida, mas não idêntica. Você criou uma segunda tradição oral ligeiramente diferente. Nenhuma delas é pesquisável. Nenhuma delas é revisável em um pull request. Ambas desaparecerão quando você deixar a empresa.

Isso não é um problema de ferramentas. É um erro de categoria. Tratamos conversas com LLM como rascunhos privados quando, na verdade, são o mais perto que a maioria dos engenheiros já chegou do literate programming.

O que Knuth quis dizer, e por que os LLMs entregaram isso acidentalmente

Donald Knuth definiu literate programming em 1984 como o ato de escrever programas como obras de literatura. Código e documentação são tecidos juntos em uma única narrativa. O leitor segue o raciocínio do autor, vê as alternativas consideradas e entende por que a forma final existe.

Por quarenta anos, o literate programming permaneceu como uma prática de nicho. Ferramentas como WEB e CWEB exigiam disciplina. A maioria dos desenvolvedores escrevia o código em um arquivo e a documentação em outro, e os dois se separavam imediatamente.

Uma conversa com um LLM é literate programming por acidente. Você declara o problema em prosa. O modelo faz perguntas de clarificação. Você refina os constraints. Ele propõe código. Você rejeita a proposta e explica por quê. Ele revisa. O artefato final não é apenas o bloco de código. É todo o thread: as abordagens descartadas, os trade-offs, as suposições de domínio.

O problema é que o meio é efêmero. Interfaces de chat são projetadas para conclusão de tarefas, não para preservação de conhecimento. Uma vez que a sessão termina, a narrativa fica congelada em âmbar, impesquisável, sem controle de versão e de propriedade de um fornecedor.

Por que logs de chat superam a documentação tradicional para decisões complexas

A documentação tradicional descreve o estado final. Responde “o quê”. Um bom log de chat responde “por quê”, que é a pergunta mais difícil e a que apodrece mais rápido.

Considere um registro típico de decisões de arquitetura. Ele pode dizer: “Escolhemos PostgreSQL em vez de DynamoDB para o serviço de inventário por causa dos requisitos de consistência forte.” Isso é uma conclusão. Não te diz nada sobre as queries que eram lentas demais, o lag de replicação que era aceitável ou o vendor lock-in que foi debatido e descartado.

Um thread do Claude contém tudo isso. Contém as iterações de esquema que falharam, os planos de query que te surpreenderam e o momento em que você percebeu que o index composto tinha que cobrir o filtro de status. É um registro de decisões com contexto completo.

O problema é que o contexto está preso em um formato conversacional. Rolar por um thread de cem turns para encontrar a única percepção sobre o design de indexes é miserável. O conhecimento está lá, mas não é acessível.

Os três modos de falha do Chat-as-Docs

Tratar logs de chat brutos como documentação falha de maneiras previsíveis. Cada modo de falha tem uma correção, mas você precisa ser intencional.

Hallucination drift. Claude inventa APIs, cita papers inexistentes e propõe designs com confiança que ignoram seus constraints reais. Um log de chat preservado como documentação preserva as hallucinations ao lado da sabedoria. Se você não marcar quais partes foram verificadas e quais eram especulativas, o próximo leitor trata tudo como evangelho.

Narrative sprawl. Uma boa conversa divaga. Você explora becos sem saída, se distrai com edge cases e volta atrás. Essa divagação é valiosa para a compreensão, mas terrível para referência. Um novo engenheiro que precisa da política de retry não precisa ler o desvio de vinte minutos sobre TCP congestion control.

Vendor lock-in. Sua documentação vive no banco de dados da Anthropic, por trás da interface de busca deles, sujeita à política de retenção deles. Se a conta expirar ou a interface mudar, seus docs desaparecem. Documentação que você não pode grepar não é documentação.

Como extrair um documento durável de um chat efêmero

A solução é tratar o chat como um primeiro rascunho, não como um artefato final. Você extrai, verifica e publica. O workflow é simples e leva cerca de dez minutos por decisão significativa.

Passo um: etiquete os turns. Durante a conversa, marque as decisões-chave. Uso uma convenção simples. Quando o Claude produz um bloco de código que pretendo manter, respondo com KEEP: <razão de uma linha>. Quando propõe algo que rejeito, respondo com REJECT: <razão>. Essas tags tornam a extração trivial.

Passo dois: extraia para markdown. Após a sessão, copie o thread em um arquivo markdown e elimine o ruído. Remova as saudações, os preenchimentos “deixe-me pensar” e os turns em que vocês dois estavam confusos. Mantenha a declaração do problema, as alternativas consideradas, a decisão final e o código verificado. O resultado deve ler como uma nota técnica, não como uma transcrição.

Aqui está um script que automatiza a extração se você usar a API do Claude ou exportar sua conversa como JSON:

#!/usr/bin/env python3
"""
Extract a readable technical note from a Claude conversation export.
Expects Anthropic's conversation JSON format.
"""

import json
import argparse
from pathlib import Path


def extract_note(conversation_path: Path, output_path: Path) -> None:
    with open(conversation_path) as f:
        data = json.load(f)

    turns = data.get("chat_messages", [])
    lines = []

    for turn in turns:
        sender = turn.get("sender", "unknown")
        text = turn.get("text", "").strip()

        if not text:
            continue

        # Skip pleasantries and meta-turns
        if any(phrase in text.lower() for phrase in [
            "hello", "how can i help", "you're welcome", "glad i could help"
        ]):
            continue

        if sender == "human":
            lines.append(f"**Q:** {text}\n")
        else:
            lines.append(f"**A:** {text}\n")

    with open(output_path, "w") as f:
        f.write("# Technical Note: Extracted from Claude Session\n\n")
        f.write("\n".join(lines))


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--input", type=Path, required=True)
    parser.add_argument("--output", type=Path, required=True)
    args = parser.parse_args()
    extract_note(args.input, args.output)

Passo três: verifique cada bloco de código. Execute o código extraído. Se ele não compilar ou não passar nos testes, corrija no markdown e anote a correção. O documento extraído deve ser uma fonte de verdade, não uma transcrição de uma conversa que pode ter contido erros.

Passo quatro: commite no repository. Armazene o markdown em docs/decisions/ ou docs/notes/ ao lado do código que descreve. Dê a ele um nome de arquivo significativo: retry-circuit-jitter-over-exponential.md, não claude-chat-july-19.md. Adicione-o ao mesmo pull request da mudança de código, ou abra um PR de acompanhamento imediatamente. Se os docs não estiverem em controle de versão, eles não existem.

Quando isso funciona e quando não funciona

Essa abordagem é excelente para decisões complexas e ambíguas onde o raciocínio importa tanto quanto o resultado. Design de circuitos, estratégias de migration de esquemas, políticas de API versioning e trade-offs de desempenho são todos bons candidatos.

Não funciona para documentação de referência. Um log de chat sobre como se autenticar com a API interna é um péssimo substituto para uma spec OpenAPI estruturada e um exemplo de cURL. Use a ferramenta certa para o trabalho.

Também não funciona sem curadoria. Despejar logs de chat brutos em um wiki não é documentação. É acumulação. Os dez minutos de extração e edição são inegociáveis. Se você os pular, produzirá lixo pesquisável.

Um ponto de partida prático

Você não precisa de uma nova ferramenta. Você precisa de um hábito.

Da próxima vez que tiver uma sessão longa e produtiva com o Claude sobre uma decisão de design não trivial, exporte o thread antes de fechar a aba. Gaste dez minutos editando-o em uma nota markdown que responda a três perguntas: Qual problema estávamos resolvendo? Quais alternativas consideramos e rejeitamos? No que decidimos e por quê?

Commite essa nota no seu repo. Vincule-a ao comentário de código acima da função que descreve. O próximo engenheiro que tocar nesse código agradecerá, e não precisará abrir o Claude para reconstruir seu raciocínio.

Seu chat com o Claude pode se tornar documentação. Só precisa que você o trate como código: extraído, verificado, versionado e mantido.