plannotator-visual-explainer

Plannotator ビジュアル解説

コンテンツの種類に応じて、3つの経路があります。それぞれに専用のリファレンスと構成があります。

コンテンツの種類に応じた経路

実装計画、設計ドキュメント、提案書 → 計画の経路に従います。references/design-system.mdとreferences/svg-patterns.mdを読みます。規定の構成に従います。

PR の解説、差分レビュー、コード変更のウォークスルー → PR の経路に従います。references/design-system.mdとreferences/pr-components.mdを読みます。規定の構成に従います。

その他すべて（アーキテクチャ図、データテーブル、スライドデッキ、プロジェクトの振り返り、一般的なビジュアル解説） → Plannotator のテーマトークンを使って、nicobailon/visual-explainer に委任するビジュアル解説の経路に従います。

提供方法

常に Plannotator の注釈 UI を使って提供してください。openやxdg-openは使用しないでください。

Mermaid を使う成果物では、注釈 UI を開く前に、ライトとダークの両方のパレットで Mermaid 12 を使ってすべての図をレンダリングしてください。レンダリングは必須のチェックです。例外、空の SVG、またはaria-roledescription="error"やSyntax error in textなどのエラー出力がある場合、その解説は提供できません。図またはテーマ設定を修正し、すべての SVG が合格するまで両方のパレットで再実行してください。

ズーム可能な図のシェルでは、さらに両方のパレットで最大までズームし、すべての端までパンしてから提供してください。その間、図のキャプションが常に完全に読みやすい状態である必要があります（references/diagram-shell.mdを参照）。

計画／提案書（ユーザーが承認または却下するもの）：

plannotator annotate <file> --gate

その他すべて（情報提供用）：

plannotator annotate <file>

---

計画の経路

実装計画、設計ドキュメント、機能仕様書、移行ガイド、提案書向けです。

生成前に読むもの：

1. references/design-system.md — Plannotator のテーマトークン、タイポグラフィ、コンポーネントのパターン
2. references/svg-patterns.md — アーキテクチャ図、フローチャート、データフロー用のインライン SVG 構成要素

ドキュメントの構成（順序に従い、適したものを選択）：

1. ヘッダー — アイブロウラベル（等幅、大文字）、タイトル（大きなセリフ体）、プロンプトボックス（元の概要）
2. サマリーストリップ — 主要な数値がひと目でわかる3〜5枚の統計カード（コンポーネント、エンドポイント、テーブルなど）
3. マイルストーン／タイムライン — 期間の見積もりを含めず、フェーズを示す縦型タイムライン。フェーズでは期間ではなく、順序と依存関係を示します。
4. アーキテクチャ／データフロー — インライン SVG 図。3つ以上のコンポーネントが連携する場合に使います。新しいコンポーネントは強調表示したボックスで示し、非同期の経路は破線の矢印で示します。
5. モックアップ — 説明文ではなく、HTML/CSS で直接 UI モックアップを作成します。
6. 主要なコード — 構文強調表示付きのダークテーマのコードブロック。アーキテクチャ上重要なインターフェース／スキーマのみを含め、すべての関数は含めません。
7. リスクと軽減策 — 重大度バッジ（HIGH/MED/LOW）付きのテーブル
8. 未解決の質問 — 意思決定者（「相談先：バックエンドチーム」など）を示すコールアウトカード

すべての計画にすべてのセクションが必要なわけではありません。内容に役立たないものは省略してください。期間の見積もり、定型的なセクション、網羅的なファイル一覧は含めないでください。

タスクに応じて調整します： バックエンドならデータフローから始めます。フロントエンドならモックアップから始めます。リファクタリングなら変更前／変更後の図から始めます。インフラストラクチャならアーキテクチャから始めます。

品質基準： 計画を読んで30秒以内に「何を、なぜ、どのように」がわかるようにします。余白も重要です。1つのビューポートにつき1つのアイデアにします。

PR パス

PR のウォークスルー、差分レビュー、コード変更の解説、レビュアー向けガイドに使用します。

生成前に読むもの：

1. references/design-system.md — Plannotator のテーマトークン、タイポグラフィ、コンポーネントのパターン
2. references/pr-components.md — 差分のレンダリング、レビューコメントの吹き出し、リスクチップ、ファイルカード、変更前／変更後のパネル

ドキュメントの構成（順番どおりに、必要なものを選択）：

1. ヘッダー — PR タイトル、メタ情報（ファイル数、変更行数（追加／削除）、ブランチ、作成者）
2. 要約 — 左側に主要なアクセントカラーのボーダーがあるカード。2〜3 文。他を読まなくても、要点がわかる内容にします。
3. 理由 — 背景と変更前／変更後の比較（2 列のグリッド）
4. ファイルごとの説明 — ファイルごとに折りたたみ可能なカード。各カードに、ファイルパスとバッジ（NEW/MOD/DEL）、行数の統計、「理由」の段落、重要な差分部分を含めます。リスクの高いファイルは展開し、安全なファイルは折りたたみます。
5. リスクマップ — 注意してレビューするファイルと機械的な変更のファイルを示す視覚的なチップ。3 段階：注意（破壊的）、中（警告）、安全（成功）。
6. 重点箇所 — 番号付きのコールアウトカード。各カードでファイル／関数を示し、懸念点を説明します。
7. テスト計画 — チェックボックス形式の検証チェックリスト
8. ロールアウト（該当する場合）— フィーチャーフラグを使用した段階的なデプロイ

構文がハイライトされたインライン差分には、CDN 経由で Pierre の差分を使用してください。パターンについては references/pr-components.md を参照してください。

---

ビジュアル解説パス

アーキテクチャ図、データテーブル、スライドデッキ、プロジェクトの振り返り、比較、その他あらゆるビジュアル解説に使用します。

生成前に：

1. visual-explainer がインストールされていることを確認します。
   • 確認先：~/.claude/skills/visual-explainer/SKILL.md または ~/.agents/skills/visual-explainer/SKILL.md
   • 見つからない場合：独自にインストールしてはいけません。作業を止め、正確なコマンドを示して、インストールするかどうか尋ねます。 npx skills add nicobailon/visual-explainer -g --yes 相手の同意を得てから実行してください（相手の「はい」が同意となります。--yes を付けない場合、インストーラーはシェルから入力できない応答を待ち続けます）。相手が希望すれば、自分でコマンドを実行することもできます。断られた場合は、このパスには visual-explainer が必要であると伝え、作業を止めてください。Plan パスと PR パスには不要なため、visual-explainer がなくても使用できます。
2. visual-explainer の SKILL.md（ワークフロー、図の種類、アンチスロップ規則）を読む
3. 作成するコンテンツの種類に適した visual-explainer のリファレンスとテンプレートを読む
4. references/theme-override.md を読む — Nico のパレットに代わる Plannotator のトークン
5. コントロールとキャプション付きの拡大縮小可能な Mermaid 図を作成する場合は、references/diagram-shell.md を読み、シェルをコピーしてください。ビューポート、キャンバス、キャプションのマークアップを独自に作成してはいけません。

visual-explainer の構成、コンポーネントクラス（.ve-card、.kpi-card、.pipeline）、アンチスロップ規則に従ってください。オーバーライドで変更するのは色／タイポグラフィのレイヤー（Nico のカスタムパレットの代わりに Plannotator のトークンを使用）と、成果物に拡大縮小可能な図が含まれる場合の references/diagram-shell.md にあるシェルだけです。

---

デザイン哲学（すべてのパスに適用）

• 余白は機能の一部です。 パディングを広く取り、セクション間に大きな間隔を設けます。窮屈な場合は、文字を小さくせず、余白を増やします。
• 1 つのビューポートにつき 1 つのアイデア。 ヒーローセクション、次に図、その次に詳細グリッドのように分け、すべてを詰め込みません。
• 説明するより、見せます。 時系列は順序を、図は関係性を、コードブロックはインターフェースを示します。
• 所要時間の見積もりは含めません。 タイムラインにはフェーズと依存関係を示します。時間や日数の見積もりを付けてはいけません。