エージェントの仕事は、あなたが読む Markdown ファイルとして返ってくる。

エージェントを作る人たちの言葉

引用はそのまま。私たちの解釈はあとに書く。

• Anthropic の「Building Effective Agents」（Erik S. と Barry Zhang、2024 年 12 月）は、エージェントを作るための 3 つの原則を挙げていて、その 1 つが「Prioritize transparency by explicitly showing the agent’s planning steps.」（透明性を優先し、エージェントの計画のステップを明示的に示す。）これはエージェントを作る人向けの原則だ。あなたの側から見れば、その透明性とは、結局あなたが読むことになる計画のことだ。
• 同じ記事：「Agents can then pause for human feedback at checkpoints or when encountering blockers.」（エージェントはチェックポイントや障害に出会ったとき、人間のフィードバックを待って一時停止できる。）動詞に注目してほしい：can（できる）。
• Chip Huyen は「Agents」（2025 年 1 月）で、計画と実行を分けるべき理由をこう説明する：「Without oversight, an agent can run those steps for hours, wasting time and money on API calls, before you realize that it’s not going anywhere.」（監督がなければ、エージェントは何時間もそのステップを実行し続け、API 呼び出しに時間とお金を浪費したあとで、それが何も進んでいないことにあなたが気づく、ということもあり得る。）彼女はさらにこんな失敗も描いている：「The agent is convinced that it’s accomplished a task when it hasn’t.」（エージェントは、実際には終わっていないのに、タスクを終えたと確信している。）50 人を 30 部屋に割り振るよう頼まれたエージェントは、40 人しか割り振らないまま、終わったと言い張る。
• Andrew Ng は The Batch（2024 年 4 月）で planning パターンについてこう述べる：「On one hand, Planning is a very powerful capability; on the other, it leads to less predictable results.」（一方で、計画は非常に強力な能力だ。他方で、予測しにくい結果につながる。）これは予測可能性についての指摘であって、人によるレビューを求めているわけではない。彼は計画能力が急速に向上すると見ている。

ここからは著者たちの主張ではなく、私たちの推論だ：エージェントが計画を示し、チェックポイントで止まるなら、そのチェックポイントで計画を読むのは、たいていあなただ。エージェントが終わっていないのに終わったと思い込むことがあるなら、その「完了報告」にも読み手が必要になる。ここに挙げた著者は誰も MarsDawn について触れておらず、MarsDawn や他の Markdown ツールを推奨してもいない。

見た目より読みにくい理由

ファイルは長く、重要な部分はたいてい先頭にはない。Mermaid の図や数式が入っていて、ソースのままでは追いにくい。読んでいる途中で、エージェントがまだファイルを書き換えていることもある。ファイルは複数にまたがることが多く、ブランチや worktree をまたぐこともある。そして問題を見つけたとき、「キャッシュの部分がおかしい」ではエージェントは推測するしかないが、「docs/plan.md:42 はバックフィルが終わる前に古いテーブルを落としている」ならそうはならない。

MarsDawn が助けになるところ

• 長いファイル：サイドバーのアウトラインタブ（⌃⌘S）に見出しが並ぶ。クリックすると両方のペインがそこへ移動する。
• 図と数式：Mermaid と KaTeX はソースの隣のプレビューに描画され（⌘2）、両方のペインが一緒にスクロールする。
• 読んでいる途中の書き換え：エージェントがファイルを書き換えると、MarsDawn は再読み込みしつつ、あなた自身に未保存の編集がなければ、読んでいた位置を保つ。
• 複数のファイル：「ファイル ▸ フォルダを開く⋯」（⇧⌘O）でエージェントの作業フォルダを開く。新しいファイルは 1 秒ほどでファイルタブに現れ、git のチェックアウトならヘッダーにブランチや worktree の名前が出る。
• 正確なフィードバック：「編集 ▸ 参照をコピー」（⌥⌘C）で、いまいる場所を docs/plan.md:42 の形でコピーできる。「AI 用にコピー」（⌃⌥⌘C）は、その下に選択したテキストを付け加える。どちらもエージェントのチャットに貼り付ければいい。

このループにはもう 2 つ関係がある。エージェントは marsdawn open plan.md:42 を実行して、MarsDawn でファイルを 42 行目、つまりまず見てほしい行で開かせることができる。そしてレビューが終わったファイルは、アプリから、あるいは無料の marsdawn export コマンドで PDF に書き出せる。

MarsDawn の中に AI モデルはない。計画を要約したり、採点したり、何が間違っているか教えたりはしない。読むのはあなたで、MarsDawn は長く変わり続けるファイルを読みやすく保ち、正確な行を指し示せるようにするだけだ。

5 分でエージェントの計画をレビューする

どんなエディタでも使える方法だ。

1. 見出しだけを読む。アウトラインは頼んだ内容と一致しているか。セクションが欠けていれば、たいてい作業も欠けている。
2. 「完了」「合格」「検証済み」と書かれている箇所をすべて見つけ、そのうち 1 つを自分で確認する：ファイルを開く、テストを実行する、行数を数える。
3. 取り消せないステップを探す：データの削除、マイグレーション、force push、何かを送信・支払い・公開する処理。それらはあなたの明示的な OK を待つべきだ。
4. 図はレンダリングした状態で読み、矢印の 1 つひとつを本文と照らし合わせる。
5. 計画が触れるファイルとシステムを列挙する。頼んでいないことがあれば、実行前に確認する。
6. フィードバックは「場所・問題・直し方」で書く：「plan.md:88：バックフィルが drop のあとに実行される。ステップ 4 と 5 を入れ替えて。」1 行に 1 つの問題だけを書く。

時間がないなら、ステップ 2 だけをやろう。終わったと思い込んでいるエージェントが見つかるのは、たいていそこだ。より詳しい説明と実例は「エージェントの計画を 5 分でレビューする」にある。

試してみる

MarsDawn は Mac App Store で配信中です。無料の marsdawn コマンドラインツールもあります：

brew install redtear1115/tap/marsdawn

アプリなしで Markdown を PDF に書き出せます。marsdawn open でエージェントにファイルを MarsDawn で開かせることもできます。

コマンドライン · AI エージェント向けの参照：marsdawn for agents · 購入前に：MarsDawn ができないこと

次に

• AI の出力をそもそも読むべき理由（短い版）：AI の出力を人が確認する理由。
• レビュー中もエージェントの context を小さく保つ：トークンを抑えたレビュー。
• なぜエージェントはそもそも計画を示すのか：Anthropic はエージェントに透明性を求めた。では誰がそれを読むのか？
• 上のチェックリストを、実例つきで詳しく：エージェントの計画を 5 分でレビューする。
• エージェントの種類ごとに、どんな文書が返ってくるか：4 つのエージェント設計パターンと、それぞれが返す文書。

出典

• Erik S. and Barry Zhang, “Building Effective Agents,” Anthropic, December 19, 2024: https://www.anthropic.com/engineering/building-effective-agents（2026-09-26 時点のオンライン版から引用。同記事は現在、2024 年 12 月以降ツール環境が大きく変わったと注記している）
• Chip Huyen, “Agents,” January 7, 2025: https://huyenchip.com/2025/01/07/agents.html
• Andrew Ng, “Agentic Design Patterns Part 4, Planning,” The Batch, April 10, 2024: https://www.deeplearning.ai/the-batch/agentic-design-patterns-part-4-planning/