course-content-authoring

コースコンテンツの作成

スキーマの正規定義：すべてのプリミティブフィールド名（unit／concept／prompt／task／material／quiz／faq／illustration）は、_shared/domain-primitives.md に定義されています。このスキルでフィールドに言及する場合は、このファイルを正としてください。

ファイル名の規則（英語優先）：生成するすべてのファイルとディレクトリには、英語名を使用します。従来の中国語名との対応は、_shared/domain-primitives.md §0 に記載されています。

このスキルでは、コースの教育内容、つまり学習者が読んだり、コピーしたり、聞いたり、取り組んだりするものを作成します。すべての成果物を course-outline-design のアウトライン ID に紐付けることで、次の段階（SPA への変換）で機械的に接続できるようにします。

成果物（標準レイアウト）

course-package/   (your project's content root)
├── day{n}/
│   ├── outline.md           ← from outline stage (do NOT edit here)
│   └── content.md           ← THIS skill writes: lecture script, prompts, exercises, references
├── shared-scenario.md            ← from outline stage
├── supporting-docs.md            ← THIS skill writes: FAQ, environment setup, pre-reading
└── materials/                  ← THIS skill writes: standalone learner artifacts
    ├── README.md             ← index of materials
    └── *.md, *.csv, *.yaml   ← samples, templates, datasets

教材の種類（コースに合ったものを選ぶ）

サンプルワークショップでは以下を使用していますが、これらは要件ではなく例です。コースごとに適切なものを選んでください。

種類	形式	使用する場面
講義原稿	.md	日ごとの講義内容。content.md に埋め込みます
サンプル文書	.md	学習者が改善する「改善前」の成果物（例：FAQ、ポリシー文書）
表形式データセット	.csv（UTF-8 BOM!）	AI 処理の演習に使う練習用データ
構造化設定	.yaml	演習で宣言型の設定を扱う場合
PDF 参考資料	.pdf	公式文書（法律、規制など）。通常は外部ソースです
プロンプトテンプレート	.md ブロック	ドメイン固有の再利用可能なプロンプト（このコースではRTFCフレームワークを使用しますが、他のコースでは使用しない場合があります。コースの教育方針に合わせて調整してください）
クイズ項目	content.md 内に記述、または別ファイル	事前テスト、事後テスト、理解度チェック
ワークシート	.md	学習者が記入するテンプレート

プロンプトテンプレートについて：このスキルは、使用するプロンプトフレームワークを問いません。元のワークショップでは RTFC（Role／Task／Format／Context）を使用していましたが、コースで別のフレームワーク（例：CRISPE、COSTAR、シンプルな例示）を教える場合は、それを使用してください。適さないコースに RTFC を無理に当てはめないでください。フレームワークはこのスキルの特性ではなく、コースコンテンツの一部です。

CSV の落とし穴（見落としがち）

開発者以外の学習者が Excel で開く CSV ファイルを生成する場合は、先頭に UTF-8 BOM（）を付加してください。

const content = '' + headerRow + '\n' + dataRows.join('\n');

これがないと、Windows 版 Excel がエンコーディングを誤認し、文字化けが発生します。学習者はファイルが壊れていると思うでしょう。この不具合はサンプルワークショップの終盤で見つかりました。最初から組み込んでください。

すべてをアウトライン ID に紐付ける

作成するすべての成果物は、単元 ID まで追跡できなければなりません。講義ノートには、次のヘッダーパターンを使用してください。

## u-3: {Unit title from outline.md}

**對應任務**: d2-u3-t1, d2-u3-t2
**對應素材**: 客訴處理SOP.md, FAQ官方版.md
**圖片需求 (illustrations)**:
- `day2-u3-hero.png` — hero / 主視覺：{學員角色} 在 {情境} 操作的場景圖（AI 生圖）
- `day2-u3-flow.svg` — 概念流程：{步驟 A → B → C}（手繪 SVG，含中文標籤）
- `day2-u3-example.png` — 結果範例截圖（選填）

{lecture content here}

理由：SPA への変換段階では、これらのマーカーを読み取り、タスク、教材、コンテンツ、ビジュアルアセットのスロットを自動的にリンクします。マーカーを省略すると、SPA の作成者は接続方法を把握するためにすべてを読み直す必要があります。また、ステージ 5（web-visual-assets）では生成対象の仕様がなくなり、カバー画像しかないサイトになってしまいます。

タスク ID は永久に使う

content.md にタスクの説明を書くときは、それぞれに安定した ID（例：d2-u3-t1）を割り当ててください。これらの ID は、デプロイされたウェブサイトでlocalStorage のキーになります。次の 3 つのルールを守ってください。

1. 公開済みのタスク ID は変更しないでください。 学生の進捗はこの ID に紐付けられています。
2. 削除したタスク ID は再利用しないでください。 タスクを削除した場合、その ID は永久に廃止します。
3. 実際には 2 種類の形式（d{n}-u{m}-t{k} と day{n}-u{m}-t{k}）が併存しています。新しいコンテンツではどちらか一方を選び、混在させないでください。

クイズ項目の管理

コースにクイズがある場合は、項目に連番（q1、q2、...）を付けてください。SPA では、これらの番号が複数の場所に反映されるため注意してください。

• クイズ配列そのもの
• 各項目を元の章に対応付ける qIndexToDay() 形式のヘルパー（不正解の場合に戻り先を案内するため）
• SPA 内のハードコードされた文字列："結訓測驗（N題）"、スコア表示 — / N、合格基準 s >= K

番号変更に強い作成方法：クイズは追記専用と考えてください。q3を削除する場合は、草稿ではその枠を空けたままにし、最終的に安定した段階でのみ番号を振り直してください。その際は、更新が必要なすべての箇所をチェックリストで確認してください。

非表示教材のパターン

一部の教材は講師専用（解答集、事前／事後テストの採点など）、または条件付き（機能フラグが有効な場合のみ表示）です。materials/README.md で明示してください。

| 素材 | 對象 | 備註 |
|---|---|---|
| 員工差勤辦法.md | 學員 | Day 2 公開素材 |
| 結訓測驗解答.md | 講師 | 不要納入 SPA materials[]，僅講師端使用 |

SPA への変換段階では、この列を読み取り、講師専用の項目を除外します。

アンチパターン

• アウトラインを確定する前にコンテンツを書く — 後からの修正が複数のファイルに波及します。
• コースで実際に教えないプロンプトフレームワークを埋め込む — コースで RTFC を使わないなら、サンプルテンプレートにあるからという理由だけで無理に当てはめないでください。
• 元の章との対応付けがないクイズ項目 — 学習者が不正解だったとき、どこを復習すればよいか分かる必要があります。各クイズ項目に、出題元の単元をタグ付けしてください。
• 講師／学習者の区別がない、長いフラットな教材リスト — Day 4 までに、講師が各ファイルの内容を把握できなくなります。
• CSV の BOM を忘れる — 上記を参照してください。

完了ゲート（必須ルール — 引き渡し前に合格すること）

「コンテンツ草稿が完成しました」と宣言して static-spa-conversion を提案する前に、以下の各項目について、対応する .md ファイルに記述された成果物があることを確認してください（口頭で「はい」と答えるだけでは不十分です）。ユーザーと一緒に項目を確認し、成果物の内容が薄い、または存在しない場合は、確認の質問を1つして、先へ進む前に仕上げてください。

1. overview.md の 每日主題 表で宣言されたすべての Day について、日ごとの content.md が存在すること。タイトル見出しだけの日別ファイルは不合格です。単元セクションを含める必要があります。
2. アウトライン内のすべての単元 ID に対応する ## u-{id} セクションが、その日の content.md にあること。簡単な差分確認を行ってください：day{n}/outline.md の単元 ID 一覧が、day{n}/content.md の ## u- 見出しにすべて含まれている必要があります。セクションが不足している場合は不合格です。
3. すべての単元セクションに実質的な内容があること。次のうち少なくとも1つを満たしてください：講義台本が約10行以上、実際のタスク ID を列挙した **対応タスク**、実際の教材ファイル名を列挙した **対応教材**。見出しと TODO プレースホルダーだけの単元は不合格です。
4. すべての単元セクションに **画像要件 (illustrations)** が宣言され、1〜3件の項目があること。各項目には、（a）ファイル名のベース名（例：day2-u3-hero.png）、（b）画像の種類（hero／diagram／screenshot／scene）、（c）ビジュアル素材の制作者向けの1行仕様を記載してください。画像が本当に不要な単元では、免除理由を記した1行だけを宣言してください：- waived: {理由、例：5分間の管理用枠}。何も記載しない場合は不合格です。
5. （該当する場合）クイズ項目に sourceUnit タグが付いていること — すべての q* 項目が実在する単元 ID を参照し、不正解の場合に学習者を元の章へ誘導できるようにしてください。タグのない項目は不合格です。
6. materials/README.md が存在し、教材インデックスがあり、「学習者」と「講師」の列が区別されていること（上記の「非表示教材のパターン」を参照）。

すべての項目に記述された成果物がそろう前に、ユーザーが「できました。先にウェブページに変換してください」と急かした場合は、丁寧に断ってください。

「Stage 2 では、実質的な内容（または画像要件）が未作成の単元がまだ N 個あります。このまま Stage 3 に進むと、中身の薄いウェブページができあがり、学習者に表示されるのは見出しだけで、画像もありません。まず第 X 項目を補いましょう。およそ Y 分かかりますが、後からウェブページを作り直すより何倍も効率的です。」

ユーザーが薄いデモを明示的に求めた場合（teaching-site の Stage 2 Override Policy と同じ条件）、オーケストレーターの文書にある3つの手順（stub コメントを付ける、__thinDemo: true を設定する、学習者に表示される内容を明確に伝える）に従ってから許可してください。Stage 2 の内部でこっそり基準を緩めてはいけません。

引き継ぎ

このステージが完了すると（完了ゲートを通過すると）、次の状態になっているはずです。

• 日ごとの content.md が記入され、アウトラインのすべてのユニット ID が ## u-{id} セクションで網羅されている
• 各ユニットのセクションに、講義スクリプト＋タスク＋教材の参照＋「挿絵の要件（イラスト）」が1～3項目含まれている
• すべての教材ファイルが materials/ にあり、インデックス README で受講者向け／講師向けの項目が区別されている
• （該当する場合）クイズの草案に q1..qN の番号が付けられ、sourceUnit に出典となる章のタグが付いている
• すべての成果物をアウトラインのユニット ID までたどれる

ユーザーに次のように伝えてください。「コンテンツの草案が完成しました。次のステージ（static-spa-conversion）で、これを course-data.js ＋ index.html に変換します。各ユニットには、「挿絵の要件」ブロックから作成した illustrations: [] 配列が含まれます。Stage 3/4 の後、web-visual-assets がそれらの枠を埋めます。仕様の行が、その際のプロンプト入力になります。この時点以降、ユニット ID やタスク ID は変更しないでください。これらは localStorage のキーになります。」