tutorial-authoring

チュートリアルの作成

読者が手順に沿って何かを作成、設定、理解、練習する学習者向け教材には、このスキルを使用してください。

このファイルは実行の中核です。タスクで必要な場合にのみ、詳細な参考資料を読み込んでください。

• 調査の根拠、エビデンスの範囲、引用： references/research-foundations.md
• 動きを使った指導とアクセシブルな動画： references/video.md
• Course Docs の MDX 契約と自動リント： references/course-docs-platform.md
• アクセシビリティの詳細とテキスト代替パターン： references/accessibility.md
• レビューチェックリスト：REVIEW-CHECKLIST.md

対象範囲

標準の対象者：初級から中級の学習者。

指導支援には、熟達度逆転効果が見られることがあります。関連する予備知識が少ない学習者はより多くのガイダンスから恩恵を受けることが多い一方、予備知識が多い学習者は冗長な支援によって妨げられることがあります。対象の学習者とその手法に関するエビデンスに応じて、ガイダンスの各形式を調整してください。マルチメディアの原則がすべて同じ形で逆転すると決めつけないでください。

作成者向けの対象者ラベルは、作成時のコンテキストまたはメタデータに留めてください。学習者が本当に必要としない限り、「初学者向け」などの表現を学習者向けの文章に含めないでください。

ファイルの種類やパスにかかわらず、学習者に表示される内容は指導コンテンツとして扱ってください。JSON/YAML/TypeScript のフィクスチャ、Bundle ソース、テストフィクスチャ、生成ソースに埋め込まれたプロンプト、ラベル、コードのコンテキスト、フィードバック、説明、表示状態のテキストにも、チュートリアル文書の文章と同じ作成レビューを適用してください。

教育上の目的

次の規範的な目的を採用してください。学習者が前向きな姿勢で楽しく学び、実際にできることを増やし、学んだことを活用して自分で考え、創造し、学び続けることです。

これは教育システムの価値判断であり、研究によって唯一の目的と証明されたものではありません。学習科学は、この目的を追求する手段、副作用、境界条件について示唆を与えます。楽しさは常に簡単であることを意味しません。厳密さのために不要なフラストレーションが必要なわけでもありません。意味のある想起、意思決定、問題解決、生産的な試行錯誤を保ちつつ、偶発的な難しさを減らしてください。

ルールの根拠

研究上の根拠と適用の厳格さは、別々に扱ってください。

Code	意味
R — 複数の研究による裏付けあり	関連する境界条件の範囲内で、複数の独立した研究または研究の統合が方針を支持している
S — 複数研究の統合に基づく結論	複数の研究・統合で裏付けられた前提のみを用い、明示された推論過程を経て導かれた結論
L — ローカルな判断	規範的な目的、執筆上の慣例、プロダクト上の判断、またはプラットフォーム契約。科学的知見ではない
U — 未解決	利用可能な研究では判断が定まらない

上記の教育上の目的は規範的であり、実証的ではなくローカルなものです。ルールをRまたはSに分類できるのは、そのエビデンスと境界条件を references/research-foundations.md で追跡できる場合に限ります。Sでは推論過程を記録し、研究結果と監査されていない設計上の直感を組み合わせないでください。Uの項目を、設計上の不足を埋めるためだけに教育上のルールにしてはいけません。追加のエビデンスを集め、選択肢を検証するか、その判断を明示的にローカルなもの、または実験的なものとして扱ってください。

エビデンスの強さと適用の厳格さは、別々の軸です。厳格なプラットフォーム契約もLであり得ます。また、正しい適用に意味上の判断が必要な場合、Rの原則であっても推奨に留められます。

作成手順

チュートリアルを作成またはレビューする際は、次の順序に従います。

1. 目的／目指す成果： 教育目的に沿って、学習者が身につけるべき価値ある能力を決めます。
2. 学習者の状態： 関連する既有知識や過去の指導内容、および目指す時間軸（初期の実践、保持、転移、またはそれらの組み合わせ）を特定します。
3. 学習単元＋対応する証拠： 何を学ぶのか、そして目指す成果を実証する観察可能な証拠は何かを定義します。
4. 学習イベントの設計： 適切なパターン／ストラテジーと有意義な活動を含め、今回の学習体験を選びます。
5. 適切な支援： 学習者、実践状況、目標に合わせて、説明、モデル、フィードバック、立て直しの支援を提供します。
6. 意欲／有意義な挑戦： 容易さを質の尺度とせず、学ぶ意欲と達成可能な進歩を支えます。
7. 学習者の能動的な処理： 関連する想起、説明、予測、比較、意思決定、応用、デバッグ、作成を設計します。
8. コースの進行： カリキュラムがその時間軸を担う場合は、その後の練習、想起、条件を変えた転移を計画します。
9. 提示／アクセシビリティ／初見での理解： 表現方法や構成要素を選び、アクセスのしやすさ、明確さ、意図しない難しさがないかを確認します。

学習システムとチュートリアルページ

目的 → 単元／意図する成果 → イベント／学習者の体験 → エビデンス → 時間経過に伴う進行、の順に設計します。単元は WHAT、 イベントは HOW / NOW、エビデンスは EVIDENCE、進行は OVER TIME です。ページ／セクションは、このモデルの下位にある提示／配布方法の選択肢です。コンポーネントは選択した体験を表現しますが、props によって教育法が決まるわけではありません。セクションが存在するというだけで、そのセクション内で完結させたり、概念やヒントを設けたりする必要はありません。

カリキュラムレベルの設計では、安定した目標と、学習者がその目標に向けて取り組む各機会を区別します。

• 学習単元は、安定した学習目標または能力、つまり学ぶ内容です。単元は、より広い目標から末端の目標へと階層を形成できます。ページは学習単元ではありません。
• 学習イベントは、1 つ以上の学習単元を対象とする、学習または練習の 1 回の機会です。つまり、学習者が今回どのように取り組むかを表します。同じ単元が、異なる活動やエビデンスを伴って複数のイベントで繰り返されることがあります。
• コースの進行とは、時間の経過に伴うイベントの順序だった繰り返しです。後の段階での想起や分散練習、累積練習または混合練習、内容と目標に適している場合の交互練習、そして転移を計画します。これらはエビデンスに基づく設計上の目標であり、研究で最適と証明されたものとして、ローカルで合成した固定的な順序を主張するものではありません。
• エビデンス／評価は、学習単元の目標に対応した、観察可能なエビデンスです。演習はタスクまたはコンテナーの形式です。通常の練習にも転移にも使えます。転移のエビデンスには、条件が意味のある形で変化していることと、学習した原則を選択または応用することが必要です。
• ページは提示と配布の単位です。1 つのイベントの一部や、複数のイベント向けの教材を提示できます。1 つのイベントが複数のページやその他の形式にまたがる場合もあります。ページによって目標や機会が定義されるわけではありません。通常、授業は学習者に見える教材に沿ってイベントの順に進められます。教師用の授業計画を重複して作る必要はありません。

初回学習の順序には、I-PS（指導を先に行い、その後に問題解決）と PS-I（問題解決を先に行い、その後に指導）を使用します。このパターンが表すのは指導と問題解決の順序であり、ページ全体のテンプレートではありません。イベントの実施に役立つ場合は、互換性のあるパターンの中で、より大きなストラテジーを使用できます。生産的失敗は、PS-I の特定の高忠実度なサブセット／バリエーションであり、すべての PS-I の同義語ではありません。意図的に設計された「指導前の問題解決」イベントは、ガイドのない苦闘ではありません。探究型学習はより広範なストラテジーであり、ガイドのない発見を意味するものではありません。有用な場合は、解答例、自己説明、想起練習などの小規模な手法を区別して扱います。実行の改善につながらず、作成の負担だけを増やす分類体系を押し付けないでください。

指導の視野

すべてのチュートリアルを同じ成果に向けて最適化しないでください。

• **初回の実行／ジョブエイド：**手順を参照できる間に、迅速かつ正確に実行できることを優先します。タスクに合わせた詳細な指示や、視覚情報を中心に進める方法が適している場合があります。
• **学習（保持を含む）：**初回の速度だけを測るのではなく、時間の経過に伴って手順を想起、説明、再現する機会を設けます。
• **転移：**成功が 1 つの解答例の模倣に限られないよう、条件を変えたもとで原則、バリエーション、または応用を取り入れます。

チュートリアルが複数の視野に対応する場合もあります。目標が競合するときは、明示的に求められる保持や転移の成果を犠牲にして、初回の完了速度を最大化しないでください。段階的な支援の縮小や混合型の指導は、両方を支えることができます。

このスキルで用いる認知負荷の枠組み

古い「3つの加算的負荷」という略式表現ではなく、Sweller, van Merriënboer & Paas（2019）を実用上の基準として使用してください。また、2025年のKalyuga & Plassによる目標駆動型の改訂案も考慮してください。ある要求が有用か余分かは、指導目標、学習者の既有知識、意欲、感情によって異なる場合があります。この案は重要な拡張として扱い、確立した合意とは見なさないでください。

• 内在的負荷は、学習者の熟達度と取り組んでいる目標に対する、相互に作用する課題要素に左右されます。順序立て、必要に応じた事前訓練、解答例、適切な区切りによって管理します。
• 外在的負荷は、現在の指導目標に照らして避けられる処理から生じます。不必要な検索、注意の分割、無関係な詳細、分かりにくいナビゲーション、役割のない重複を減らします。
• 有益な処理は、最大化すべき独立した第3の負荷ではありません。避けられる要求を制御したうえで、有用な想起、自己説明、練習、フィードバックのための余地を作ります。

目標に照らして避けられる処理を減らし、学習者が学習に関わる思考に認知資源を使えるようにします。想起、自己説明、問題解決、選択、デバッグ、応用、転移は、生産的な困難になり得ます。報告された負担を下げるためだけに、これらを取り除かないでください。

方策が相反する場合は、まず指導目標を特定し、その目標に照らして避けられる処理を減らし、学習者にとっての課題の複雑さを管理してから、利用可能な認知資源に収まる学習関連の活動を加えます。意欲や感情が、学習者の課題に取り組む能力や意欲を大きく左右する場合は、それらも考慮してください。

出典と限界については、references/research-foundations.mdを参照してください。

主要な表現形式

意図した学習の時間軸を支えながら、避けられる統合作業を最も少なくして学習者の操作を伝える表現形式を選んでください。画像は選択肢の一つであり、既定の形式ではありません。

課題	一般的な主要表現形式
空間的なUIの経路、レイアウト、視覚的な関係	注釈付きビジュアル
コードの作成または変更	コード／CodePreview
空間に関係しない短いコマンドまたは設定	テキスト
構造上の関係または状態の遷移	図
動き、タイミング、または連続的な変化が学習上重要	対応している場合は動画／アニメーション。references/video.mdを参照してください

副次的な表現形式では、相補的な情報を加えてください。たとえば、正確な入力値、ホバーとクリックの違い、ユーザー固有の経路、文章とビジュアルを対応づけるラベル、形だけでは示せない意味情報などです。

同じ手順全体を、同じくらい目立つ2つの経路で重複して示さないでください。検索や対応づけの負担を減らす場合は、短い識別の手がかり、ラベル、番号、位置を示す目印を両方に表示してもかまいません。

アクセシビリティに相当するコンテンツは、無意味な冗長性ではありません。 ビジュアルに不可欠な情報が含まれている場合は、同等のテキストによる経路を用意してください。すべての学習者に2つの完全な並行手順を処理させるのではなく、支援技術から利用できる、または必要に応じて表示できる形で同等の情報を提供してください。

アクション単位

アクションは、一貫した学習者の行動エピソードとして扱います。つまり、1つの直近のサブゴールに向けた、局所的にまとまりのある操作、または短い操作の連続です。必ずしもマウスのクリック1回を意味するわけではありません。

たとえば、ビジュアルを主とするアクションでは、クリック → メニューを開く → サブメニューにカーソルを合わせる → 項目を選択する、といった短いナビゲーションの一連の流れが、全体として一貫したエピソードであれば、正当なものとして示せます。

分割によって意味のある状態やサブゴールの境界ができる場合、統合コストが下がる場合、または復旧や検証が分かりやすくなる場合は、アクションを分割します。フィールド、クリック、番号付きコールアウトごとに機械的に分割してはいけません。

アクション全体で、学習者が推測せずに行動できるようにします。ビジュアルを主とするアクションでは、表示される説明文に完全な視覚的経路を言い換えて記載する必要はなく、補足情報のみを含めてもかまいません。重要な視覚的指示については、完全でアクセス可能なテキスト相当の経路を用意します。ただし、プラットフォームがそれをプログラムによって、または必要に応じて表示できる場合は、その経路を主たる表示と視覚的に競合させないでください。

主たる表現にも、アクセス可能な代替表現にも、対象と操作が明確に示されていないのに、「クリックします」のような特定不足の指示を残して冗長性を「修正」してはいけません。

回答を伴うアクティビティでは、回答前の表示状態から、学習者が何について回答するのか、どのような操作または判断が求められているのか、回答に期待される形式が明確に分かるようにします。作成時に記載しなかったタスク固有の意味を、共通のレンダラーが補うことを前提にしてはいけません。タスクの意味を誤って伝えない場合に限り、中立的なアクセシビリティラベルやプラットフォームラベルを使用できます。

分割と注意の分散

「1画面＝1セグメント」という機械的なルールではなく、学習者が意味のある単位で進められるチャンクを使います。

GUIチュートリアルでは、画面や状態の遷移が有用な境界候補になりますが、意味上のサブゴールをより優先します。コーディングや概念学習のタスクでは、画面の遷移なしに分割が必要になることもあります。

画面数ではなく、意味的または因果的に意味のある境界で分割します。同時に変更すると、どの変更がどの結果を引き起こしたのか分かりにくくなる場合は、それぞれの寄与を確認できるように分けます。役割を区別したり、メンタルモデルを明確にしたりするために、意図的に「まだ目に見える変化がない」状態を保ちます。たとえば、HTML クラスを追加してから、CSS でそのクラスを選択する場合です。統合コストが高くなるような機械的な分割は避けてください。

意味のあるセグメントは、段階的に表示できます。後の内容を理解するために前の内容との比較や統合が必要な場合は、その内容を引き続き参照できる状態にするか、簡単に再表示できるようにします。初学者向けのガイド付きフローでは、先へ進むよう案内しながら、完了した内容を見直せるようにできます。これは、常に制限のない移動が有益であることを意味するものではありません。前のステップを見直す際は、実用上可能な場合、学習者の状態と回答を保持します。意図的にリセットする場合は、それが明確に分かるようにします。学習者が回答を確定した後、比較が重要であれば、回答をその場に保持するか、すぐに比較できる形で保持します。2つ目の表現が、説明、正規化、比較、アクセシビリティのいずれかで異なる役割を果たさない限り、すでに正解が表示されているすぐ隣に、同一の正解を標準形で追加してはいけません。累積型の提示は、有望でエビデンスにも沿った候補ですが、あらゆる状況で有効だと証明されたものでも、唯一最適な UI でもありません。ページ内で累積的に復習することは、情報の外部化に役立ちますが、後日の間隔を空けた検索練習や転移練習に代わるものではありません。 タブ、アコーディオン、折りたたみ、レイアウトの具体的な選択は、個別の状況に応じた実験的なものです。学習者が必要とする場合は、完了後に簡潔なリファレンスを用意すると、すぐに再開しやすくなることがあります。すべてのページに必須というわけではありません。

注意の分散は、学習者が離れた情報源を頭の中で統合しなければならない場合に生じます。物理的な距離はよくある原因ですが、それ自体が定義ではありません。対応するビジュアル、ラベル、値、説明文は、不必要に探し回らなくても統合できる程度に近くに配置します。

概念と事前学習

概念は、現在または次に行う学習活動を理解したり、実行したりするために必要な概念的知識を支えます。

• 初めて使う直前に配置するのはデフォルトであり、配置をそれのみに限定する契約ではありません。複雑な活動に備えて、より早い段階で事前学習を行うこともできます。また、要約、想起、参照として配置するのも、意味の面で適切な場合があります。
• 活動にとって、それが何であり、なぜ重要なのかを説明してください。遠い将来に関する無関係な内容は避けてください。
• 事前学習が必要な場合は、後の課題が前提とする理解に先立って、学習者が理解すべき名称と関連する特性や関係性を教えてください。名称のリストだけでは、その理解を促す準備にはなりません。
• 明確に伝えるために必要な長さにしてください。6文以上の場合、概念が混在している、または参照情報が含まれている可能性を検討することがあります。これは厳格な上限でも、調査上の基準でもなく、短い説明が必ずしも優れているわけではありません。

学習者がすでに概念を知っている場合は、折りたたみ式や参照用の形式にするか、概念をまったく設けないほうが適切なこともあります。

学習者向けの導入

ページの導入、前提条件のコールアウト、目標の要約、セクションの目標、プレビュー、順序の案内は、その時点での活動、構成、判断に具体的な助けとなる場合に使用してください。初見でのレビューでは、見出しや隣接する文章を繰り返すだけの項目、確定しているコースの順序、標準的なユニット目標、あるいは学習者がまだ活用できない情報を、見直しの対象として検討してください。この L レビュー規約は、学習目標や先行オーガナイザーを否定するものではありません。有用であれば、注意を向けたり構成を明らかにしたりする役割を果たします。 references/research-foundations.mdを参照してください。

説明される前に、なじみのない用語が導入や見出しに現れることがあります。学習者が意味を理解し、それに基づいて行動する必要がある場合は、その理解を前提とする前に、名称と関連する特性や関係性を説明してください。名称だけのプレビューを事前学習と呼ばないでください。前提条件のコールアウトは、実行可能な準備、学習への再参加、または立て直しに役立つ場合に有用です。順序が保証された直線的な進行では、そのような価値を加えない場合は省略してください。前提知識は重要ですが、すべてのページに前提条件のUIが必要なわけではありません。

Course Docsでは、学習者の行動の一貫性をS 調査の統合知見として扱ってください。学習者向けの見出し、その直後の説明、課題の指示、関連するUIの手がかりは、同じ段階で求められる行動を伝える必要があります。「見る」「書く」「選ぶ」「修正する」「試す」「確認する」「答える」「作成する」のどれをすべきか学習者が判断できなくなる場合は、不一致を学習者向けの不備として見直してください。同じ行動を意味する自然な言い換えは問題ありません。同じ言葉を使う必要はありません。複数の行動を示すこともできますが、その順序が明確で、それぞれの段階が理解できるようにしてください。この統合知見は、見出しとシグナリング、一貫性、課題の行動と提示の一貫性に関するエビデンスを組み合わせたものであり、特定の動詞の組み合わせについて直接検証された規則ではありません。references/research-foundations.mdを参照してください。

これとは別に、隣接する内容間の順序／談話の連続性も確認してください。学習者が現在置かれている状況から、次のトピック、操作、概念がなぜ今登場するのかが明確でしょうか。これは、見出しと活動で同じ行動が求められているかを確認することよりも広い観点です。特に、初学者向けの導入では有用です。簡潔なつなぎの説明によって、学習者の目標、観察された結果、現在の方法の限界、次の概念や操作の必要性、または明示的な移行を結び付けることができます。教材に簡潔に記載できる論理的なつながりを、学習者に推測させないでください。初見でのレビューでは、次の点を確認してください。

• 直前の内容を読んだ学習者は、「なぜ今これを学ぶのか」と疑問に思うでしょうか。
• 新しい概念、ツール、操作は、その必要性が明らかになった後に登場していますか。
• 見出しが、学習者の現在の理解より先に結論を示していませんか。
• 前の結果から次の説明や操作へとつながる目的や理由は、自然に読めますか。 段落間のつなぎをすべて追加したり、あらゆる読者にとっての一貫性を最大化したりする要件ではなく、S の研究知見を統合したものとして適用してください。検索や問題解決の活動では、意図的な推論を保ってください。十分な既有知識を持つ学習者に対して、高い一貫性を普遍的なルールにしないでください。

初学者への初期指導では、通常、各文はそこまでに導入された情報から解釈できるようにしてください。前の文を理解するために、後の内容が必要になる構成は避けてください。レッスンの因果構造に合う場合は、現在／既知の状態 → 必要性／問題 → 新しい概念 → 活用の順を優先してください。この順序は局所的なヒューリスティックであり、常に最適な順序ではありません。安定した名称や識別子（たとえば、index.html、style.css、ブラウザーの結果など）は、L のユーザビリティ／アクセシビリティに関する慣例です。レスポンシブレイアウトによって対象の位置が変わりうる場合、ビューポートに依存する位置だけを参照するより信頼できます。学習者の行動を明確に表現できる場合は、執筆上のメタラベルよりも、タスクを直接示す表現を優先してください。

学習者向けのプロンプトでは、質問する時点で、対象となる物や内容、求められる判断／行動、期待される回答形式が明確になるようにしてください。指示対象や基準がすでに明確でない限り、学習者に推測させないでください。選択肢は、設問文を自然に補完するか、設問に自然に答えるものにしてください。日本語の表現を別個の解読課題にしたり、回答の対象となるカテゴリを前提にしたりしないでください。最初の試行の前に、意図した想起や生成を行えるようにしてください。Course Docs で日本語の文面を厳密に照合することは、ローカルな品質上の統合指針であり、普遍的な研究法則ではありません。文の穴埋め回答を比較のために返す場合は、意味が完全な文として示すことを優先してください。これは範囲を限定したローカルな慣例であり、普遍的なルールとして直接検証されたものではありません。

指導の主要な流れ、後続の操作、またはその流れに含まれる QuickCheck の理解に必要な説明は、そのまま流れの中に残してください。不可欠な原則を、ヒント、折りたたまれたコンテンツ、任意の吹き出しだけに頼って示さないでください。相互に依存する操作、結果、コード、説明を統合する必要がある場合は、不要な検索や注意の分散を避けられるよう、互いに近くに配置してください。事例学習、近接性、一貫性に関する研究から、固定的な指導順序を導き出さないでください。実際の目標と学習者の状態に応じて、イベントパターンと活動の順序を選んでください。

活性化

有用な既有知識の手がかりがある場合は、想起、比較、前のレッスン／課題、または適切なたとえを通じて活性化してください。

チェックリストを満たすためだけに、たとえを作らないでください。活性化は既存の知識を想起させるものです。事前トレーニングは、まだ定着していない知識を教えるものです。

足場かけと段階的な自立

指導を最小限に抑えるのではなく、適切な支援を目指します。自立性の向上は能力の成果であり、有用な支援を差し控える要件ではありません。

関連する既有知識が少ない、または不明な場合は、実質的な独力での構築に進む前に、十分な例題やガイド付き支援を提供することを基本とします。この基本方針は、適切な場合に忠実度の高い支援付き Productive Failure PS-I デザインを採用する妨げにはなりません。意図的に設計された「指導前の問題解決」は、手がかりのない苦闘とは異なります。境界については、references/research-foundations.md を参照してください。

既有知識と学習者の実績に応じて、支援を段階的に減らす、維持する、または再び増やします。「2 回目はガイド付き」「3 回目は独力」といった固定のしきい値は使用しないでください。

想定する学習者について得られる知識と、観察された実績に合わせて支援を調整します。個人に応じた適応型習得度の追跡は将来の対象範囲であり、このスキルに必須の実装ではありません。

状況に応じて、次のように段階を進めると効果的です。

• 例題： 必要なガイダンスを含む、完成されたモデル。
• ガイド付きの応用／完成： 学習者が選択された判断を行います。
• 独力での応用： 手順の指示なしに、学習者が計画を立てる、または知識を転移します。

すべてのページでこの 3 段階を設ける必要はありません。既有知識が十分にある学習者は、進行の後半から始めるのが適切な場合があります。

エンゲージメント、楽しさ、自律性

学習成果の達成に役立つ場合は、真正な関連性、有意義な課題、目に見える進捗、能力を支えるフィードバック、有意義な選択肢、学習者の主導権、前向きなエンゲージメントを検討してください。これらは設計上の選択肢であり、すべてのページに盛り込むチェックリストではありません。関連性を作り上げたり、選択自体を目的にしたりしないでください。楽しさ ≠ 易しさ、厳密さ ≠ 不必要な苛立ちです。

学習と体験の両方を評価します。流暢にできたことや学んだと感じることだけでは、能力の向上が示されたことにはなりません。また、有益な努力であっても難しく感じられる場合があります。適切なエビデンスと学習者からのフィードバックを併せて活用してください。

練習、想起、フィードバック、整合性のあるエビデンス

実質的な学習目標には、その目標と想定する指導期間に適したエビデンスが必要です。

目標／エビデンスの必要性	エビデンスを得る方法の例
観察可能な行動または状態	Verify
想起／理解	QuickCheck
マイルストーンを構成する複数の観察可能な条件	Checkpoint
応用または転移の課題	Exercise

この対応付けは、エビデンスを得る方法を選ぶための品質上の慣例であり、Section ごとの完了要件ではありません。すべての Section に確認を追加するのではなく、進行の有用な時点で Evidence を Units および Events に対応させてください。

生成的な活動では、学習者に選択、整理、統合、想起、説明、予測、比較、応用、デバッグ、適応、または創作を明示的に求めます。QuickCheck、自己説明、適切に設計された Exercise は、この役割を果たせます。受動的な Verify は有用なフィードバックになり得ますが、生成的な活動ではない場合があります。

有用な検証とは、UI の状態を読み上げることではありません。回答を客観的に、または確認可能な形で採点でき、検証によって学習者の不確かさが解消される場合、結果が画面上にも表示されているとしても、その達成状況に関するフィードバックは残してください。「冗長な読み上げ」として削除しないでください。修正情報や説明が役立つ場合、検証だけでは不十分です。適切に、実際の結果、正しい情報、因果関係の説明、または段階的に役立つヒントにフィードバックを結び付けてください。詳しい説明が有用な場合は、正誤だけを伝えるフィードバックでループを終わらせないでください。

リカバリーはエラーへの支援であり、目標に対する Evidence ではありません。すべてのジョブエイドや、初回の遂行のみを対象とするページで、能動的／生成的な活動が必須なわけではありません。

その場での成功は初回の遂行を示すエビデンスであり、定着した学習や転移の証拠ではありません。カリキュラムの対象範囲が許す場合は、想起と分散練習を通じて重要な知識を後から再び扱ってください。その場で一度成功しただけで習得を主張しないでください。

検索および生成活動の試行前条件

課題が、支援なしでの検索や学習者による生成を意図的に促すよう設計されている場合（想起をテストする QuickCheck や、学習者が目標となる回答を作成または生成する必要がある課題など）、学習者に見えるプロンプトの内容やデフォルトの試行前状態によって、学習者が最初に試行する前に目標の回答や、意図された検索や生成の機会をなくす決定的な手がかりを明かしてはなりません。

検索練習と生成効果の根拠および適用範囲については、references/research-foundations.mdを参照してください。

回答を、解答例を用いた指導、ガイド付きモデリング、または足場かけによる支援（解答例、穴埋め課題、段階的な支援）として意図的に提示する場合、その学習者とのやり取りは、支援なしの検索や生成ではなく、ガイド付き練習または確認となります。これは検索と生成の原則に適合しており、支援形式について意図的な選択を反映しています。

これは、すべての演習で答えを隠すべきであること、常にガイダンスを最小限にすべきであること、またはすべての学習イベントで生成の難易度を最大化すべきであることを意味するものではありません。指導上の目標、学習者の知識、適用する手法に関するエビデンスに合わせて、課題を設計してください。

予測／事前質問のアクティビティでは、これから扱う具体的な関係や結果について尋ねてください。エビデンスが裏付けているのは、事前に質問された内容に対する効果です。その効果を、関連性のない、事前に質問されていない内容に一般化しないでください。説明の前に初心者がコードの出力を予測する研究は、適切な初期プログラミング指導においてこの方法が有効であることを裏付けていますが、あらゆる場面で必須のパターンであることを示すものではありません。対象のオブジェクト／コードを明確に提示し、具体的な結果を尋ねてください。目標の答えが漏れないよう、試行前の状態を維持してください。試行後は、実際の結果や関係について、課題に即した具体的なフィードバックを行い、正誤の判定だけでなく、因果関係に基づく、または詳しいフィードバックを提供してください。探索的な予測では、誤りを罰するような表現より、比較を促す支援的な表現が望ましい場合があります。具体的な言い回し、色、アイコンの選択は個別の判断であり、研究に基づく要件ではありません。 自己説明が有用な場合は、説明すべき関係、誤り、または概念を特定できるよう、プロンプトに足場を設けてください。一般的な「なぜか説明してください」というプロンプトが自動的に優れているわけではありません。自己説明のテキストが空でないことだけでは、正しさは確認できません。また、採点されない自由記述で意味上の正しさを決して偽装しないでください。説明の全文を提示すると、予定していた自己説明や生成の目標が漏れる場合は、まず確認と実際に観察された具体的な結果を示し、次に学習者による生成／自己説明を促してから、因果関係に基づく、または詳しい標準的な説明を提示してください。振り返りを意味的に採点しない場合は、見せかけの必須ゲートを設けないでください。適切な場合は、「わかりません」を選べるようにするか、明示的な方法で学習者が説明や答えを表示できるようにしてください。有用な場合は、学習者が生成した文の全文を標準的な説明の横に表示してください。自己説明は概念上の転換点で選択的に用い、すべての操作の後に行わないでください。

学習、操作、回復、状況把握、またはアクセシビリティに役立たない場合は、「記録しました」「追加しました」「結果を以下に表示します」などの状態説明を削除してください。2回目の表示に固有の役割がない場合は、まったく同じ結果の文を繰り返さないでください。視覚的な結果と、それに対応する簡潔なテキストやアクセシビリティ上の代替表現を、機械的に冗長な重複と見なさないでください。Shute（2008）およびVan der Kleij、Feskens、Eggen（2015）のフィードバックに関する知見は、明示された境界条件の範囲内でRレベルの指針となります。段階的な順序はS Course Docsによる統合であり、具体的な言い回し、トーン、色、アイコンのスタイルはLの個別判断です。

回復とエラーへの対応

最小限のエラー対応では、予防、検出、診断、回復を扱います。 <Recovery>形式のコンポーネント自体は、主に事後対応を担います。

• よくあるミスを低コストで防げる場合は、操作の前に予防的な警告を置きます。
• もっともらしい失敗が起こりうる箇所の後に、Recoveryを配置します。
• Recoveryは、症状 → 考えられる原因 → 具体的な解決策の順に構成します。
• セクションの最後に、どんな場合にも当てはまる「もう一度試してください」という助言を置かないでください。

シグナリングと一貫性

シグナリングは、学習者が目標に関係する情報を見つけ、対応づけ、順序づけ、解釈するのに役立つ場合に限って使います。

適切なシグナルには、簡潔な目標、視覚的なコールアウト、重要なUIラベル、入力する正確な値、重要なジェスチャーなどがあります。装飾的な強調はシグナリングではありません。

重要なタスク関連情報を視覚的に目立たせる一方、競合する強調は抑えて、シグナルの選択性を保ちます。近接、共通の領域、整列、接続といったグルーピングの手がかりは、実際の意味構造を伝える場合に使います。同じタスクと操作の対応関係、および手がかりは、意味や操作が同じ場合には一貫させます。これらは研究に裏づけられた指針ですが、特定の色、枠線の幅、角丸、余白、コンポーネントの種類を独自に決めて、それを研究上の知見と呼んでよいという意味ではありません。

学習目標と無関係な装飾や感情的な刺激は取り除きます。意図的な感情に配慮したデザインは、目標に沿っており、処理の競合を生まない場合、意欲や注意を支えることがあります。サイドバー、ビジュアル、音声、動きは、タスク、警告、参照、アクセシビリティ、説明、フィードバックに実際の役割がある場合に適切です。

強調の数に恣意的な上限を設け、それを科学的な法則として扱わないでください。プラットフォームのリンターが太字の密度が異常に高いと警告した場合は、視覚的なシグナルが競合していないか見直すきっかけとして扱います。

学習者がコード、UI、図、レンダリング結果を統合する必要がある場合は、それらの意味上の関係を明示し、有用であれば近接、共通の領域、選択的な対応づけの手がかりを使います。初心者が、近くにあるプレビューが特定のHTML/CSSの状態から生じたものだと推測できるとは限りません。補助的な表記によって新たな読み取り作業を生じさせないでください。A + B → Cのような説明のない記号に頼らず、ラベルを直接説明します。左右配置や上下配置の具体的な選択は個々の場面によります。どちらか一方が最適だと研究で示されているわけではありません。レンダリングされたパネルは、そうした概念に頼る前に、学習者にとってわかりやすい言葉（例：「ブラウザーの表示結果」）で呼び、レイアウト上の位置よりも安定したオブジェクト名を優先します。

Learner-facing prose

Clarity > brevity. Do not shorten away causal relationships, UI/state correspondence, why an action matters, state transitions, or term meanings that learners need. A term may appear in a heading or title before definition, but explain it before requiring understanding of it. Prefer headings that predict the task, topic, or capability.

Use natural, direct, active language. Japanese zero-subject sentences are fine; explicit 「あなた」 is not required.

Keep authoring rationale and audience classification out of learner-facing prose when they do not help the task. Rewrite 「受講者は〜」「学習者は〜」 「初学者向け」 as task-facing prose. Do not ban 「ユーザー」 when it refers to a real product/domain end user.

Use the S — visible-prose value test: if a learner-facing sentence does not materially improve understanding, a decision, the next action, error prevention/recovery, state interpretation, reference value, or accessibility, consider removing or reworking it. UI narration that only repeats an obvious interaction/result is usually unnecessary. Keep objectively scorable verification that resolves learner uncertainty, useful performance feedback, causal explanations, misconception prevention, task directions, useful status/accessibility messages, and elaboration that improves clarity. This is not “shorter is always better”: clarity and useful elaboration can help, while reducing complexity alone has not reliably improved STEM text learning. Visible prose and assistive-technology status messages serve different purposes. Accessibility- equivalent content is not gratuitous redundancy. See the bounded synthesis in references/research-foundations.md.

Cold-read: accidental difficulty detector

Read the material in rendered order to detect unexplained prerequisites, ambiguous instructions, missing state, unnecessary backtracking, undefined assumptions, terminology gaps, and visual/prose mismatches. Re-entry should be understandable where the material supports it.

Preserve intended retrieval effort, problem solving, decision making, productive struggle, and changed-condition transfer. Cold-read review should remove accidental confusion, not solve the learner's meaningful challenge.

アクセシビリティの基本事項

特定のコンポーネント内のスクリーンショットだけでなく、すべての情報を伝える非テキストコンテンツに、以下のルールを適用してください。

• 同じ目的を果たす、または本質的な情報を伝えるテキストによる代替を用意してください。
• 注釈付きの複雑なビジュアルには、簡潔な短い代替テキストと、学習者に表示する詳細な説明、またはそれに関連付けた詳細な説明を用意してください。
• 意味を伝える際に色だけに頼らないでください。
• 通常のテキストやテキスト画像には 4.5:1 のコントラスト比が必要です。大きなテキストには 3:1 のコントラスト比を適用できます。意味のある非テキスト UI／グラフィック指標には、該当する 3:1 の非テキストコントラスト要件を適用してください。
• 同等の表現を実用的に実現できる場合は、テキスト画像より実際のテキストを優先してください。
• インタラクティブな例はキーボードで操作できるようにしてください。
• 状態を変える操作が理解に重要な場合は、記憶に頼って比較しなくても、変更されたソース、対象、または結果がわかるようにしてください。アニメーションだけを手がかりにしてはいけません。学習者が確認できるよう、変更後の値、行マーカー、結果テキスト、または同等のものを表示したままにしてください。動きは連続性を補助できますが、あくまで補足です。視覚的な信号だけで明確に伝わり、説明を加えても学習価値がない場合は、すべての変更を逐一説明する必要はありません。
• 手順に沿って進む動的なチュートリアルでは、新たに表示される説明は通常、それを引き起こす操作の後、または同じ読み上げ順序／フォーカス順序の中でその操作の位置以降に表示してください。先にある説明を黙って変更し、戻って探す必要が生じる配置は避けてください。順序が意味に影響する場合は、意味上の順序、視覚上の順序、DOM／読み上げ順序、キーボードフォーカス順序を一致させてください。予測しやすい通常の上から下への読み取りの流れは、このチュートリアルの文脈における局所的な既定値であり、あらゆるレイアウトや言語に普遍的に適用されるルールではありません。大きなステップの変更は、学習者の現在位置の近くで理解できるようにしてください。離れた位置にある進捗インジケーターはその手がかりを補助できますが、それだけでは主要な手がかりとして不十分です。
• 主要な送信／確認アクションが 1 つある、インタラクティブな単一行の入力では、該当する場合、Enter キーと表示された送信コントロールが同じ検証と状態遷移を実行するよう、ネイティブのフォームセマンティクスを優先してください。複数行の入力や、標準的なキーボード操作が異なるコントロールには適用しないでください。IME の変換中に送信するカスタム Enter ハンドラーは、変換を明示的に処理しない限り避けてください。

このスキルでは、WCAG 2.2 AA を既定のアクセシビリティ目標とします。米国連邦政府の ICT の対象となる資料には、米国の Section 508 E205 も関連します。ただし、すべてのチュートリアルに普遍的に適用される法的要件ではありません。

情報を伝える画像、図、グラフ、注釈付きスクリーンショット、またはインタラクティブな例を作成またはレビューする際は、references/accessibility.md を読み込んでください。

動画もこのスキルの対象です。動き、タイミング、または連続的な変化が、タスクの理解や実行に重要な場合に使用してください。正確な値やコマンドは、アクセシブルなテキストでも確認できるようにしてください。学習者による操作、シグナリング、セグメント化、同期、時間依存メディアのアクセシビリティについては、references/video.md を読み込んでください。

Course Docs の環境

対象サイトが @metyatech/course-docs-platform を使用している場合は、references/course-docs-platform.md を読み込んでください。

このリファレンスには、次のようなローカルの MDX 規約が記載されています。

• すべての階層で任意に設定できる <Section> の方向付け目標。
• QuickCheck／Exercise の problem → Hint* → Answer 構造。
• Verify のソース表記。
• コンポーネントの配置規約。
• lint ルールの ID と重大度。

これらのプラットフォーム規約を、チュートリアル全般に当てはまる科学的主張として一般化したり、無関係な Markdown／チュートリアルシステムに強制的に適用したりしないでください。

最終レビュー

チュートリアルを公開または承認する前に、次の点を確認してください。

• 想定する指導の到達点（初回のパフォーマンス、保持を含む学習、転移、またはそれらの組み合わせ）が、設計上の判断を導くのに十分明確であることを確認します。
• ページが学習者の目標に沿って構成されていることを確認します。
• 見出し、用語、値、比喩、コードコメントをすべて、表示順に予備知識なしで読み、確認します。
• 表現方法の選択と、アクセシビリティに配慮した代替手段を確認します。
• Concept の配置が、意味のある活用、または意図的な事前学習、要約、想起、参照に役立っていることを確認します。
• 適切な支援が、学習者の既有知識やパフォーマンスに合っていることを確認します。
• Evidence が、学習の進行における有用な時点で Unit の成果を評価していることを確認します。
• 楽しさと容易さを同一視せず、意義のある挑戦を支えるエンゲージメントになっていることを確認します。
• 失敗への支援が、起こり得る失敗に対処していることを確認します。
• 無関係な処理や重複した処理を取り除きます。
• 全項目の監査には REVIEW-CHECKLIST.md を使用します。

このスキルは、エビデンスに基づく既定の方法と、ローカルな品質基準を定めたものです。教育的に正しい出力を保証するものではありません。実際の学習者を観察し、実際の利用から得られたエビデンスが、想定したヒューリスティックと食い違う場合は改訂してください。