ドキュメント / ベータ

マージンノートbeta

ローカルのどんな Markdown 文書にも、プルリクエストにコメントするのと 同じ感覚でコメントできます——ただし、コメントが住むのはファイルそのもの。レンダリングされた ページには現れない、ごく普通の HTML コメントとして。とりわけ、ひとつのループのために 作りました。エージェントがあなたに文書を書き、あなたは PullMark で読みながらノートを残し、 「ノートに対応して、済んだものは消しておいて」と言ってファイルを返す。 エージェントのページが、スクリーンショット付きでそのループの 全体を追いかけます。

PullMark で使う

PullMark（0.28.1 以降）が入っている Mac でこれを読んでいますか？ マージンノートのスイッチへ 直行する。

• デフォルトで有効です — マージンノートは、有効な状態で出荷される ベータの実験的機能です（0.35 から）。はじめて手を 伸ばしたとき——ホバーの吹き出し、⌥⌘M、あるいは誰かが残したノートの 「編集」／「削除」——PullMark が機能を紹介します。ノートとは何か、エージェントに教えるための コピーボタン、そして自分向けでなければ押せる「オフにする」ボタン。スイッチは 設定 → 実験的機能 にあり、そこが左右するのは書く側の 道具だけです。すでにノートを含む文書は、どちらの設定でも吹き出しを表示します （読み取り専用で）。同僚やエージェントが注釈を付けたファイルが、黙って空っぽに レンダリングされることはありません。
• ノートを足す — ローカル文書のどれかのブロックにホバーして、余白の 吹き出しをクリックします（PR にコメントするのと同じ手つきです）。リストの中では指している その項目が、表の中ではその行が対象になります——淡い色づきが、ノートの付き先を正確に 教えてくれます。先にテキストを選択しておけば、選択部分を引用した状態でノートが開きます ——段落ではなく一文を指し示すやり方です。⌥⌘M はいま読んでいるブロックに ノートを残し、編集 → 「ファイル全体のマージンノート…」 は文書全体についての ノートを、いちばん上に残します。
• Markdown で書く — 太字、コードスパン、フェンス付きコード、リンク、 リスト。⌘↩ で保存します。1 回の保存は、ファイルへの 1 回の編集です （取り消しは ファイル → 「最後の編集を元に戻す」）。
• 「編集」／「削除」 — ノートの吹き出しにホバーすると操作が出ます。ノートを 削除することが、解決するということ。状態もアーカイブもありません——対応されたノートとは、 そこに無いノートです。
• チップ — 文書がまだノートを抱えているあいだ、「開いているファイル」の行には コメント数のチップが付きます。それは生きています。エージェントがファイルを片づけながら ノートを消していくにつれ、数は減り、吹き出しは目の前で消えていきます。
• そのほかの場所では — ブラウズ中の GitHub ファイルでは読み取り専用で レンダリングされ、印刷にも、PDF／HTML の書き出しにも、Quick Look にも決して現れません。 表示 → 「マージンノートを非表示」 は、きれいな状態で読みたいときに ページを片づけます。
• あなたの署名 — ノートにはデフォルトで @your-github-login の署名が入ります。変えるのは 設定 → 実験的機能 の、この機能自身のスイッチのところです。

フォーマット

マージンノートは、note というキーワードと作者タグを持つ HTML コメントで、 対象のブロックのあとに、単独の行として置かれます。

Requests retry three times with exponential backoff.

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

ひとつのリスト項目についてのノートは、その項目の中に住みます——項目の内容にそろえて インデントし、すき間なく詰めて。リストがひとつづきのまま保たれるためです。

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

長いノートは、閉じマーカーを独立した行に置きます。本文は完全な Markdown で、空行も フェンス付きコードも含められます。

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

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

文法の全体は、こうです。

Markdown のレンダラは HTML コメントを飛ばすので、ノート入りのファイルは GitHub でも、 エディタでも、ほかのどんなツールでも、きれいにレンダリングされます——ノートはページを 散らかすことなく、ソースの中を一緒に運ばれていくのです。PullMark は、どこでも通用する フォーマットのための、美しいクライアントです。

エージェント向け

受け渡しにプロトコルは要りません。エージェントはファイルを読み、ノートはそのファイルの 中に、対象のテキストと物理的に隣り合って置かれています。次を CLAUDE.md / AGENTS.md に貼り付けてください——設定 → 実験的機能 には 同じ文言の「コピー」ボタンがあります（口で言ってしまっても構いません）。

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

収束のループは、フォーマットから自然に導かれます。残っている吹き出しが残っている仕事で、 空のファイルが終わったレビューです。ノートを決してプルリクエストまで届かせたくないなら、 CI のチェックは 1 行で済みます—— grep -rn '<!-- note @' docs/ && exit 1。

なぜベータなのか

仕組みそのものは、すでに自らを証明しました——出荷以来、フォーマットに互換性の無い変更が 必要になったことは一度もなく、だからこそアルファを卒業しました。 ベータの取り決めのとおり、いまはバージョンをまたいで 文法とふるまいの互換性を保つよう本気で努めていますし、この機能が完全に卒業する見込みも 高いと考えています。まだ落ち着いていないのは、その周りの表層です。名前、操作の手がかり、 そしてこのワークフローが、設計の場だったエージェントレビューのループをどこまで超えて 通用するのか。もし何かが変わったなら、リリースノートが正確にそう書きます。 フィードバックは 歓迎です。