rzhang569/study-guide

学習ガイド

自己完結型のHTMLページを試験ごとに1つ生成します。このページは、プレーンテキストファイル群を含むコースフォルダから scripts/build.py によってビルドされます。ページは3つのパートで構成されます。

• ノート: 講義ごとに1セクション。すべての主張にスライドのページ番号を引用します。各トピックには、わかりやすい説明ボックス、実例、図、および赤い「トラップ」ボックスが付属します。各セクションの末尾にある練習ボックスで、学生は読んだ直後に自己テストを行えます。
• 練習センター: 4つのタブがあります。
  • 即時フィードバックと各選択肢の解説を提供する練習問題バンク。
  • 部分点のある段階的な記述問題。
  • 実際の試験の構成に合わせた専用プールから出題されるタイムド模擬試験。
  • 自動的に記録される間違いノート。
• 進捗レポート: ページが自動的に記録します。後でレポートを確認し、学生が実際に間違えた問題をターゲットにした新しいドリルを作成できます。

エンジン（assets/engine.js）とスタイル（assets/page.css）は完成してテスト済みです。あなたの仕事はコンテンツと問題の作成です。ページの有用性のほとんどはリファレンスファイルに依存しています。該当する手順に進んだらそれらを読んでください。

これから行う作業	読むファイル
講義セクションの作成	references/content-standard.md
問題の作成または監査、模擬試験の調整	references/question-bank.md
フィールド名、進捗形式、データベースドキュメントの確認	references/data-format.md

examples/demo/ は、完全な小規模コース（架空の PROB 101、3つの講義）です。どのように見せるべきか不明な場合は、そのソースファイル（sections/*.html、practice.json、mock.json、short.json）のパターンをコピーしてください。

assets/engine.js、assets/page.css、またはビルド済みの review.html は読まないでください。build.py がそれらをインライン化します。これらは数万トークンあり、編集が必要なものは何も含まれていません。

以下のコマンドで、<skill-dir> はこの SKILL.md を含むフォルダです。python3 が見つからない場合（Windowsでよくある）、python または py -3 を使用してください。

1. 試験内容の確認

何を書くよりも先に、以下の事実を確認してください。可能な限り自分で調べ、どうしても見つからない場合のみ学生に質問してください。

• 試験: 日時、時間（分）、対象となる講義範囲、形式、および持ち込み許可物。形式とは、問題の種類、各問題の数と配点を意味します。持ち込み許可物とは、ノート、電卓、または無しを意味します。
• ソース: スライド（PDFまたはリンク）、リーディング課題、コースウェブサイト、および公式の練習問題、小テストの結果、サンプル試験。
• 学生: ページに使用する言語（lang: インターフェースは zh または en。コンテンツは学生の言語で記述）、および学生の基礎知識レベル。「まったくわからない」と言う学生には、ほぼすべてのトピックにわかりやすい説明ボックスが必要です。

閲覧できる場合は、コースのスケジュールページ、シラバス、公開されている小テストの結果などを自ら調査してください。学生に伝える価値のあるパターン（例：「授業内確認問題は特定のスライドの直後に出題される」「公式問題バンクは試験と同じ形式を使用している」など）を探してください。ロジスティクス情報はページのヒーローセクションに配置してください。

シラバスでコースのAIポリシーを確認してください。一部のコースでは、AIが生成した学習教材を禁止したり、採点対象の課題へのAI利用を禁止しています。ポリシーがこれを禁止している場合は、ビルドを開始する前に学生に伝えてください。採点済みの宿題の答えをページに決して掲載しないでください。

2. ネタバレなしで模擬試験を調整する

学生は多くの場合、公式のサンプル試験をタイムドで一度だけ使用するために温存したいと考えます。その場合は、その問題を読まずに、代わりに計測してください。

python3 <skill-dir>/scripts/count_exam.py sample_exam.pdf

このスクリプトは、問題、選択肢、またはシナリオのテキストを決して出力しません。出力するのは以下の情報です。

• ページ数と問題数、および問題ごとの選択肢の数。
• 配点、制限時間、表紙の指示（電卓、ノートの可否）。
• パートの見出しと、シナリオを共有する問題の範囲（「問題11～14...」）。
• 以前の資料を参照する問題の番号。

出力を使用して、模擬試験のセクション（タイプと数）と制限時間を設定します。以前のシナリオを再利用する記述問題など、参照を含む問題は、試験の構造を説明する際にそのシナリオに属するものとして扱います。

スクリプトが何かを伝えられない場合は、不明として報告し、学生に表紙を確認するように依頼してください。問題内部から単語や数字を出力するような独自の調査ツールを作成しないでください。偶発的な「合計」や「%」でさえ問題のトピックを示唆し、数式内の数字は問題を特定可能にしてしまいます。

サンプルや解答キーを開く前には必ず許可を求めてください。学生が読むことを許可した場合でも、調整（構造、難易度、スタイル）にのみ使用してください。その問題やシナリオをページにコピーすることは決してしないでください。

3. コースフォルダのセットアップ

python3 <skill-dir>/scripts/build.py --init <course-dir>

これにより、デモコースがコピーされます。次に course.json を編集します。

• title、lang、lectures。講義ラベルは、問題やグループが使用するものと正確に一致させます（例："L1" または "L5–L6"）。
• storageKey: コースと試験ごとに一意に設定します（例："bio201-mt1"）。進捗はこのキーの下に保存されるため、学生が使い始めたら決して変更しないでください。
• mock.sections: 問題タイプごとに1エントリ、試験の順序で、実際の試験用紙と一致する数で設定します。
• mock.minutes: 選択可能な制限時間を設定します。実際の試験時間を含め、模擬試験が長文問題を省略する場合は、それに比例して短い時間も提供します。

デモのセクションと問題を新しいものに置き換える際に削除してください。すべてのフィールドについては references/data-format.md を参照してください。

4. セクションの作成

講義ごとに1ファイルを sections/ に作成します（10-l1.html、20-l2.html...）。さらに、ロジスティクス情報用の 00-hero.html と、最後にトラップのリストを作成します。各講義は <section class="part" id="..."> です。練習グループがその id を "sec" で指定すると、練習ボックスが自動的に表示されます。

references/content-standard.md には、完全なレシピとすべてのコンポーネントのHTMLが記載されています。要約: すべての主張を引用し、難しい講義は用語集と類推で始め、各トピックに一行のリード文、公式の前に具体的な例、わかりやすい説明ボックス、図が役立つ場所には図、そして○×問題がひっかけようとするところにトラップボックスを配置します。

5. 問題の作成

3つの問題バンクがあります。references/question-bank.md にルールと監査チェックリストがあります。

• practice.json: 講義ごとに8～15問。単一選択、○×、複数選択、穴埋め、および時折フラッシュカードを混在させます。すべての選択肢に個別の解説があります。
• mock.json: 専用の問題です。練習問題のコピーは絶対に使用しません。各タイプから試験1回分が抽出する数の約2倍を用意し、別の試験用紙が異なるものになるようにします。実際の試験のスタイルに一致させます。
• short.json (オプション): 試験の記述問題タイプを段階的に解くバージョンです。各ステップは、寛容な穴埋め、選択、または模範解答との自己チェックです。

6. ビルドと確認

python3 <skill-dir>/scripts/build.py <course-dir>

エラーがあるとビルドは停止します。警告は問題バンクのチェックから発生します。特別な理由がない限り修正してください。警告は以下のようなパターンを指摘します。

• 正解が多すぎる問題で最長の選択肢になっている。
• 特定の文字が正解として表示される頻度が高すぎる。
• すべての複数選択問題で選択肢の数が同じである。
• 模擬試験の問題が練習問題を数字だけ変えたものである。

--strict を追加すると、警告が発生した場合にビルドが終了コード2で停止するようになります（ページ自体は書き込まれます）。これにより、警告がなくなるまで修正を続けることができます。その後、ブラウザで <course-dir>/review.html を開いて確認します。

• コンソールにエラーがなく、数式がレンダリングされること。
• 練習問題、記述問題のステップ、フル模擬試験の回答が機能すること。
• 375px幅の画面でページが横方向にスクロールしないこと（図や表はボックス内でスクロールします）。
• 図内のテキストが線、矢印、または他のテキストと重なっていないこと（スクリーンショットを撮って確認）。

7. 納品

• ローカル（任意のエージェント）: ファイルパスを伝えます。進捗はそのブラウザのlocalStorageに保存されます。練習センターの「進捗をエクスポート」ボタンで、学生があなたにペーストして送れるJSONが得られます。
• claude.ai アーティファクト（Claudeのみ。実験的、エンドツーエンド未テスト）: ビルド済みのHTMLを公開し、db ケイパビリティを許可します。window.claude.use("db") が利用可能な場合、エンジンは進捗をドキュメント progress/practice と progress/mock にミラーリングし、progress/report にサマリーを保持します。これに依存する前に、公開されたページで1問回答し、progress/report を読み返してください。ドキュメントがない場合は、代わりに「進捗をエクスポート」を使用するよう学生に伝えてください。

ページの使い方を学生に2～3行で伝えてください。セクションを読み、その練習ボックスを行い、終盤に模擬試験、前日に間違いノートを使用するよう指示します。

8. フィードバックループを閉じる

学生が戻ってきたら、何かを変更する前に進捗を読んでください。学生がペーストまたは送信したエクスポートJSON（その report フィールド）、またはアーティファクトの同期が機能している場合は progress/report データベースドキュメントを使用します。レポートには以下がリストされます。

• 講義ごとの初回正答率。
• 間違えたすべての練習問題と、学生が答えた内容および正解。
• 間違えた記述問題のステップ。
• 模擬試験の履歴と、最後の試験用紙の間違いおよびフラグが立てられた問題。

その後、以下の手順を実行します。

1. 弱点を数行で特定します。初回正答率が約80%未満の講義、繰り返される誤解、および失敗し続ける記述問題のステップを数えます。また、正解ではあるが「自信がない」とフラグが立てられた問題も数えます。これらも不安定な知識です。
2. 各弱点に対する新しいドリルを作成します。同じ概念を異なる言い回し、数字、またはシナリオで再度質問します。学生が間違えた問題を繰り返すことは決してしないでください。新しいIDで practice.json に追加し、mock.json の該当プールが薄い場合はそちらにも追加します。
3. 説明を修正します。問題だけでなく、誤解が繰り返される場合は、おそらくセクションの説明が不十分です。その誤解を正確にターゲットにした、わかりやすい説明ボックス、実例、または図を追加します。
4. 再ビルドし、何が変わったか、どこが変わったかを学生に伝えます。

編集中に既存の進捗を有効に保つ

レコードは storageKey、質問 id、および元の選択肢インデックスによってキー付けされます。そのため、以下の点を守ってください。

• storageKey と既存のIDは維持すること。
• 回答済みの質問では、選択肢の並べ替え、挿入、削除を行わないこと（代わりに新しい質問を追加します）。
• 古いIDを別の質問に再利用しないこと。
• 質問の意味や正解が変わった場合は、新しいIDを与え、古いIDを削除すること。削除されたIDのレコードは無視され、誤って読み取られることはありません。

エンジンはIDからのシードを使用して選択肢の表示順序をシャッフルするため、保存されたインデックスは正しいままです。選択肢の表示文字を変更するには、選択肢を並べ替える代わりに "show" を設定してください（references/data-format.md を参照）。問題文や解説のタイプミスや文言の修正は常に安全であり、セクションHTMLの編集も同様です。

学生からの要望

実際の試験で使用された復習ページの構築から得られた教訓です。

• 抽象的な説明は理解されませんでした。学生はまず具体的な数字（「コインを10回投げて...」）を求め、次に公式を求め、導出は折りたたんで「試験範囲外」とラベル付けしました。
• 練習前に複数の講義を勉強するのは疲れるものでした。そのため、すべてのセクションは独自の練習ボックスで終わります。
• フォーマットの厳格さは苛立たしいものでした。例えば、1/2 の代わりに 0.5 と書かないと不正解とされるなど。エンジンは数値解答を値で比較します。テキストのバリアントは accept にリストしてください。
• 学生は解答のパターンを素早く学習します。正解が最も長い選択肢であることが多く、すべての複数選択問題が3つの選択肢を持ち、正解が常にBでした。ビルドスクリプトは最初の2つを監査し、エンジンが表示順序をシャッフルします。
• 練習問題を再利用した模擬試験は、理解ではなく記憶を測定しました。そのため、模擬試験プールは別になっています。
• 学生は、選択肢のテキストを選択してコピーできること、および時間切れで自動的に提出されるタイマーを望みました。