AI エージェントの計画とドキュメントをレビューする

その瞬間

400 行の計画が届いた。さて、どうする？

おなじみの流れです。エージェントが計画を書き上げ、次の一手はあなたの番。エディタで生の Markdown を読めば、読み手が見るはずのもの——表、構造、議論の輪郭——は見えません。チャットに断片を貼り戻せば、どのコメントも対象の場所から切り離され、あなたの「ここが違う」がどこを指しているのか、エージェントは推測するしかなくなります。そして、文書へのコメントのために作られた唯一の道具であるプルリクエストは、まずドラフトをコミットし、プッシュし、ブラウザでレビューすることを求めてくるのです。

すべての文書がコミットされるべきとは限らないし、作業途中の版までプッシュすべきでもない。

作業中のドラフトに必要なのは、ホワイトボードの前で同僚に返すようなフィードバックループです。段落を指さし、何が違うかを言い、そのまま手渡す。それがマージンノートです。

ループ

レンダリングで読む。その場に書き込む。そのまま返す。

1 · レンダリングで読む

ドラフトを PullMark で開きます。エージェントが動いているターミナルから pullmark plan.md と打つだけでも。表は表、図は図として表示され、ファイルが変わるたびにページは再レンダリングされます。

2 · その場に書き込む

違うと思ったブロックにポインタを重ね、ノートのバブルをクリックして、同僚に伝えるつもりで書きます。ノートはあなたの @名前で署名され、まさにその一節に固定されます。タイトルより上のノートは、文書全体へのノートです。

3 · そのまま返す

エージェントに伝えます——「plan.md のノートに対応して」。ノートは普通の HTML コメントとしてファイルの中にあるので、エージェントはあなたが残したまさにその場所でひとつずつ読み、適用し、答え、削除していきます。

Wind Gust Alerts と題されたエージェント作の設計仕様書をレンダリングする PullMark。レビュアーの署名付きカードとして 3 件のマージンノートが表示されている——きれいな第 2 稿を求めるファイルレベルのノート、仕様のサンプリングレートの前提に異議を唱えるノート、ある機能に YAGNI を宣告するノート。サイドバーには、ブランチ main の git リポジトリの docs/superpowers/specs フォルダにこの仕様書が見えている — エージェントの仕様書への、最初のレビューパス。署名付きノートが該当ブロックに固定されています——コミットも、貼り付けも、プルリクエストもなしで。

仕組みからして、ロックインしません。マージンノートの正体は Markdown 中の ——レンダリングされたページには現れないコメントです。ファイルはプレーンテキストのまま、ノートは文書と一緒に旅をし、ファイルを読めるものなら何でもフィードバックを読めます。仕組みの詳細はマージンノートのドキュメントへ。この機能はベータ版で、デフォルトで有効です。

一段落の説明があるだけで、エージェントはこの規約をずっと上手に守ります。以下は設定 → 実験的機能の「コピー」ボタンが渡すのと同じテキストです。エージェントの指示ファイル（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.

長い文書

あなたを待ってくれるノート。

長い文書——調査レポートや込み入った設計ドキュメント——を丁寧にレビューすれば、1 時間はかかります。マージンノートは、その 1 時間のために作られています。作業のあいだ、文書はじっと動きません。思いついた場所に考えを書き留めて、読み進める。30 ページ目まで来て 3 ページ目のノートへの考えが変わったら、戻って研ぎ直すか、消してしまえばいい。パスを終えてノート同士の辻褄が合うまで、エージェントには何も届きません。だからフィードバックは、訂正の垂れ流しではなく、筋の通ったひとまとまりとして着地します。

最終的にコミットされる文書でも、元は取れます。粗い最初のパスを最初のコミットの前にマージンノートで済ませておけば、プルリクエストはきれいな状態で開きます。レビュアーの目に入るのは本質的な議論だけで、そこへ至るまでの足場は残りません。

改訂

編集が届くのを、見届ける。

エージェントがノートに取り組むあいだ、PullMark は歩調を合わせます。保存のたびにページは再レンダリングされ、「比較」が改訂をレンダリングされた差分として表示—— エージェントの編集は単語単位でハイライトされ、届くそばからライブで映ります。ワンクリックで作業中のファイルを最近の任意のコミットやブランチと比較でき、ターミナルからなら pullmark --diff plan.md。「エージェントはいま自分のドキュメントの何を変えた？」への最速の答えです。そしてノートへの対応が済めば、それはただ、ファイルから消えています。

PR になったら

そして、ドキュメントが本当にレビューへ上がるときは…

コミットされるべき文書も、もちろんあります。エージェントが活躍するリポジトリでは、プルリクエストは Markdown で満ちていきます——計画、ADR、エージェント定義、運用手順書。 PullMark はそうした PR を、変わった単語だけがハイライトされたレンダリング差分 として表示し、該当ブロックへのコメントや提案を受け付け、レビューを GitHub に送信します。概要画面は PR の現在地を心得ています。決定、レビュアーの判定、チェック、そして読みやすいタイムラインになった会話。

PullMark のプルリクエスト概要。「オープン」チップ付きの PR タイトル、「変更をリクエスト済み」カプセル、「チェック成功」カプセル、判定バッジをまとったレビュアーのアバター、docs-guild チームのチップ、レンダリングされた PR 説明、そして最初のレビューコメントに表が表として表示されている会話のタイムライン — 同じレビューの勘どころを、プルリクエストに向けただけ——レビュー機能の全体はフロントページで。

エージェントとのループを、閉じる。

無料、オープンソース、署名・公証済み。macOS 13+。

Homebrew

$ brew tap jedijashwa/tap
$ brew trust jedijashwa/tap
$ brew install --cask pullmark

直接ダウンロード

PullMark をダウンロード

最新の DMG です。開いて Applications にドラッグするだけ（後片付けは PullMark が引き受けます）。すべてのリリース →

どちらの方法でも、PullMark がアップデートを確認し、ワンクリックでインストールします。