open-doc: Deixando Agentes de Codificação Controlarem Layout e Geração de Documentos

GitHub — open-doc
https://github.com/simonliu-ai-product/open-doc

1. Introdução

Ao longo do último ano, acho que a maioria de nós entregou cada vez mais trabalho a agentes de codificação — escrevendo código, pesquisando coisas, executando testes. Eles fazem tudo isso muito bem. Mas há uma coisa que eu nunca consegui acertar: pedir a um agente para produzir um relatório que eu pudesse entregar como está.

Os agentes são, na verdade, bons escritores. Peça a um para fazer uma revisão trimestral, uma avaliação técnica ou uma proposta de projeto e a qualidade do conteúdo é boa. O problema começa logo após as palavras — o layout. Cada abordagem que tentei ficou presa no mesmo lugar:

• Fazer o agente escrever Markdown, depois converter para PDF. A saída não tem conceito de "página". Tabelas são cortadas ao meio em uma quebra de página, legendas são separadas de suas figuras, os números da página do índice não se alinham. Você acaba ajustando CSS em vez de ler o conteúdo.
• Fazer o agente escrever HTML, depois imprimi-lo. Cada documento reinventa o layout da página do zero. Onde estão as margens A4, quando deve haver uma quebra, como os números das páginas se mantêm — você re-deriva tudo isso toda vez, e então o próximo documento começa de novo.
• Fazer o agente produzir Word. Não há necessidade de elaborar aqui. As chances de a formatação desmoronar são de aproximadamente 100%.

Depois de pensar sobre isso por tempo suficiente, você percebe que o problema não é que o agente não é inteligente o suficiente — é que a divisão de trabalho está errada. O que os agentes são genuinamente bons é em conteúdo, e o layout é a parte que não pode estar errada. O tamanho da página de um relatório, margens, posições de quebra e números de páginas consecutivas não deixam espaço para criatividade: eles estão certos ou errados. Entregar isso a um agente que tem que adivinhar a cada vez nunca foi uma ideia razoável.

Então, o arranjo sensato é deixar a estrutura bloquear as partes que não podem estar erradas, e deixar o agente lidar apenas com o que ele realmente é bom. O projeto que me fez ver isso claramente foi o trabalho de outra pessoa.

2. Um Olhar sobre open-slide

Para deixar claro desde o início: open-slide é o trabalho de @1weiho, não meu. Eu sou um usuário.

GitHub - 1weiho/open-slide: Uma estrutura de slides construída para agentes.
https://github.com/1weiho/open-slide

Ela se apresenta como "uma estrutura de slides construída para agentes". Cada slide é uma tela fixa de 1920 × 1080 escrita como um componente React, e a estrutura cuida da escalabilidade, navegação, recarregamento a quente, modo apresentador e visualização do palestrante. Você não precisa aprender uma DSL restritiva, porque a página é um componente — quer um gráfico, insira um gráfico; quer uma animação, escreva uma animação.

npx @open-slide/cli init my-slide

Eu ouvi sobre o projeto no COSCUP e fui para casa tentar. Na prática, a sensação é: enquanto você puder descrever o slide que deseja em linguagem simples, o agente escreve React e o resultado aparece no seu navegador imediatamente.

Mas o que realmente me fez parar e investigar não foi "escrever slides em React" — isso não é novo. O que achei interessante foi como ele lida com a questão de como o agente deve saber como usar essa ferramenta.

Quando você init um projeto open-slide, a pasta contém mais do que código: há um AGENTS.md, além de um punhado de documentos de habilidades em .agents/skills/. Quando seu agente de codificação abre o projeto, ele já sabe como é o contrato de arquivo, quanto conteúdo cabe com segurança em um slide e o que não deve tocar.

Em outras palavras, o manual viaja com o projeto, não com a conversa. Esse design se tornou o ponto de partida para todo o open-doc.

3. O que open-slide me ensinou — Construindo ferramentas e fazendo agentes de codificação entenderem como usá-las

Eu coloquei o open-slide à prova e li a fonte. Esta seção é sobre o que me ensinou sobre a diferença entre ferramentas construídas para agentes e ferramentas construídas para pessoas.

I. O manual pertence ao repositório, não ao prompt

Este é o ponto mais contra-intuitivo e o que tem o maior impacto. Estamos acostumados a escrever "como usar esta ferramenta" como um prompt colado no topo de uma conversa. O problema é que os prompts ficam obsoletos, são truncados e nunca são atualizados — e uma pessoa diferente ou um agente diferente significa colá-lo tudo de novo.

A abordagem do open-slide é transformar esse conhecimento em arquivos no repositório. Uma habilidade é apenas um arquivo Markdown que diz "quando você escreve este tipo de arquivo, aqui está o que você deve seguir", e o scaffolder o gera no projeto do usuário. Três benefícios surgem disso: é versionado (a estrutura muda, a habilidade muda com ela), é escopo do projeto (qualquer um que abrir o repositório pode vê-lo), e é revisável (uma habilidade é parte da fonte, então passa por PRs).

II. Tranque as partes que não podem estar erradas na estrutura

A tela do open-slide é sempre 1920 × 1080. Isso não é uma limitação — isso é o produto. Como a tela é fixa, o agente nunca precisa adivinhar qual é o tamanho do slide, quão grande deve ser o texto ou se o conteúdo caberá. Ele apenas escreve conteúdo, e "cabe?" é respondido pela estrutura através da medição, que é muito mais confiável do que um agente adivinhando.

Eu diria de forma ainda mais direta: cada escolha que você tira do agente é uma classe de erro que você não precisa mais verificar. O layout é certo ou errado sem margem criativa — nunca foi algo a ser deixado para adivinhação.

III. O agente precisa saber onde você está olhando atualmente

Esse eu só apreciei depois de usá-lo na prática. Você está olhando para o slide 7 no seu navegador, vira-se para o agente e diz "o espaçamento nesta página está muito apertado" — qual página é "esta página"? O agente não sabe. Ele só pode perguntar de volta ou adivinhar, e um palpite errado significa que ele edita algo completamente diferente.

A solução do open-slide é direta: em cada navegação, o servidor de desenvolvimento escreve "onde o usuário está agora" em um arquivo, emparelhado com uma habilidade que diz ao agente para lê-lo. Referências deícticas como "esta página" ou "este elemento" então se resolvem em um caminho de arquivo concreto e número de linha. Parece uma coisa pequena, mas é a ponte entre a tela que o humano está olhando e o arquivo que o agente está editando.

Essas três lições vieram diretamente do open-slide. Mas uma vez que realmente construí um sistema próprio, encontrei mais dois problemas que ele não me mostrou — humanos e agentes editando o mesmo arquivo ao mesmo tempo, e a mesma operação tendo mais de um ponto de entrada. Vou cobrir ambos na próxima seção.

4. Meu Projeto de Código Aberto: open-doc

Carregando essas três lições, passei os últimos poucos dias