lesson-screen

レッスン画面

レッスン画面は、小規模なローカルウェブサーバーとブラウザーの1つのタブで構成されます。チューターは引き続きターミナルで教えます。各ステップでフォルダーに画面を1つ書き込み、ブラウザーには最新の画面が表示されます。学習者は選択肢を押したり、画面の一部をクリックしたりできます。そのクリックはイベントログに記録され、チューターは次の返答の前にそれを読みます。

このスキルは、SKILL.md を読み取る任意のエージェント（Claude、Cursor、Codex、OpenClaw、Hermes など）と一緒に使用できます。必要なのは Node.js 20 以降と、同じマシン上のブラウザーです。パッケージはインストールしません。

使用する場面

• コースのチューターがレッスンを教え、学習者が画面を受け入れたとき。対象のチューターは learn、learn-mcp、learn-agent-skills、learn-reverse-engineering、claude-certification、mcpa-certification です。
• 学習者がレッスン、概念、またはシステムを見たいと頼んだとき：「見せて」「図にして」「3Dで」。
• 概念に構造や流れがある、または変化する数値が含まれるとき。読むよりも、見たほうが理解しやすい場合です。

使用しない場面

• 学習者が画面を断った場合。このセッションでは再度提案しないでください。
• 学習者がホストからブラウザーのページにアクセスできない場合（チャットアプリや、ポートフォワーディングを利用できないリモートマシンなど）。aiengineeringfromscratch.com のレッスンページを案内してください。該当するケースは references/hosts.md に記載されています。
• ステップが言葉だけで済む場合（確認の質問、トレードオフ、定義など）。ターミナルで続け、待機画面を表示してください。
• レッスンファイル用の恒久的な図が必要な場合。図のスキルを直接使用してください。このスキルで作成するのは、1人の学習者向けの画面です。

パス

SKILL_ROOT は、この SKILL.md を格納しているフォルダーです。このファイルでは、CLI は node "$SKILL_ROOT/scripts/lesson-screen.mjs" を意味します。

すべてのコマンドは、学習者の作業フォルダーから実行してください。画面は .lesson-screen/screens/ に、ビルドは .lesson-screen/builds/ に保存されます。フォルダーが git リポジトリの場合は、学習者に .lesson-screen/ を .gitignore に追加するよう依頼してください。

開始

1. CLI start --open を実行します。url、screens、state、next を含む JSON が1行で出力されます。
2. クエリ文字列も含めた完全な url を学習者に伝えます。URL 内のキーがページを保護します。
3. いつでも CLI start を再度実行できます。実行中のサーバーが再利用され、ポートは同じままです。
4. 開始に失敗した場合は、その旨を1行で伝えてください。レッスンページのリンクを案内し、指導を続けてください。

コマンドの終了時にバックグラウンドプロセスを終了するホストもあります。そのようなホストでは --foreground と、ホスト独自のバックグラウンドシェルオプションが必要です。詳しくは references/hosts.md を参照してください。

指導の流れ

1. 返答の前に毎回 CLI events を実行します。前回の呼び出し以降にクリックされた内容が出力されます。これらはヒントとして扱ってください。
2. 次の画面を <screens>/<next>-<slug>.html に書き込みます。next は start または CLI status の出力から取得します。
3. ファイル名を再利用してはいけません。ブラウザーには最新のファイルが表示されます。
4. 画面に何が表示されるかを1行で学習者に伝えます。答えはターミナルで尋ねてください。
5. 次のステップが言葉だけで済む場合は、待機画面を書き込みます。

ファイルツールを使って画面を書き込んでください。cat やヒアドキュメントを使って、ターミナルに画面を出力してはいけません。

各ステップで表示する内容

チューターのステップ	画面	信頼できる情報源
問題を提示する	ステップレールと、レッスンの質問を記載したカード	docs/en.md
中心となる概念	レッスンに登録された図を、説明する例に合わせたもの	docs/en.md 内の figure フェンス
構築する	コードトレース：コードのまとまり、実行中の行、変数	レッスンコードの実際の実行結果
使用する	同じ出力を伴う、ライブラリ呼び出しとスクラッチ実装の並列表示	レッスンコードとその出力
確認する	このレッスン用に作成した図	図のスキル、レッスンの本文、実際の実行結果
予測またはクイズ	質問と、ボタン形式の選択肢	quiz.json。答えは含めない

references/screens.md には、すべてのクラスと各画面の完全な例が記載されています。

登録済みの図を最初に確認する

ほとんどのレッスンには、すでにインタラクティブな図があります。新しいものを作る前に、まず探してください。

1. レッスンの docs/en.md で、言語が figure のフェンス付きブロックを検索します。
2. フェンスの最初の行をホスト要素に入れます：<div class="lesson-figure" data-figure="kv-cache-sizer"></div>。
3. data-figure='iso-machine {"machine":"kv-cache"}' のように、フェンスに JSON 設定がある場合はそのまま残します。
4. 設定値を変更する場合は、フェンスですでに使われているキーだけを使用します。

画面はコースの図のランタイムを読み込み、図をマウントします。図の見た目と動作は、レッスンページ上のものと同じです。

その場で図を作る

レッスンに最適な図は、そのレッスン専用に作られたものです。教えながら作成し、See it の段階で使えるようにしておきます。

1. レッスンが始まったら、docs/en.md を読み、レッスンのコードを実行します。
2. レッスンのシステムを1文で表します：「X が Y を通って移動し、その動きは Z を意味します。」
3. 以下の表から形式を1つ選び、所要時間とともに提案します。学習者が承諾してから作成します。
4. 作成中の画面を用意し、ステージの一覧を最新の状態に保ちます。
5. ホストでエージェントを1つ実行できる場合は、作成を2つ目のエージェントに任せます。ターミナルでの指導は続けます。
6. 2つ目のエージェントがいない場合は、ラボまたはクイズの間に作成するか、セッションの最後に図を作ることを提案します。
7. CLI shot で作成物を確認します。すべての画像を見て、問題があれば修正します。
8. CLI publish <page.html> を実行します。そのページが次の画面になります。

形式	作成に使用するもの	所要時間	適した場面
ブループリント	blueprint-figure スキル	5〜10分	名前の付いたパーツで構成される構造がアイデアの場合
メカニズム	motion-figure スキルの tier 2	15〜25分	1つのコントロールが計算結果を変える場合
アイソメトリックマシン	isometric-explainer スキル	40〜90分	アイデアが、ステーション、順序、失敗を伴うプロセスの場合
3D モデル	3D モードを備えたインストール済みの図のスキル、または three.js	60〜120分	奥行きや回転がアイデアの要点である場合、または学習者が 3D を希望する場合

アイデアを示せる最小限の形式を提案します。学習者に時間があり、さらに詳しく知りたい場合は、より大きな形式を提案します。

references/build.md には、作成ステージ、ページの仕様、制作ルール、3D のルールが記載されています。作成のたびに、事前に読んでください。

図のスキル

コースの図のスキルは blueprint-figure、motion-figure、isometric-explainer、course-style です。インストールされていないスキルがある場合は、https://raw.githubusercontent.com/rohitg00/ai-engineering-from-scratch/main/skills/<name>/ からそのファイルを読んでください。

ホストには、3D モードや WebGL エフェクトを備えたアイソメトリックイラストのスキルなど、ほかの図のスキルがインストールされている場合があります。形式を選ぶ前に、ホストのスキル一覧を確認してください。形式に適している場合はそのスキルを使用し、このスキルの正確性に関するルールとページの仕様を守ってください。

レッスン後の練習

CLI practice <lesson-path> は、1つのレッスンの練習ページを次の画面として作成します。内容は4つのパートに分かれています。

• 概要：導入、学習目標、キーを押すと意味が表示される各重要用語のカード。
• ドリル：quiz.json の質問。1〜4 のキーで回答し、Enter キーで次の質問に進み、タイマーは任意で設定できます。
• 復習：間違えた質問が1日後、3日後、7日後、16日後に再び表示されます。
• さらに学ぶ：レッスンページ、レッスンフォルダー、コードを実行するコマンド、演習1つ、参考資料。

以下のルールに従ってください。

• 練習を提案するのは、チューターによるレッスンのクイズが完了した後だけです。ページには解答が含まれます。
• ページは自動採点し、進捗をブラウザーに保存します。ページから何も記録しないでください。スコア、復習キュー、証拠が変更されることはありません。
• クローンがある場合はそこからレッスンを読み込み、ない場合は GitHub から読み込みます。
• quiz.json がないレッスンでは、Key Terms の表から質問が作成されます。

真偽に関するルール

• 数値を決して捏造しないでください。表示値、ラベル、ステップの文言は、レッスンの本文または実際の実行結果に基づくものです。
• 動きのある図を作成する場合は、テスト済みの簡潔な状態モデルを使用します。モデルが各部品を動かし、表示値を書き込みます。
• 学習者が回答する前に、正解、回答番号、説明を画面に表示してはいけません。学習者はページのソースを読めます。唯一の例外は演習ページで、チューターのクイズの後にのみ表示されます。
• クリックはヒントです。クイズの回答、チェックポイントの証拠、ラボの結果として扱ってはいけません。
• 進捗、スコア、証拠は、チューター独自のルールに従って決まります。
• 作成した図にはすべて、このレッスン用にチューターが作成したものであり、コースの作成者によるレビューを受けていないことを示す一文を表示します。
• シミュレーション値またはスケーリングされた値は、すべてページ上でその旨を明記します。

イベント

CLI events は {"type":"events","events":[...]} を出力します。各イベントには type、screen、at と、以下のフィールドが含まれます。

type	フィールド	意味
choice	question、choice、text	学習者が選択肢を押しました
part	part、label	学習者が作成した図の一部について質問しました
step	step、label	学習者が作成した図のステップに移動しました
note	text	カスタム画面からの自由記述のメモです

CLI events --all はすべてのイベントを出力し、読み取り位置を保持します。

停止と保存

• 次のレッスンをすぐに開始する場合を除き、レッスンが終わったら CLI stop を実行します。
• サーバーは2時間操作がないと自動的に停止します。
• 作成したページはディスクから開きます。チューターへの質問はサーバー経由でのみ機能します。
• 学習者が保存したい作成物を、そのソースとともに learning-artifacts/<phase>-<lesson>/ にコピーします。

コマンド

コマンド	動作
start [--open] [--foreground] [--port N] [--host H] [--url-host H] [--assets live|local] [--repo PATH] [--idle-minutes N]	サーバーを起動するか、実行中のサーバーを再利用します
status	running、url、screens、latest、next、未読イベント数を出力します
events [--all]	新しいイベントを出力します
publish FILE [--name SLUG]	作成したページを次の画面として screens フォルダーにコピーします
practice LESSON [--repo PATH] [--name SLUG]	レッスンのパスに対応する演習ページを、次の画面として書き出します
shot TARGET [--width N] [--height N] [--theme light|dark] [--wait MS] [--out FILE] [--chrome PATH]	ローカルの Chrome、Chromium、または Edge で、画面名またはページファイルのスクリーンショットを撮影します
stop	サーバーを停止します

別のセッションフォルダーを指定するには、すべてのコマンドで --dir PATH を使用できます。すべてのコマンドは JSON の1行を出力します。エラーは終了コード 1 とともに、JSON として stderr に出力されます。

デフォルトでは、画面は aiengineeringfromscratch.com から図のランタイムを読み込みます。--assets local を指定すると、クローン内の site/ フォルダーから読み込みます。先にそのクローンで node site/build.js を実行してください。

完了前の確認

• 学習者に、キーを含む完全な URL またはレッスンページへのリンクを渡しました。
• 返信する前にイベントを確認しました。
• 各画面が、ターミナルで教えるステップと一致しています。
• 学習者が回答する前に、回答を表示する画面はありません。
• 作成した図に表示される数値はすべて、レッスンまたは実際の実行結果に基づいています。
• 作成物を公開する前に、両方のテーマで各作成物の CLI shot 画像を確認しました。
• サーバーを停止したか、サーバーが起動したままであることを学習者に伝えました。