docs / beta

Notas de margembeta

Comente qualquer documento Markdown local do jeito que você comentaria um pull request — só que os comentários vivem no próprio arquivo, como comentários HTML simples que ficam fora da página renderizada. Feitas para um ciclo em particular: um agente escreve um documento para você, você o lê no PullMark deixando notas pelo caminho e devolve o arquivo com um “resolva as notas e apague-as conforme terminar”. A página de agentes percorre esse ciclo inteiro, com capturas de tela e tudo.

Usando no PullMark

Lendo isto no Mac onde o PullMark (0.28.1+) está instalado? Pule direto para o interruptor das notas de margem.

• Elas vêm ativadas por padrão — as notas de margem são um recurso experimental beta que já vem ativado (desde a 0.35). Na primeira vez que você as alcança — o balão ao passar o mouse, ⌥⌘M, ou Editar / Apagar numa nota que alguém deixou para você — o PullMark apresenta o recurso: o que as notas são, um botão de copiar para ensinar seu agente e um botão de desligar se não for para você. O interruptor mora em Ajustes → Experimental e controla só as ferramentas de escrita; um documento que já contém notas mostra seus balões de qualquer jeito (somente leitura), então um arquivo anotado por um colega ou um agente nunca renderiza silenciosamente vazio.
• Adicionar uma nota — passe o mouse sobre qualquer bloco de um documento local e clique no balão na margem (o mesmo gesto de comentar num PR). Dentro de uma lista, o balão mira no item que você está apontando; dentro de uma tabela, na linha — um tom sutil mostra exatamente ao que a nota vai se prender. Selecione texto primeiro e a nota abre com a seleção citada — o jeito de apontar para uma frase em vez de um parágrafo. ⌥⌘M anota o bloco que você está lendo; Editar → Nota de Margem do Arquivo… deixa uma nota sobre o documento inteiro, no topo.
• Escreva Markdown — negrito, trechos de código, código cercado, links, listas; ⌘↩ salva. Cada salvamento é uma edição no arquivo (desfaça com Arquivo → Reverter Última Edição).
• Editar / Apagar — passe o mouse sobre o balão de uma nota para suas ações. Apagar uma nota é como ela se resolve: sem estado, sem arquivo morto — uma nota resolvida é uma nota ausente.
• O chip — linhas de Arquivos Abertos mostram um chip com a contagem de comentários enquanto um documento ainda carrega notas. É ao vivo: conforme um agente trabalha pelo arquivo apagando notas, a contagem cai e os balões desaparecem na sua frente.
• Em todo o resto — as notas renderizam somente leitura em arquivos navegados do GitHub, nunca aparecem na impressão, na exportação para PDF/HTML ou no Quick Look, e Visualizar → Ocultar Notas de Margem limpa a página quando você quer ler sem nada.
• Sua assinatura — as notas são assinadas @seu-login-do-github por padrão; mude isso sob o interruptor do próprio recurso em Ajustes → Experimental.

O formato

Uma nota de margem é um comentário HTML com a palavra-chave note e uma marca de autor, colocado em linha própria após o bloco de que trata:

Requests retry three times with exponential backoff.

<!-- note @josh: Section 2 says five times. Which is it? -->

Uma nota sobre um item de lista vive dentro do item — indentada até o conteúdo do item, bem colada, para a lista continuar inteira:

- First point
  <!-- note @josh: too vague — name the metric -->
- Second point

Notas mais longas põem o marcador de fechamento em linha própria; o corpo é Markdown completo, linhas em branco e código cercado incluídos:

<!-- note @josh:
This contradicts the design doc. Either reconcile them or
drop this section.

```suggestion
Requests retry five times with exponential backoff.
```
-->

A gramática completa:

Como os renderizadores de Markdown pulam comentários HTML, um arquivo com notas dentro renderiza limpo no GitHub, nos editores e em qualquer outra ferramenta — as notas viajam no código-fonte sem poluir a página. O PullMark é o cliente bonito de um formato que funciona em qualquer lugar.

Para agentes

A entrega é de protocolo zero: agentes leem arquivos, e as notas estão no arquivo, fisicamente adjacentes ao texto de que tratam. Cole isto no seu CLAUDE.md / AGENTS.md — Ajustes → Experimental tem um botão de copiar com o mesmo texto (ou simplesmente diga em voz alta):

## 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.

O ciclo de convergência decorre do formato: balões restantes são trabalho restante, e um arquivo vazio é uma revisão terminada. Se as notas nunca puderem chegar a um pull request, uma verificação de CI é uma linha — grep -rn '<!-- note @' docs/ && exit 1.

Por que é beta

A mecânica já se provou — o formato não precisou de nenhuma mudança incompatível desde que foi lançado, e foi por isso que ele se graduou do alfa. Pelo contrato do beta, agora fazemos um esforço real para manter a gramática e o comportamento compatíveis entre versões, e é provável que o recurso se gradue por completo. O que ainda está assentando é a superfície ao redor: nomes, affordances e até onde o fluxo de trabalho generaliza além do ciclo de revisão com agentes em que foi criado. As notas de release dirão exatamente o que mudou, se algo mudar. Feedback é bem-vindo.