md-review

md-review — コードレビューの Markdown → 2 列の HTML

Shihipar のエッセイ（「Code Review and PR Writeups」）の Tier 2 にある、コードレビュー用コンバーターです。差分ブロックと重要度の注記を含む PR の Markdown レポートを受け取り、ジャンプナビゲーション、2 列の差分＋注釈レイアウト、レビュアー名を記載したフッターを備えた単一ファイルの HTML レビューを生成します。

3 つの標準ライブラリツールをパイプラインで連携させます。

diff_parser.py  →  annotation_extractor.py  →  review_html_renderer.py
   (md → diff hunks)   (md → severity-tagged    (hunks + annotations
                        annotations attached     + tokens → 2-col HTML)
                        to nearest hunk)

呼び出すタイミング

症状	アクション
markdown-html-orchestrator が入力を REVIEW として振り分ける	このスキルを呼び出します
ユーザーが /cs-md-review <path>.md を直接実行する	このスキルを呼び出します
入力に ```diff のフェンス付きブロックと > [!MAJOR]／> [!BLOCKER] などの注記が含まれる	このスキルを呼び出します
入力が長文の仕様書／レポート（差分ブロックなし）である	代わりに md-document に振り分けます
入力がスライドデッキである	代わりに md-slides に振り分けます
入力が 100 行未満である	拒否します（Shihipar の基準）
デザインシステムがオンボーディングされていない	拒否し、/cs-design-system を提示します

パイプライン

# 1. Parse markdown → diff hunks JSON
python3 markdown-html/skills/md-review/scripts/diff_parser.py \
    --input <path>.md --output hunks.json

# 2. Extract severity-tagged annotations, attach to nearest preceding hunk
python3 markdown-html/skills/md-review/scripts/annotation_extractor.py \
    --input <path>.md --diff-blocks hunks.json --output annotations.json

# 3. Render 2-col HTML (--reviewer is mandatory — refuses without)
python3 markdown-html/skills/md-review/scripts/review_html_renderer.py \
    --diff-blocks hunks.json --annotations annotations.json \
    --reviewer "Jane Doe" --title "PR #123: Add retry logic" \
    --output review.html

レンダリングされる内容

• 上部のジャンプナビゲーション — 重要度バッジ、80 文字のプレビュー、ジャンプリンクを付けて各注釈を表示します。見出しには重要度ごとの件数を表示します（「3 BLOCKER · 2 MAJOR · 1 NIT」）。
• 2 列のハンク行 — 左側に統一差分を表示します（行ごとの旧／新行番号、+／−マーク、デザインシステムのトークンによる追加／削除の背景色）。右側には注釈カードを表示します（WCAG 1.4.1 に準拠した色、アイコン、aria-label）。
• 承認バー — LGTM マーカーがあり、重要度の注釈がない場合、成功を示す色の「LGTM — 指摘事項はありません」バーを表示します。
• 全般的なコメント — どのハンクにも紐付いていない注釈は、専用セクションにまとめて下部に表示します。
• レビュアーフッター — 必須です。--reviewer を指定しない場合はレンダリングを拒否します。
• レスポンシブ対応 — 900px 未満のビューポートでは、2 列レイアウトを縦積みに切り替えます。

厳守事項

1. --reviewer は必須です。 コードレビューには人間のレビュアー名が必要です。指定しない場合は終了コード 3 で拒否します。research-ops の「担当者を明記する」方針を踏襲しています。
2. ハンクがない場合は拒否します。 --- a/file と @@ ... @@ のブロックがなければ、これはコードレビューではありません。終了コード 4 で拒否し、md-document を推奨します。
3. 入力が 100 行未満の場合は拒否します。 基準を下回る場合は Markdown が適切です（Shihipar）。
4. オンボーディングなしでは拒否します。 すべてのコンバーターと同じゲートを適用します。
5. 重要度を色だけで示してはいけません。 各バッジには色、アイコン、aria-label、テキストが含まれます。レンダラーレベルで WCAG 1.4.1 を適用します。
6. 出力は単一ファイルです。 CSS はすべてインラインです。外部リソースは Google Fonts の CSS のみです。差分の色付けが構文ハイライトと競合するため、md-review では Prism を使用しません。
7. 重要度の表記をカスタマイズできます。 --severity-convention "critical,important,suggestion,nit" を指定すると、階層名を置き換えます。位置 0 が最も重大です。デフォルトは BLOCKER／MAJOR／MINOR／NIT です（Google Code Review Developer Guide）。

深掘り質問ライブラリ（Matt Pocock の問い詰め方針）

1. レビュアーとして記載するのは誰ですか？ 推奨：レビューを承認するユーザーです。準拠先：research-ops の担当者明記パターン、SWE at Google 第 9 章。
2. 適用する重要度の表記はどれですか？ デフォルト（BLOCKER／MAJOR／MINOR／NIT）ですか、それともカスタムですか？ 推奨：チームで文書化された別の表記がない限り、デフォルトを使用します。準拠先：Google Code Review Developer Guide。
3. 注釈は特定のハンクに紐付けますか、それとも全般的なものもありますか？ 推奨：可能なものはすべて紐付け、全般的なものは未紐付けセクションに配置します。準拠先：SWE at Google 第 9 章 — 「コメントは特定の行を参照する必要があります」。
4. <title> とヘッダーに使う PR のタイトルは何ですか？ 推奨：実際の PR／コミットのタイトルです。準拠先：docs-as-context-for-readers。
5. LGTM マーカーを承認バーとして表示しますか？ 推奨：重要度の注釈がなければ表示します。注釈がある場合は指摘事項を優先します。

次のものとは異なります

• md-document — このコンバーターは文章、表、コード、注記をレンダリングします。こちらは差分ハンクと欄外注釈をレンダリングします。
• md-slides — このコンバーターは --- の区切りで分割します。こちらは単一ページの成果物です。
• GitHub PR のコメント — そちらはスレッドです。こちらは単一の作成者によるスナップショット形式の成果物です。

出力成果物

{default_output_dir}/review-{slug}.html（パスはオーケストレーターの output_path_resolver.py で解決されます。デフォルトでは、衝突時に -2、-3、…のサフィックスが付与されます）。

参考資料

• Shihipar — Claude Code HTML output（Medium、2026年）、Tier 2 のユースケース
• Software Engineering at Google（Manshreck & Wright、O'Reilly 2020）、第9章「コードレビュー」
• Google Code Review Developer Guide — 重大度の表記規則の出典
• WCAG 2.2 §1.4.1 — 色だけに頼らない通知の適用
• 詳細な引用については references/ を参照してください（diff_rendering_canon、severity_coding、pr_annotation_ux）