explain-with-code-walkthrough

コードウォークスルーで解説する

左側の短いステップがスクロールし、右側のコードパネルはビューポートの垂直中央に固定されます。 各ステップでは、該当するファイルをパネルに表示し、そのステップに関係する行をハイライトします。読者は、 現在のコードが提案コードへと変わる様子を確認できます。

このスキルを使う場面

• ユーザーが、コードウォークスルーを使って変更を視覚的に説明するよう求めたとき。
• オーケストレーターが、コードウォークスルーを使って変更を視覚的に説明するとき。

ステップ

• 読者が理解すべき順序で4～8ステップにします（通常は、現在のコード → 変更箇所 → 新しいコード → それを使う人）。
• 各ステップでは、内容を示す太字の一文を置き、その後に短い行を最大1～2行添えます。
• 現在のステップには控えめなマーカーを付けます（キットのev-step.is-active：アクセントの縁と薄い色合い）。ほかのステップは暗くしません。
• 詳細な説明、表、トレースは、各ステップにつき1つのev-moreトグルに入れます。概要には、内部の内容がわかる名前を付けます（例：「5行で十分な理由・ティックトレース」）。クリックする前に、何が表示されるか読者に伝わるようにします。
• トグルの内容は視覚的に表現します。ハイライト付きコード、グループ、ステータスチップ、簡潔な表などを使い、長文の塊は避けます。

コードパネル

• コードベース（または提案コード）から実際のコードを表示し、パネルのヘッダーにファイルパスを示します。各15行以下のスニペットを3～4個表示すれば十分です。
• コンテンツをずらさずにハイライトをアニメーションさせます。フォーカスされていない行を暗くし、フォーカス帯を新しい範囲へ滑らかに移動し、ファイルが切り替わるときはクロスフェードします。読者が見ている間に行を増減させないでください。
• パネルの最初の状態（ファイルとハイライト行）はステップ1に対応させ、ステップ1が現在のステップである間は変更しません。最初の切り替えは、ステップ2が現在のステップになったときに行います。
• 上方向にスクロールして戻ると、前のステップのファイルとハイライトが正確に復元されるようにします。パネルは前の状態ではなく、ステップ番号だけを基準に設定します。
• 新しい行には緑色の+ガターを付け、削除された行には−を付けます。
• 手作業で数えた行番号はずれるため、行は安定したIDで選択します（コードデータ内で行にタグを付けます）。
• スニペットには、関連する行と少しの前後の文脈だけを含めます。ファイル全体を表示せず、省略部分には「⋯ 12 lines hidden」のように記します。可能な限り、横スクロールが必要な行は避けます。

スマートフォン

• スマートフォンでは、コードパネルをステップの上に固定するため、ev-side--pinを追加します。横スクロールが発生しないよう、行は短く（70文字以下に）保ちます。

構築方法

• explainer-kitスキルを使ってフラグメントとして構築します（SCRIPTS-AND-TABS.mdにEV.stepsの説明があります）。インラインコードとトグル内のコードには、キットのコードブロック（data-add、data-hl、data-groups、data-marksを備えたev-code）を使います。
• キットのev-side（左側にステップ）とev-stick（右側にコードパネル。上部バーの下で固定し、垂直中央に配置）を使ってレイアウトします。最初のステップは、上部の余白やスペーサーなしで、コードパネルと同じ高さの列の先頭から始めます。最後のステップが中央まで届くように、下部にパディングを追加します。ステップをev-stepボックスにし、EV.steps(steps, function (i) { … })でパネルを制御します（逆方向スクロールを正しく処理できないIntersectionObserverは使いません）。EV.onShowで初期化し、リサイズ時にフォーカス帯の位置を再計測します。
• 各ステップにidとdata-tocを付け、章の一覧に表示されるようにします。