Markdownレビューを
本文と分けて残す方法

生成済みMarkdownへ指摘を直接書き込む代わりに、対象箇所とコメントをsidecar JSONLへ分けると、本文を保ちながら人間・script・AI工程へ同じ記録を渡せます。

2026年7月29日 · 本文を変更しない管理手順

結論：本文と判断を別ファイルにする

Markdownは成果物、レビューJSONLは人間の判断として分けます。レビュー側には文書hash、行、引用、見出し、コメント、改善案、重要度を保存し、対象を特定できない場合は推測で別の箇所へ付けません。

実際の形式を先に確認

無料の出力サンプルZIPを確認する MDDの実画面を見る

登録不要。1件の合成annotationを含む形式見本です。Windowsアプリ本体・購入リンク・共同編集機能の実証ではありません。

Markdown本文へ直接コメントを書く場合の課題

成果物と指摘が混ざる：AIや公開工程へ渡す本文に、作業中のコメントが残りやすくなります。
機械処理しにくい：コメント、改善案、重要度、状態を毎回同じ形式で取得できません。
対象が曖昧になる：行が移動したとき、どの文章への指摘だったかを行番号だけでは判断できません。

sidecar JSONLへ保存する項目

JSON LinesはUTF-8で、一行ごとに一つの有効なJSON valueを置く形式です。MDDのレビューは独自schemaであり、次の情報を一つのrecordにまとめます。

区分	保存する情報	目的
document	path、SHA-256	どのMarkdown版への指摘か確認
target	line range、quote、heading path、fingerprint	対象箇所の再特定材料
annotation	comment、suggestion、severity、status、link	人間の判断を構造化
metadata	schema version、ID、作成・更新時刻	読み込み契約と更新状態を確認

合成sampleの1 recordを読む

公開sampleには、実在文書ではなく合成Markdownへ付けたレビューが一件入っています。形式を読みやすく抜粋すると次のようになります。

{
  "document": {
    "path": "docs/synthetic-project-brief.md",
    "sha256": "cd053f..."
  },
  "target": {
    "heading_path": ["Synthetic Atlas Project Brief", "Review handoff"],
    "start_line": 38,
    "end_line": 38,
    "quote": "The review checklist must remain traceable..."
  },
  "annotation": {
    "severity": "info",
    "comment": "Clarify how the synthetic acceptance check is recorded.",
    "suggestion": "Record each acceptance check in the generated report."
  }
}

sampleが直接証明するのは、この1件の合成annotationと、対象quote、行、見出し、document hash、comment、suggestion、severityの形式だけです。

編集後にレビュー対象を再特定する手順

保存された行範囲とquoteが現在のMarkdownでも一致すれば、その行を使う。
行が移動していても、同じquoteが文書内に一か所だけなら、その箇所を使う。
同じquoteが複数ある、または消えている場合は、別の箇所を推測せずorphanedとして扱う。

行と引用を併用しても、編集後に必ず再特定できるわけではありません。現在のresolverは保存行とquoteを使い、`heading_path`や`fingerprint`を自動再特定には使いません。

GUIで選択範囲へレビューを付ける流れ

変換後Markdownのプレビューで対象範囲を選ぶ。
コメント、必要なら改善案、重要度、参考リンクを入力する。
元Markdownとは別の`reviews/review.jsonl`へ保存する。
文書を編集した後は、resolved / orphanedの状態を再確認する。

このページは現在のsourceとtestsが証明する単独利用の保存・再特定契約を説明しています。複数人の同時編集、同期、権限管理、自動AIレビューは主張しません。

人間からscript・AI工程へ渡す際の境界

JSONLは一行ずつ処理しやすい形式ですが、schemaの意味や判断の正しさを自動的に保証しません。AIへ渡す場合も、文書本文とreview recordの対応hash、公開可能な内容か、利用するAI側の保存条件を別途確認します。

W3C Web Annotation Data ModelはText Quote SelectorとText Position Selectorを定義していますが、MDDの独自review JSONLはW3C Web Annotation準拠を主張しません。位置と引用を別の手掛かりとして考える際の一次情報として参照しています。

保証境界

この仕組みはappend-only台帳、改ざん防止ログ、共同編集サービス、標準annotation schemaではありません。対象が一意に解決できない場合は人間が確認してください。MDDは現在発売準備中で、Windows実機QAと顧客向けrelease artifactは未完了です。

変換工程からつなげる

レビュー対象のMarkdownをWordから作る場合は、先に見出し、表、画像、警告を確認します。詳しくはWordをMarkdownへローカル変換する手順を参照してください。

無料sampleでreview JSONLを確認

合成Markdown、変換出力、警告、conversion report、review JSONL、MANIFEST、SHA256SUMSを同じZIPで確認できます。

無料の出力サンプルZIPを確認する sample内容を見る

形式確認用の合成データです。アプリの現在入手可否、Windows実機動作、共同編集機能を証明するものではありません。

よくある質問

JSONLは標準規格ですか？

JSON Linesには一般的な形式上の要件がありますが、MDDの各fieldと意味は独自schemaです。W3C Web Annotation準拠ではありません。

複数人で同時にレビューできますか？

現在の証拠が示すのは、ローカルファイルへの保存・読み込みです。共同編集、同期、権限管理は実証していません。

Markdown本文は変更されますか？

レビュー保存処理は元Markdownを変更せず、別のJSONLへrecordを保存します。変換や利用工程で行う別の編集はこの説明に含みません。

MDDは現在購入できますか？

まだ発売準備中です。販売者情報、価格・ライセンス・返金条件、Windows実機QA、exact release artifactの確認後に正規購入導線を公開します。

一次情報と製品内証拠

JSON Lines — UTF-8、一行一JSON value、改行の形式要件
W3C Web Annotation Data Model — Text Quote / Text Positionというselectorの考え方
MDD Review Annotation Format — 公開sampleと同じ、現在の独自record契約

Markdownレビューを本文と分けて残す方法