visual-plan

目的

vplan CLI を使って、計画をテキストの羅列ではなくビジュアルな MDX ページとして表示します。コンポーネントの語彙は汎用的です。以下の例はコードを題材にしていますが、ソフトウェアの変更だけでなく、製品のローンチ、研究計画、インシデント対応など、あらゆる構造化された計画に適しています。計画に合うコンポーネントを使い、合わないものは省略してください。

何よりも、説明するより、見せましょう。読者が図、フェーズ、表に目を通すだけで計画を把握できるようにします。文章はビジュアルをつなぐためだけに使い、計画そのものを文章で伝えないでください。以下の 見せる、説明しない セクションは、このスキルの核心です。

vplan コマンドが見つからない場合は、まずグローバルにインストールしてください：npm i -g vplan@latest（npm で公開されています）。その後、失敗したコマンドを再実行してください。

ワークフロー

1. .mdx ファイルにプランを記述します。最初に単一の # タイトル 見出しを置きます（これはプランのタイトルになります。フロントマターは不要です）。その後、以下のコンポーネントを使います。import 文を書く必要はありません。常にスコープ内にあります。

2. ユーザーに見せる前に検証します：vplan check <file>.mdx。報告された file:line:col の問題をすべて修正します（有効な列挙値が示され、未知のコンポーネントにはフラグが立ちます）。check は、弱いレンダリング（以下の「注意点」で適用されるもの）にフラグを立てる品質リンターも実行します。警告があると check は失敗するため、警告も修正してください。

3. プランを vplan <file>.mdx で提示します。インタラクティブなレビューはプランを提供する際のデフォルトであり、承認を得るためだけの特別なモードではありません。フィードバックレイヤー付きでプランが開き、ユーザーはセクション全体や選択したテキストにコメントし、<Questions> に直接回答します（各質問はインラインの回答欄になり、入れ子になった選択肢の箇条書きがある質問はクリックできる選択肢になります。選択した選択肢のテキスト（または入力した「その他」のテキスト）が回答となり、Answer to "<question>": として出力されます）。その後、Approve／Deny／Iterate をクリックします。送信されるまで処理はブロックされ、決定、コメント、回答が stdout に出力されて終了します。終了コードは approve が 0、deny が 1、iterate が 2、タイムアウトが 3 です（--timeout のデフォルトは 4h です。タブを閉じると deny として扱われます）。--timeout には必ず ms 形式の単位を付けてください（30s、45m、4h）。数値だけの場合はミリ秒として解釈されるため、--timeout 240 は 240 分ではなく、4 分の 1 秒待機します。これはフォアグラウンドで長時間実行されるサーバーなので、バックグラウンドで実行してください。（明示的な --review フラグも引き続き使えますが、レビューがデフォルトになったため不要です。）コメントには重大度タグが付く場合があります。[must-fix] コメントはブロッキングとして扱い（プランの承認前に必ず対応する必要があります）、[suggestion] またはタグなしのコメントは非ブロッキングの入力として扱います。その後、出力されたフィードバックに基づいて対応します：

   • Approve → 記載どおりにプランを進めます。
   • Iterate → 各コメントに対応してプランを修正し、vplan <file>.mdx を再実行するだけです。レビューデータは同じプラン上で更新され、ラウンド番号は自動的に増加します（上書きする場合に限り -i N を渡します）。Approve または Deny になるまで繰り返します。同じ .mdx ファイルをその場で編集して再レンダリングします。vplan は提示した各プランのスナップショットを（ファイルパスをキーとして）保存するため、次のレンダリングでは前回の表示からの変更箇所が、控えめな git-gutter のアクセントと「N changed」の概要で自動的に示され、ユーザーは差分だけを再確認できます。スナップショットの代わりに明示的なファイルとの差分を取るには --diff <baseline.mdx> を、差分表示を抑制するには --no-diff を渡します（たとえば、初回に変更箇所のない状態で表示する場合）。
   • Deny → いったん停止して再検討し、先へ進まないでください。

   **レビューは、重要度の高いあらゆるプランに適したデフォルトです。**対象を絞ったコメントとインラインの <Questions> への回答により、チャットでのやり取りよりも的確な修正ができ、明示的な Approve でループが終わるため、決着したことが分かります。静的レンダリング（ステップ 4）を使うのは、ユーザーが内容を確認したいだけで、形を整えたり決定したりする必要がない場合に限ります。

4. 静的ページ、ライブリロードのプレビュー、PDF／JPG のエクスポートは、ユーザーが内容を確認したいだけの場合や、レビュー用ではなく共有できるファイルを求める場合に使う、レビュー以外の出力形式です。必要な場合は references/static-exports.md を読み込んでください。これらのコマンドとフラグが記載されています（レビューをデフォルトの手順に保つため、ここには含まれていません）。プランの作成方法（以下のすべて）は、どの出力を選んでも同じです。

正確な prop のシグネチャは、いつでも vplan components を実行して確認できます。

コンポーネント

データコンポーネント（FileTree、Chart、Stat、Compare、Matrix、Questions、Checklist）は、データを props ではなく Markdown の子要素として受け取ります。タグの間に通常の Markdown リスト（Matrix と複数系列の Chart では Markdown の表）を記述してください。属性に指定するのは、スカラー設定（title、type、status）のみです。トークン数を抑えられるうえ、レンダリングを壊す {[{ ... }]} の括弧エラーも避けられます。

• <Phase title="..." status="planned|active|done">：番号付きの縦型タイムラインの1ステップです。Markdown（番号付きリスト、文章、ネストしたコンポーネント）を囲みます。ステップには順番に自動で番号が振られます。計画の主なステップごとに1つ使います。

• 図には ```mermaid のフェンス付きコードブロックを使います。アーキテクチャ（flowchart）、sequenceDiagram、依存関係グラフ、stateDiagram-v2、classDiagram、erDiagram、xychart-beta に対応しています。構造を表すものには、まずこれを使ってください。（gantt と pie はサポートされていません。定量データには <Chart> を使ってください。現在は check が各図を検証するため、サポートされていない種類はエラーボックスとしてレンダリングされるのではなく、file:line:col を示すエラーになります。）

• <Svg src="./diagrams/power-path.svg" title="Power path" caption="Bench unit, splitter-fed" />：アーキテクチャ図や、別のツールからエクスポートしたシーケンス図など、ローカルの .svg ファイルとしてすでに存在する図を埋め込みます。src はプランファイルからの相対パスです。ファイルは読み込まれ、サニタイズされてビルド時にインライン化されるため、ページは自己完結し、図はページのライト／ダークテーマに従います。title はスクリーンリーダーと拡大表示用の名前です（エクスポートされた SVG 自体の <title> は、ツールの既定値であることがよくあります）。caption を指定すると、その下に任意の行を追加できます。Mermaid 図と同じ、ホバーで拡大する全画面ビューアーが使えます。静的な SVG のみ対応しています。<script>、<foreignObject>、イベントハンドラー（on*）、および外部参照（同一ドキュメント内の #fragment ではない href、src、url(...)、@import）は、削除されずに拒否されます。その理由は check によりタグの行で報告されます。最大サイズは 2 MB です。図がすでにファイルとして存在する場合にのみ使い、テキストで表現できる場合は ```mermaid 図を記述してください。

• LaTeX で記述したディスプレイ数式を数式として組版するには、```math のフェンス付きコードブロックを使います（計算量の上限、確率、線形代数など）。例：```math のあとに T(n) = O(n \log n) と記述します。

• <Callout type="note|tip|risk|decision|warn">：リスク、決定、ヒント、注記を強調します。Markdown を囲みます。（note は青、tip は緑、decision は紫、risk は赤、warn は黄色です。）

• <FileTree>：ファイル変更マップです。ファイルごとに1つの箇条書きを使い、- <change> <path> の形式で記述します。change は add|modify|delete|move のいずれかです。移動には移動元と移動先の両方が必要です。- move <from> -> <to> と記述すると、移動元を表示しつつ、ファイルは移動先に表示されます。末尾が / のパスはディレクトリ全体を示します（例：- delete src/legacy/）。パスの拡張子に応じて、色付きのファイル種別アイコンが自動で追加されます。変更の短いインラインコメント（その変更の内容や理由）を付ける場合は、任意の行に -- <note> を追加します。ファイル名と同じ行に表示されるため、コメントは短い語句にしてください。

  <FileTree>
  - add src/gateway/rate-limiter.ts -- sliding-window check against Redis
  - modify src/gateway/middleware.ts -- mount the limiter behind the flag
  - delete src/gateway/legacy/
  </FileTree>
  

• <Chart type="bar|line|area|scatter|radar|gauge|funnel|treemap|pie" title="...">：見積もりや指標に使います。単一系列では、データポイントごとに - <label>: <value>（数値）という箇条書きを1つ記述します。複数系列（bar／line／area／radar）では、ヘッダーを category | series1 | series2 とする表を使います（最初のセル以降のセルが系列名となり、凡例に表示されます。最初の列はカテゴリ軸です）。詳細：scatter は x と y として読み取られる値の列をちょうど2列含む表です（| point | x | y |）。pie／gauge／funnel／treemap は常に単一系列で、リスト形式のみ対応します（表は拒否されます）。gauge は 0～100 のスケール、funnel は降順にします。複数系列の bar／area に stacked を追加すると（<Chart type="bar" stacked>）、グループ化ではなく積み上げ表示になります。

  <Chart type="bar" title="Effort (days)">
  - Limiter: 2
  - Dashboards: 1
  </Chart>
  
  <Chart type="line" title="Latency by stage (ms)">
  | Stage | p50 | p95 |
  |-------|-----|-----|
  | Auth  | 12  | 30  |
  | DB    | 40  | 120 |
  </Chart>
  

• <Compare>：アプローチを長所／短所のカード形式で並べて比較します。各選択肢は ## Name 見出し（推奨するものには (pick) を追加）に続けて、必要な数の - pro: ／ - con: 箇条書きを記述します。

  <Compare>
  ## Redis sliding window (pick)
  - pro: accurate
  - pro: shared across nodes
  - con: network hop
  
  ## In-memory token bucket
  - pro: fast
  - con: per-node only
  </Compare>
  

• <Matrix>：複数の選択肢を複数の観点で評価するための比較表です（列に選択肢、行に評価基準）。Markdown の表を記述します。1 列目は行のラベルにし、推奨する列の見出しに (pick) を追加して強調します。長所／短所には <Compare>、評価表には <Matrix> を使います。

  <Matrix>
  | Dimension | Postgres (pick) | ClickHouse | DynamoDB |
  |-----------|-----------------|------------|----------|
  | Writes    | medium          | high       | high     |
  | Querying  | high            | medium     | low      |
  </Matrix>
  

• <Questions>：構築前に読者に解決してほしい未解決の質問を、1 つずつ箇条書きにします。不確実な点を文章の中に埋め込む代わりに使います。タイトルは既定で "Open questions" です。title="..." で変更できます。--review セッションでは各質問に直接回答できるため、レビュー担当者に特定の質問への回答を求める場合は、文章よりも <Questions> ブロックを優先してください。 質問の下に箇条書きをネストすると、複数選択肢を提示できます。レビューではクリック可能な選択肢（および自由記述の「Other」フィールド）になり、選択した項目のテキストが回答として返されます。想定される回答を列挙できる場合は、選択肢を提示してください。文章よりも明確で実行可能な回答が得られます。下位の箇条書きがない質問は、自由記述になります。

  <Questions>
  - Should the limiter fail open or fail closed if Redis is unreachable?
    - Fail open, availability first
    - Fail closed, safety first
  - Is a 15-minute access-token TTL acceptable?
  </Questions>
  

• <Checklist title="Done when">：受け入れ基準／完了の定義を、Markdown のタスクリストで記述します。完了には - [x]、未完了には - [ ] を使います。

  <Checklist title="Done when">
  - [x] Returns 429 over the limit
  - [ ] Dashboards live
  </Checklist>
  

• <Stat>：計画の主要な指標をカードのグリッドで表示します（変更したファイル、推定稼働率、ロールアウトなど）。箇条書き 1 つにつきカード 1 つを記述し、形式は - <label>: <value> (<intent>) -- <caption> です。intent は note|good|warn|risk のいずれかで、(intent) と -- caption は省略できます。value は数値ではなく、自由形式のテキストです（5 min、99.9% など）。時系列データではなく、静的な事実に使います（時系列データには <Chart> を使います）。特に目立つ数値を提示する価値がある場合にのみ <Stat> を追加してください。ほとんどの計画には該当する数値はなく、指標を捏造したり埋め草として追加したりするより、コンポーネントを省略する方が適切です。

  <Stat>
  - Files changed: 12
  - Est. uptime: 99.9% (good)
  - RPO: 5 min (risk) -- worst-case data loss
  </Stat>
  

• フェンス付きコードブロックは構文強調表示されます（Expressive Code）。重要なスニペットを表示するには、```ts（または js、json、bash、 python、go、rust、sql、yaml など）と記述します。ブロックにファイル名のヘッダーを表示するには、```ts title="src/path/file.ts" のようにファイル名を追加します。

• コードブロック内の行やテキストは、フェンスのメタ文字列に Expressive Code のプロパティを指定してマークします（コンポーネントは不要です）。マーカーは mark（中立、既定）、ins（緑、追加）、del（赤、削除）の 3 種類です。それぞれ、行番号、範囲、引用符で囲んだ文字列、または /regex/ を指定できます。計画によって変更される行を目立たせるために使います。

  • 行／範囲（中立）：```ts {2}、```ts {2-4}、```ts {1, 3, 5-6}
  • 行の種類を指定：```ts ins={3-4} del={2} mark={6}（1 つのブロック内で自由に組み合わせられます）
  • インラインテキスト：```ts "TokenBucket"、名前の変更は ```ts del="oldName" ins="newName"
  • 正規表現（キャプチャグループも指定可能）：```ts /\bTODO\b/、```ts ins=/const (\w+) =/（グループをマークします）

説明するのではなく、見せる

ビジュアルプランの目的は、文章の壁を、ひと目で把握できるものに置き換えることです。文よりコンポーネントを優先してください。事実に構造があるなら、段落で説明するのではなく、見せましょう。文章はビジュアルをつなぐ役割にとどめ、内容の本体にはしないでください。

• 構造を先に示します。 最初に置く背景説明は最大1段落にして、そのあとに```mermaidのアーキテクチャ図（図がファイルとしてすでに存在する場合は<Svg>）、続いて<Phase>のタイムラインを配置します。読者が文章をひとつも読み切る前に、プランの全体像を理解できるようにしましょう。
• 構造を言葉で説明するより、図や<FileTree>を優先します。 データの流れをたどる段落よりフローチャート、ファイル名を並べる文章よりファイル変更マップが適しています。
• 意味は、それを伝えるコンポーネントに集約します。 リスクや決定事項は<Callout>に、未解決の質問は<Questions>に、トレードオフは<Compare>／<Matrix>に、受け入れ条件は<Checklist>に記載します。読み飛ばされやすい段落に埋め込まないでください。
• 各フェーズの文章は簡潔にします。 <Phase>はステップであり、エッセイではありません。意図を1～2行で示し、そのあとにビジュアルを配置します。要点はビジュアルです。
• 見せる内容の規模を適切にします。 大規模な取り組みでは、図と複数のフェーズから始めます。ファイルが2～3個変わるだけなら、短い<FileTree>と<Checklist>だけで十分な場合があります。情報を何も伝えない図やフェーズは追加しないでください。ノードが2つだけの空疎なフローチャートは何も示さず、簡潔な一文より劣ります。見せるべき構造があれば見せ、なければ簡潔な一文で構いません（これは<Stat>にも当てはまります。詳しくは各項目の説明を参照してください）。

プランの構成

• <Phase>と<Callout>の中には、任意のMarkdownやコンポーネントを配置できます。<FileTree>、<Chart>、<Matrix>、```mermaidの図、コードブロック、- [ ]のタスクリストなどを入れ子にできます。ステップや強調表示の中に関連する内容をまとめるため、自由に入れ子にしてください。
• 図、チャート、<Svg>にはそれぞれ、ホバーすると「拡大」ボタンが表示されます。これをクリックすると、ズームやパンができる全画面ビューアーが開きます。そのため、インライン表示で縮小されていても、密度の高い図を読みやすく保てます（コードブロックは対象外です）。必然的に大きくなる図にはこの機能を活用できますが、インライン表示だけで内容が把握できる場合でも、図を小さく分けたほうが読みやすくなります。

ルール

• ユーザー向けのプランで--no-openを指定してはいけません。 目的はユーザーにプランを見てもらうことです。レビューセッションは自動的に開きます。--no-openは、明示的にヘッドレス／CI実行が求められた場合に限って使用してください。
• 画像や外部アセットは使用しないでください。 ページは自己完結型の単一ファイルなので、Markdown画像（![](url)）や外部アセットは埋め込めず、checkではMarkdown画像が拒否されます。ビジュアルには```mermaidの図を、ローカルの.svgファイルとしてすでに存在する図には<Svg>（ビルド時にインライン化されるため、外部アセットではありません）を使用するか、テキストで説明してください。

注意事項

これらのいくつか（文章が壁のように続くフェーズ、横幅の広い LR mermaid 図、長すぎる Matrix セル、コメント付きの FileTree の move 行、スケールが大きく異なる Chart）は、現在 check 品質 lint で検査され、違反すると失敗するため、単なるスタイル上のアドバイスではなく、必ず守るべきルールです。

• 文章中の <、{、} は MDX の構文です。 裸の <Thing> や {value} はレンダリングを壊すことがあります。リテラルの山かっこ、中かっこ、ジェネリクス（List<T>）、タグのようなテキストは、すべての文字が安全にそのまま表示されるよう、バッククォートかコードフェンスで囲んでください。
• 生のインライン HTML タグは check に失敗します。 <kbd>、<sub>、<sup>、<details> などは不明なコンポーネントとして読み取られ、エラーになります。代わりにバッククォートかプレーンテキストを使ってください。それ以外のプレーンな Markdown はコンポーネントと併用できます。GFM テーブル（<Matrix>／<Chart> の外）、引用、脚注、~~取り消し線~~、自動リンク、- [ ] タスクリスト、番号を任意の値から始める順序付きリストは、すべてレンダリングされます。
• <Chart> が示すのはデータの形であり、正確な数値ではありません。 棒の上に値のラベルは表示されないため、読者に正確に知ってほしい数値は、文章にも記載してください。ラベルは1、2語程度にしてください（長い棒グラフ／折れ線グラフの x 軸ラベルは省略されたり、詰め込まれたりします）。また、スケールが大きく異なる系列を1つのチャートに入れないでください。50に近い値と2,000,000に近い値を並べると、同じ y 軸が使われ、小さい系列はゼロの線に押しつぶされます。チャートを分けるか、同じ単位に正規化してください。
• <Matrix> のセルでは折り返しが行われません。 1つのセルに長い文を入れると横スクロールバーが表示され、ほかの列が画面外に押し出されます。セルには1語か短い評価のみを入れ、理由は文章か <Callout> に記載してください。
• <FileTree> の move 行では -- コメント を避けてください。 move は元のパス（← <from> の注記）をすでに表示するため、行の大部分を占め、同じ行にコメントを入れると混み合います。move 行にはコメントを付けず、説明は文章か <Callout> に記載してください。-- コメント は、余裕のある add／modify／delete 行に使ってください。
• 横幅の広い mermaid 図は、縮小されて判読できなくなります。 ノードが多い図では、上から下へ流れる形式（flowchart TD）を優先してください。左から右へ長く続く（LR）チェーンは、ページに収めるために縮小され、インラインでは実質的に読めなくなります。大きなフローは、1つの広大な図ではなく、いくつかの小さな図に分割してください。