o momento
Um plano de 400 linhas acabou de chegar. E agora?
Você conhece a rotina: o agente termina um plano, e o próximo passo é seu. Ler Markdown cru num editor esconde o que um leitor veria — tabelas, estrutura, a forma do argumento. Colar trechos de volta no chat separa cada comentário do lugar de que ele fala, e o agente tem que adivinhar para onde o seu “essa parte está errada” aponta. E a única ferramenta feita para comentar documentos — o pull request — exige o rascunho commitado, enviado e revisado num navegador antes.
Nem todo documento merece um commit, e nem toda versão de trabalho de um doc deve subir para o remoto.
Um rascunho de trabalho precisa do mesmo ciclo de feedback que você daria a um colega diante de um quadro branco: apontar o parágrafo, dizer o que está errado, devolver. É isso que as notas de margem são.
o ciclo
Leia renderizado. Anote no lugar. Devolva.
Abra o rascunho no PullMark — ou só pullmark plan.md no
terminal em que o agente roda. Tabelas são tabelas, diagramas são
diagramas, e a página re-renderiza toda vez que o arquivo muda.
Passe o mouse sobre o bloco errado, clique no balão de nota e escreva o que diria a um colega. As notas são assinadas com o seu @nome e ancoradas no trecho exato — uma nota acima do título cobre o documento inteiro.
Diga ao seu agente: “resolva minhas notas no plan.md”. As notas vivem no arquivo como comentários HTML comuns, então o agente lê cada uma exatamente onde você a deixou — aplica, responde, apaga.
Sem aprisionamento, por construção. Uma nota de margem
é <!-- note @voce: … --> no Markdown — um comentário que
fica fora da página renderizada. Seus arquivos continuam texto puro, suas
notas viajam com o documento, e qualquer coisa que consiga ler o arquivo
consegue ler o feedback. A documentação
das notas de margem cobre a mecânica; o recurso está em beta e vem
ativado por padrão.
Agentes seguem a convenção melhor com um parágrafo de contexto. Este
é o mesmo texto por trás do botão Copiar em
Ajustes → Experimental — cole-o no arquivo de instruções do
seu agente (CLAUDE.md, AGENTS.md) ou na
conversa:
## Margin notes Markdown files may contain review notes as HTML comments: `<!-- note @name: comment -->` (possibly multi-line, closing with `-->` on its own line). Each note sits directly after the passage it's about; a note above the first heading is about the whole document. `--\>` inside a note means a literal `-->`. When asked to address notes: work through each one, apply or answer it, and DELETE the note (with its surrounding blank line) once addressed. To reply or ask instead, leave your own note in the same format below the original, signed with your own @name. Don't add notes to code examples inside fenced blocks. A note about one list item sits inside that item — directly after the item's last line, indented to the item's content, with no blank lines around it. Keep (or delete) the whole indented comment; its indentation is what ties it to the item.
documentos longos
Notas que esperam por você.
Uma revisão minuciosa de um documento longo — um relatório de pesquisa, um doc de design complexo — pode levar uma hora. As notas de margem foram feitas para essa hora. O documento fica parado enquanto você trabalha: escreva o pensamento onde ele surgir e continue lendo. Quando a página trinta mudar sua opinião sobre a nota que você deixou na página três, volte e afie-a — ou apague-a. Nada chega ao seu agente até a passada terminar e as suas notas concordarem entre si, então o feedback aterrissa como um conjunto coerente, não como um fluxo contínuo de correções.
Vale a pena até para documentos que vão acabar commitados. Faça a primeira passada bruta em notas de margem antes do primeiro commit, e o pull request abre limpo — os revisores veem a conversa que importa, não o andaime que foi preciso para chegar lá.
a revisão
Veja as edições aterrissarem.
Enquanto o agente trabalha nas suas notas, o PullMark acompanha. A
página re-renderiza a cada salvamento, e o Comparar
mostra a nova versão como um diff renderizado — as edições do agente
destacadas palavra por palavra, ao vivo, conforme chegam. Um
clique compara o arquivo de trabalho com qualquer commit ou branch
recente; pullmark --diff plan.md faz isso do terminal. É a
resposta mais rápida para “o que o agente acabou de mudar no meu
doc?” — e quando as notas estão resolvidas, elas simplesmente
desaparecem do arquivo.
quando é um PR
E quando o doc sobe mesmo para revisão…
Alguns documentos merecem commit, sim — e repositórios cheios de agentes enchem pull requests de Markdown: planos, ADRs, definições de agentes, runbooks. O PullMark mostra esses PRs como diffs renderizados com apenas as palavras alteradas em destaque, deixa você comentar e sugerir nos blocos exatos, e envia sua revisão ao GitHub. A visão geral sabe onde o PR está: decisão, vereditos dos revisores, verificações e a conversa como uma linha do tempo legível.
Feche o ciclo com o seu agente.
Gratuito, open source, assinado e notarizado. macOS 13+.
$ brew tap jedijashwa/tap
$ brew trust jedijashwa/tap
$ brew install --cask pullmarkO DMG mais recente — abra e arraste para Aplicativos (o PullMark cuida da limpeza). Todas as releases →
Nos dois casos, o PullMark verifica atualizações e as instala com um clique.