Devemos revisitar a programação literária na era dos agentes

 (silly.business)
14 pontos por GN⁺ 2026-03-11 | 2 comentários | Compartilhar no WhatsApp
  • Programação literária (Literate Programming), que entrelaça código e explicações em linguagem natural em uma única narrativa, não se difundiu amplamente por causa do custo de manter em paralelo tanto o código quanto a explicação; porém, agentes de codificação com IA podem eliminar esse trabalho central
  • O org-babel do Emacs Org Mode permite programação literária multilíngue, mas em projetos grandes o incômodo do processo de extração do código-fonte (tangling) é uma limitação
  • Ao instruir um agente a escrever um runbook baseado em arquivos Org, torna-se possível um fluxo de trabalho em que a intenção é descrita em texto, blocos de código são executados de forma interativa e os resultados são salvos no documento
  • Como o agente sincroniza automaticamente explicações, código e tangling, desaparece o esforço de reescrever a explicação quando o código muda, aproveitando justamente a capacidade em que os LLMs mais se destacam: tradução e resumo
  • Em um movimento em que o papel do engenheiro está mudando de escrever código para ler código, a utilidade prática de uma base de código narrativa mantida por agentes surge como questão central

Conceito e limitações da programação literária

  • Programação literária (Literate Programming) é a ideia de misturar código e explicações em linguagem natural para que até leitores sem conhecimento prévio possam ler a base de código como uma narrativa única e entender como ela funciona
  • É uma ideia atraente, mas na prática impõe o custo de manter duas narrativas paralelas, o próprio código e sua explicação, e essa é a principal razão pela qual sua adoção ficou limitada
  • A forma mais comum no trabalho prático são os notebooks Jupyter da comunidade de ciência de dados, onde explicações, computação e resultados aparecem juntos no navegador

Emacs Org Mode e programação literária

  • O Emacs Org Mode oferece suporte a programação literária multilíngue por meio do pacote org-babel, permitindo executar linguagens arbitrárias e capturar os resultados no documento
    • Ainda assim, esse padrão permaneceu como um uso de nicho entre um pequeno grupo de entusiastas
  • Se um arquivo Org for usado como fonte da verdade (source of truth) em um grande projeto de software, o código-fonte passa a ser na prática um artefato compilado, e após cada edição é preciso extrair o código ("tangle") e colocá-lo no destino
    • Isso pode ser automatizado, mas quando um usuário ou agente edita o código-fonte real, é fácil que ele seja sobrescrito no próximo tangle

Padrões de uso antes dos agentes

  • Houve resultados bons o suficiente ao usar programação literária para gerenciar configurações pessoais (bookkeeping personal configuration), de modo que a ideia não foi abandonada nem antes da chegada dos LLMs
  • Um padrão de usar o Org Mode para testes manuais e tomada de notas: em vez da linha de comando, escrever e executar comandos no editor, editando cada etapa até que esteja correta e então salvando o resultado no próprio lugar
    • "Se você combina escrita de notas com execução de testes, quando o teste termina as notas são geradas de graça"

Um novo fluxo de trabalho com agentes

  • Agentes de codificação como Claude e Kimi entendem muito bem a sintaxe do Org Mode, e o Org é uma linguagem de marcação tolerante, algo com que os LLMs lidam muito bem
    • A gramática vasta do Org Mode é uma desvantagem para humanos, mas não é um problema para modelos de linguagem
  • Ao pedir ao agente para escrever um runbook em Org durante um teste funcional:
    • a explicação traz a reflexão do modelo sobre a intenção de cada etapa
    • os blocos de código podem, após revisão, ser executados interativamente um a um ou todos de uma vez como um script
    • os resultados são salvos abaixo do código, como em um notebook Jupyter
  • É possível editar a explicação e pedir ao modelo que atualize o código, ou editar o código e deixar que o modelo reflita esse significado na explicação, ou ainda o agente alterar ambos ao mesmo tempo
    • o problema de manter narrativas paralelas desaparece

O trabalho central que os agentes eliminam

  • Ao deixar o tangling a cargo do agente, o problema de extração do código também é resolvido
  • Com um arquivo AGENTS.md, é possível instruir o agente a tratar o arquivo Org Mode como fonte da verdade, sempre escrever explicações e executar o tangle antes de rodar
    • O agente é bom em tudo isso e nunca se cansa de reescrever explicações depois de modificar o código
  • O agente elimina o trabalho extra fundamental que impediu a adoção ampla da programação literária, aproveitando justamente as habilidades de tradução e resumo em que os LLMs mais se destacam

Benefícios esperados

  • A base de código pode ser exportada em vários formatos para facilitar a leitura
    • Isso é especialmente importante se o papel principal do engenheiro está mudando de escrever para ler
  • Não há dados que comprovem isso, mas especula-se que a qualidade do código gerado também possa melhorar, porque a narrativa que explica a intenção de cada bloco aparece junto com o código no contexto
  • Até agora isso não foi tentado em bases de código grandes e completas; está sendo usado em fluxos de trabalho de testes e documentação de processos manuais

Limitações do Org Mode e alternativas

  • O formato Org é uma limitação por estar fortemente integrado ao Emacs, e há muito tempo existe a convicção de que o Org precisa sair de dentro do Emacs
  • Seria tentador recomendar Markdown como alternativa, mas o Markdown não tem bons recursos para incluir metadados
    • O conceito de Properties do Org Mode permite manipular documentos programaticamente com Emacs Lisp, e agora LLMs podem escrever funções personalizadas específicas para aquele documento em Emacs Lisp na seção de file variables
    • O Markdown não tem um recurso como os header arguments do Org Mode para especificar detalhes de execução dos blocos de código, como onde executar ou em qual máquina remota
  • O que empolga não é a implementação específica do Emacs, e sim a própria ideia

Pergunta central

  • "Com agentes, pode se tornar prático ter uma base de código em larga escala que possa ser lida como uma narrativa e em que uma máquina incansável mantenha sincronizadas as mudanças no código e suas explicações?"

Leituras relacionadas

2 comentários

 
GN⁺ 2026-03-11
Comentários no Hacker News

  • Acho que a forma mais simples é fazer o próprio LLM deixar seus comentários
    Assim, quando o LLM reler o código depois, ele usa os próprios comentários como referência, funcionando como uma espécie de memória de longo prazo just-in-time
    Em <summary>, ele colocaria o resumo; em <remarks>, os motivos e o contexto; em <params>, as restrições; e os comentários inline seriam minimizados
    Desse jeito, ao revisar um PR, dá para verificar diretamente em <remarks> o processo de raciocínio do LLM e identificar facilmente onde ele entendeu algo diferente da intenção

    • Pela minha experiência, os comentários adicionados por LLM são verbosos demais e infantis
      No fim, só poluem o próprio contexto com informação inútil e pioram a compreensão
      Ainda está longe do nível humano de letramento
    • Para humanos, muitas vezes os comentários de LLM parecem barulhentos e cheios de informação desnecessária
      Mas, quando o LLM volta a ler o mesmo código, é justamente nesse tipo de comentário que ele trava, então talvez essa informação tenha valor
    • Humanos lembram por que escreveram o código, mas LLMs têm janela de contexto limitada, então esse tipo de informação desaparece rápido
      Por isso, esses comentários acabam preservando essa memória
    • Isso me faz pensar que comentários escritos por agentes deveriam ter assinatura, para que possam ser distinguidos

  • Acho que linguagens de programação surgiram por causa da ambiguidade da linguagem natural
    Então comentários em código também acabam sendo ambíguos e, como não são executados, envelhecem rápido
    LLMs são bons em traduzir código, mas ainda parece difícil transformar prompts em linguagem natural em código
    Um bom código deve expressar claramente a intenção, e muitos comentários podem ser sinal de baixa qualidade do código

    • Se código bom bastasse, seria possível olhar só o código-fonte sem ler documentação
      Mas um bom software também precisa incluir boa documentação
      Programação literária é uma escrita centrada na explicação, mais do que nos detalhes de implementação
    • Assim como surgiu o estilo da linguagem jurídica, quanto mais específico for o prompt, melhor ele funciona
      O código define o “como” de forma estreita, mas a linguagem natural pode expressar mais o “o quê”, deixando espaço para o LLM propor métodos melhores
    • Código e documentação devem funcionar juntos como códigos de correção de erro mútuos
      É preciso haver informação redundante para detectar e corrigir erros
    • Linguagens de programação também não são totalmente inequívocas
      Elas apenas impõem regras que reduzem a liberdade de interpretação
      Às vezes, metáfora ou ambiguidade são formas mais adequadas de expressão
    • Eu não peço ao LLM para fazer programação literária, mas faço com que ele explique os trade-offs
      Se você der código de exemplo e documentação como template, as alucinações diminuem

  • Há pesquisas mostrando que comentários em estilo de programação literária ajudam humanos a entender código
    Pesquisadores do Google testaram se LLMs conseguem atualizar esse tipo de comentário e se isso ajuda a compreensão humana
    A conclusão foi que comentários em nível de bloco explicando a intenção são os mais eficazes
    (Referência: artigo arXiv de 2024 "Natural Language Outlines for Code")

  • Um fenômeno interessante recente é que, antes, as pessoas tinham preguiça de escrever README ou documentos de arquitetura para humanos
    Agora, se for para o LLM, elas fazem isso com muito mais disposição

    • Humanos quase não leem documentação e só perguntam quando precisam
      Mas LLMs consultam a documentação a cada tarefa, então a motivação para documentar fica muito mais forte
    • Hábitos que antes eram ignorados como “higiene de engenharia” agora trazem grandes ganhos para agentes
      Mensagens de commit e registros como ADR, que humanos não leem, são todos lidos por LLMs
      No fim, esses hábitos acabam ajudando também quem está entrando na equipe
    • Já ouvi isso antes
      Pessoas que aprenderam a falar com computadores e deixaram de aprender a falar com humanos acabaram mais para trás depois de se formar
    • Documentação apodrece mais rápido que código
      Afinal, para o código funcionar, a documentação não precisa estar correta
      Por isso, muitas vezes parece melhor olhar diretamente o código do que a documentação
    • Talvez esse tipo de hábito tenha sido mais natural do ponto de vista de gestão

  • Acho que a combinação de programação literária leve com linguagens orientadas por convenção combina bem com a era dos agentes
    Linguagens como Go, com compilação rápida e guia de estilo claro, são boas
    Se o agente consultar o Google Go Style Guide ao escrever código, o resultado costuma ser bem bom

  • Como LLMs são modelos de linguagem, vale a pena investir em escrita clara
    Mesmo sem chegar à programação literária, bons nomes, docstrings, assinaturas de tipos e comentários explicando o “porquê” são importantes
    No fim, o essencial é criar padrões de comunicação para humanos e LLMs ao mesmo tempo

    • O necessário é um ponto intermediário entre docstring e programação literária
      Documentos que expliquem a estrutura de alto nível em nível de arquivo, diretório e projeto são especialmente importantes
      Mas esses conceitos atravessam vários arquivos, então sempre há o problema de onde escrever isso e da sincronização entre documentação e código
    • Acho que o próprio Notebook já é uma forma de programação literária

  • Nos últimos 10 anos, venho escrevendo quase todo o meu código em estilo de programação literária
    Criei o nbdev para gerenciar juntos, com base em notebooks, código, documentação e testes
    Mais recentemente, criei uma ferramenta chamada Solveit, com integração de LLM, e estou usando isso na empresa toda
    (link do Solveit)
    Programação literária também é útil para trabalhos fora da programação

    • Mas o nome Solveit é comum demais, então é difícil pesquisar, e o vídeo de apresentação é longo demais
      Seria bom adicionar uma demo curta ou capturas de tela

  • A ideia de usar LLM para detectar automaticamente inconsistências entre comentários e código é interessante
    Documentação inevitavelmente se desalinhará do código com o tempo, então, se isso puder ser detectado automaticamente, haverá muito valor aí
    Dá até para imaginar uma startup baseada nisso

    • Desde 2023, já surgiram mais de 10 startups nessa área (quem escreveu isso é technical writer)
    • Era uma ideia que eu já tinha pensado antes: um sistema que obriga DocString/JSDoc em todo diretório, módulo, classe e função
      As mudanças começam com um PR de documentação, e o desenvolvedor reflete isso no código
      Na revisão, documentação e código aparecem lado a lado para validação
      Também seria projetado para permitir navegação de contexto por links entre documentos
    • Já existem startups semelhantes, como Promptless.ai
    • Também daria para conectar IA ao CI e detectar periodicamente inconsistências entre documentação e código ou deriva de arquitetura
      Ex.: GitHub gh-aw, Continue.dev
    • Mas também fica a dúvida: “não bastaria simplesmente perguntar para a IA o que o código faz?”

  • A estrutura em par entre código de teste e código de produção é útil, como a escrituração por partidas dobradas na contabilidade
    Os testes explicam a intenção do código, e o código complementa o sentido dos testes
    Na revisão, se um lado estiver confuso, basta olhar o outro
    A desvantagem é o aumento na quantidade de código, mas o ganho de legibilidade compensa

  • Eu também escrevi recentemente sobre coding orientado por intenção, e isso toca nessa mesma discussão
    (link do blog)
    O importante é que a codebase possa ser transformada em formatos mais fáceis de ler
    No futuro, pessoas sem formação na área vão se aproximar mais do código, e a inclusão de linguagem natural ajudará muito na produtividade e no aprendizado delas
 
xguru 2026-03-11

Wikipédia - Programação literária
> Programação literária (literate programming) é uma das metodologias de programação que, ao programar, coloca mais ênfase em criar código fácil para humanos entenderem do que em apenas produzir código compilável por computador. Em outras palavras, o objetivo é programar como se estivesse escrevendo documentação para que as pessoas possam ler e compreender. Como a meta é “tornar possível ler a programação como se fosse uma obra literária”, recebeu o nome de “programação literária”.