explain-with-preview

プレビューで説明する

2 カラム構成の章です。左側には短い導入文とクリックできるカードをいくつか配置し、右側には読者がカードを選ぶと切り替わる固定パネルを配置します。カードを切り替えて見比べると、違いが明確になります。

このスキルを使う場面

• ユーザーが、変更内容をプレビュー付きで視覚的に説明するよう求めた場合。
• オーケストレーターが、変更内容をプレビュー付きで視覚的に説明する場合。

2 つのモード

モード	カード	最初に表示するカード
選択肢（決定）	選択肢ごとに 1 枚、2～3 枚。慎重な選択肢／低リスクの選択肢を含める	推奨する選択肢
変更前／変更後	2 枚のみ：「変更前 · 現状」と「変更後 · 変更を適用」	変更後（"selected"）

内容

• すべての選択肢で、行の順序を含めて同じ行を使い、違いだけが変わるようにします。決定の場合、通常は維持するもの（ok）、失われるもの（removed）、先に修正すること（decision、具体的な対応）、リスク（risk）に加え、effort（所要時間と作業内容）を含めます。各行には、事実に基づく具体的な名称や数値を使い、2～4 件の短い項目を記載します。その選択肢にとって重要な調査結果は、すべていずれかの行に含めます。
• 脆弱性、依存関係、複雑さは、それぞれ独立した章にせず、各行に記載します（例：「先に修正：3 つのパスチェックをローカルプラグインに移植」）。
• ツールや用語は、最初に登場する行で説明します（「nursery（Biome の不安定なルール）」など）。
• code（選択肢ごとに任意）：その選択肢で追加または変更する設定やコードを、ファイルパスとともに実際の行から 8 行以内で記載します。設定やコードを変更する場合は、推奨する選択肢に code を指定します。
• flip：推奨を変更する条件（1～3 項目）。details：「測定方法」（コマンド、バージョン、マシン、実行回数が 1 回か複数回か、測定しなかった内容）と「情報源」（リンク）。
• 実際の内容を使います。説明図には、説明図であることを明記します。

JSON から生成する

章を JSON で記述し、フラグメントを生成します。HTML、CSS、スクリプトを手作業で作成しないでください。

python <explainer-kit>/assets/preview.py decide.json --out frag-decide.html

JSON の形式は preview.py の冒頭と、キットの FRAGMENT-CONTRACT.md（「Preview chapters from JSON」）に記載されています。テキストフィールドには、インラインの <b>、<code>、<a href> を含めることができます。