レポートのレビュー・注釈・バージョン管理 — レビュアーガイド
md-logは、AIコーディングエージェントの作業をレビュー・アーカイブする面です。エージェントがMarkdownレポートをパス単位でフォルダツリーに書き込み、あなたはそれをWeb・スマホ・タブレットで読み、承認または却下し、手書きで注釈を付けます — すべての保存が不変のバージョンとして残ります。
md-logは、AIコーディングエージェントの成果物を、人が実際にレビューできる形に変えます。巨大なdiffをスクロールする代わりに、エージェントが書いたMarkdownのレポート（何を・なぜ・どんな影響か）を読み、承認または却下すればよいのです。このガイドでは、レポートがどこに現れるか、どの端末でレビューするか、スタイラス注釈がどう動作するか、不変バージョンが履歴全体をどう保存するかを扱います。
レポートはどこに現れるか
エージェントはMCPを通じて、レポートをファイルパス単位でmd-logに書き込みます（MCPを接続するを参照）。レポートは階層型フォルダツリーに保存されるため、my-project/2026-07-14-auth-refactor.mdのようなパスが、レポートを期待どおりの場所に正確に配置します。フォルダは保存時にmkdir -pのように自動生成されるので、エージェントが事前にフォルダを作る必要はなく、画像やその他の添付アセットも本文と一緒にアップロードされます。
保存されたレポートは、3つの方法で見つけられます。
- Webアプリapp.md-log.comやモバイルアプリでフォルダツリーを探索する。
- レポート全体を対象に全文（full-text）検索する。
- よく開くレポートはお気に入りに登録しておく。
全体の構成がどう噛み合うかは概要で確認してください。
読んでレビューする — human-in-the-loop
レビューモデルは意図的にシンプルです。レビューの対象はdiffではなく、レポートです。 何がなぜ変わったのかについてのエージェントの要約を読み、承認するか却下するかを人が判断します。md-logはレビュービューアであり、アーカイブであって、コードを自動でレビューしたり、人の判断を代替したりはしません。レビュアーはあくまで人です。
レポートはWeb・スマホ・タブレットできれいにレンダリングされるため、レビューは非同期で行えます。席を外している間にエージェントが行った作業を、どこからでもレビューでき、新しいチームメンバー（そして新しいエージェント）は蓄積されたレポートを読んでオンボーディング資料として活用できます。
ペン対応タブレットでのスタイラス注釈
ペンに対応したタブレットでは、レンダリングされたMarkdownの上に直接、手書きで注釈を付けられます。
- AndroidタブレットのS-Pen（ネイティブ）。
- iOS（iPad）のApple Pencil。
- スタイラスがない端末では指描きの代替。
ペン専用のUIはペン対応端末でのみ表示されるため、スタイラスのない環境では画面がすっきり保たれます。ストローク（stroke）の作成はモバイル・タブレットで行います。
注釈はバージョンに固定されます
各注釈レイヤーは特定のドキュメントバージョン1つに属します。ドキュメントが変わっても、md-logは手書きを自動で再整列（re-anchor）したり、繰り越したりしません。 こうすることで、すべての注釈が、描いた当時に見ていた正確なバージョンに忠実に残ります。同じマークを新しいバージョンにも残したい場合は、明示的なコピー操作でそのバージョンにそのまま複製できます。
いま見ているバージョンに、ストロークが描かれたテキストブロックがもう存在しない場合、その孤立した（orphaned）ストロークはページ下部に集められます（クライアント側の処理）。無関係な内容の上に浮くことはありません。
Webアプリの注釈は読み取り専用です
Webアプリは注釈をレンダリングしますが、作成はしません。Webでは手書きが注釈を付けたバージョンに固定されたSVGオーバーレイとして表示されるので、ノートPCで見るレビュアーも、何がマークされたかを正確に見られます。ただし新しいストロークを描くには、モバイルまたはタブレットのアプリを使います。この切り分けにより、Webでのレビューは軽量かつ正確に保たれます。
不変バージョンと履歴
保存するたびに新しい不変バージョンが作られます。既存の内容を上書きしないため、プロジェクトのAIコラボレーション履歴が時間とともに蓄積されます。
- すべてのsave/update/appendには、バージョン履歴に表示されるコミットメッセージが一緒に保存されます。
- 全履歴を参照し、過去のバージョンを開いて読むことができます。
- レポートを移動したり名前を変更したりしても、履歴と注釈は保持されます。
2つの編集が衝突すると、md-logは**楽観的同時実行制御（optimistic concurrency）**を使います。衝突する書き込みは、サーバーの現在のheadとともに同期の衝突を返すため、誤って上書きされることはありません。意図的に最後の書き込みを優先したい場合は、forceオプションを使えます。
オフラインファーストのモバイル、検索、お気に入り
モバイルアプリ（iOS + Android、スマホ・タブレット）はオフラインファーストです。ローカルデータベースを保持し、オンラインに復帰したときにデルタだけを同期するため、移動中でも読んで注釈を付けられます。すべての画面で全文検索とお気に入りにより、重要なレポートに素早く戻れます。
よくある質問
スマホでレポートを編集できますか？
モバイルアプリでは、レポートのMarkdown本文を直接編集するよりも、レビューして注釈を付けます。レポートはAIエージェントがMCPで作成するためです。スマホやタブレットでは、レポートを読んで承認/却下し、スタイラスや指で注釈を付けることができ、その内容はサービスに同期されます。
ドキュメントが変わると、私の注釈も一緒に動きますか？
いいえ。各注釈レイヤーは特定のドキュメントバージョン1つに固定され、md-logは手書きを自動で再整列したり繰り越したりしません。同じマークを新しいバージョンに残したい場合は、明示的なコピー操作で複製すればよく、テキストブロックがもう存在しないストロークはページ下部に集められます。
Webで注釈を付けられますか？
Webアプリの注釈は読み取り専用です。手書きは注釈を付けたバージョンに固定されたSVGオーバーレイとしてレンダリングされ、ノートPCでも見られますが、新しいストロークを描く作成はモバイルまたはタブレットのアプリで行います。
どの端末でペン（スタイラス）注釈に対応していますか？
AndroidタブレットはS-Penをネイティブでサポートし、iPadはApple Pencilをサポートします。スタイラスのない端末は指描きで代替され、ペン専用のUIはペン対応端末でのみ表示されます。
私のレビュー履歴は保管されますか？
はい。保存するたびにコミットメッセージの付いた新しい不変バージョンが作られ、全履歴を参照して過去のバージョンを読めます。レポートを移動したり名前を変更したりしても、履歴と注釈は保持されます。