educates-course-design

Educates コース設計スキル

このスキルでは、ワークショップを体系的にまとめた Educates コースの設計を、初期要件の確認からワークショップごとの詳細な実装計画の作成まで支援します。成果物は、educates-workshop-authoring スキルを使ってワークショップを作成する際の設計図となる一連の計画ドキュメントです。

ワークフローは、要件の整理からワークショップごとの実装計画まで、6 つのステップで進みます。各ステップでは、planning/ ディレクトリに計画ドキュメントを作成します。タスクの一元管理ファイル（planning/tasks.md）には、ワークショップ全体の未対応タスクを記録し、ワークフローを通じて更新します。新しいコースでは通常、順番に各ステップを進めますが、既存コースを拡張する場合は、どのステップからでも開始できます（例：新しいワークショップを計画するためにステップ 3 から始める、または単一のワークショップの計画を作成するためにステップ 4 から始める）。既存のワークショップがあるプロジェクトにこのスキルを適用する場合は、既存の作業を監査し、計画ドキュメントの初期セットを作成する方法について、既存コースの導入を参照してください。小規模なコースでは、一部のステップを簡略化するか、完全に省略します。ワークフローは、ステップ 1 で決定したコースの規模に応じて調整されます。

ステップ 1：コース要件を確認する

コースの規模を決定する

詳細な要件を収集する前に、ユーザーが想定している規模と構成を把握します。ユーザーが希望をどのように説明しているかに注意してください。「X に関する包括的なコースを作りたい」「Y について、ワークショップを 1、2 個考えている」など、さまざまな場合があります。

会話の内容から規模を見極め、次のいずれかの分類を提案します。

• Focused（ワークショップ 1～3 個）：少数のワークショップで構成され、ユーザーがアイデアを具体化したいだけの場合もあります。モジュールは 1 つです。必修／選択モデルは任意です。ユーザーはまだ全体像を把握できていない場合があるため、現在の構想を計画し、後から追加できる内容を提案します。
• Standard（ワークショップ 4～10 個）：複数のワークショップで構成される、まとまりのあるコースです。モジュールは 1 つ以上です。必修／選択モデルは任意です。基本はシンプルな直線的な順序とし、ユーザーが柔軟な順序を希望する場合は、必修／選択モデルを利用できます。
• Comprehensive（複数のモジュールにわたるワークショップ 10 個以上）：大規模で構造化されたコースです。複数のモジュールで構成されます。受講者が教材の中から学ぶ内容を選べるよう、必修／選択モデルを推奨します。

次に進む前に、コースの規模をユーザーと確認します。規模は固定ではなく、後から変更できますが、ワークフローでどの程度の構成を導入するかを左右します。コース概要に規模を記録します。

要件を収集する

ユーザーから次の情報を収集するか、文脈から推測します。

• テーマと範囲：コースで扱う内容と、その幅や深さ
• 対象者：コースの対象者と、想定する難易度の範囲（初級、中級、上級、または段階的な構成）
• ナビゲーションモデル (Standard と Comprehensive のみ)：コースで必修／選択モデル（受講者が内容を選んで学ぶ包括的なコースに推奨）を使うか、直線的な順序を使うか。Focused コースでは、ワークショップは単独で受講するか、シンプルな直線的な順序で進めるため、ナビゲーションモデルのセクションは不要です。

ユーザーが広範なテーマを提示しても、具体的な詳細がない場合は、妥当な初期設定を提案し、次に進む前に確認します。コース概要では、トピックのアイデアを出し合う前に、コースを作る「理由」と扱う「内容」をまとめます。

コース概要の作成

planning/course-brief.md を作成します。以下のセクションはコースの範囲に応じて調整し、該当するもののみを含めます。

• コースのビジョン — コースで扱う内容と、そのコースが存在する理由です。複数のモジュールがあるコースでは、モジュールの進行順と、モジュール全体を通じたテーマや物語の流れを説明します。特定のテーマに絞ったコースでは、数段落で主題と学習目標を示せば十分です。
• 対象者 — コースの対象者、前提となる知識、さまざまな経験レベルにどのように対応するかを説明します。
• 提供プラットフォーム — コースは、インタラクティブなブラウザベースのワークショップとして Educates トレーニングプラットフォームで提供されます。
• コース構成 — コースをモジュールに分ける方法の概要と、各モジュールのテーマや重点を簡潔に説明します。すべてのコースには、少なくとも1つのモジュールが必要です。1つのモジュールのみで構成される特定のテーマに絞ったコースでは、モジュールのテーマを説明する1〜2文で十分です。
• ナビゲーションモデル (標準コースと包括的コースのみ) — ワークショップ同士の関係を説明します。コア／選択コースの場合は、コアと選択の意味、前提条件の扱い方、学習者が直線的ではない順序で進める方法を説明します。直線的に進むコースの場合は、推奨される順序を示します。特定のテーマに絞ったコースでは省略します。
• 設計原則 — 学習者とのインタラクションに推奨する方法（クリック可能な操作を使ったガイド付きの体験がデフォルトですが、コースの作成者は、学習者が自分でコードやコマンドを入力する、より実践的な方法を選ぶこともできます）と、コース固有の設計上の決定事項（例：概念的な内容の扱い方）を説明します。
• 範囲と拡張の方向性 (特定のテーマに絞ったコースと標準コースのみ) — 現在の範囲を記録し、今後の拡張の方向性を提案します。たとえば、「この特定のテーマに絞ったコースでは、XをN個のワークショップで扱います。次の段階として、YやZを追加できます。」と記載します。これにより、段階的にコースを構築し、後からワークショップを追加したいユーザーを支援できます。

各セクションの詳しいガイダンスについては、コース概要リファレンスを参照してください。

AI アシスタントの指示ファイルを作成する

プロジェクトのルートに AI アシスタントの指示ファイルを作成し、今後の AI とのやり取りで、プロジェクトのコンテキストと使用すべきスキルが自動的にわかるようにします。Claude Code の場合、このファイルは CLAUDE.md です。他の AI コーディングエージェントでは、異なる規約（例：AGENTS.md）が使われます。

指示ファイルには、以下を含めます。

• プロジェクトの概要、ディレクトリ構成、ナビゲーションモデルについて記載した README.md への参照
• コース全体のビジョンと設計原則について記載した planning/course-brief.md への参照
• コースで使用する外部ドキュメントや参考資料をまとめたリストとしての planning/resources.md への参照。コースの主題に関する情報をウェブ検索する前に、エージェントがこのファイルを確認するよう指示します
• プロジェクト固有のワークショップ規約 — このステップで定めた規約を記載します。たとえば、ワークショップ名のプレフィックス、各ワークショップに必要なセッションアプリケーション（ターミナル、エディター、Kubernetes など）、プログラミング言語とランタイムのバージョン、コース全体に適用されるその他のデフォルト設定などです
• スキルへの参照 — 各スキルを呼び出すタイミングを記載します。
  • コースの計画（トピック、ワークショップの分割、ワークショップごとの計画）には、educates-course-design スキルを使用します
  • ワークショップ作成に関する知識には、educates-workshop-authoring スキルを使用します。このスキルは、ワークショップごとの計画を作成するときと、実際のワークショップファイルを作成するときの両方で使用します
• 設計原則 — コース概要で選択したアプローチ（例：クリック可能な操作を使った完全なガイド付き、またはより実践的なアプローチ）を簡潔に示し、詳細については planning/course-brief.md を参照するよう記載します

このファイルは、AI 固有の指示とプロジェクト固有の上書き設定に絞ります。README.md や planning/course-brief.md にすでに記載されている内容を重複させず、代わりにそれらのファイルを参照してください。

コースリソースファイルを開始する

コース設計中に見つかったコースの題材に関連する外部ドキュメント、参考資料、学習教材を記録するために、planning/resources.mdを作成します。このファイルは、セッションをまたいで引き継がれる、継続的に管理されたリソース一覧として機能します。会話のコンテキストがクリアされ、後日作業を再開する場合、エージェントは同じリソースを再検索する代わりに、このファイルを参照できます。

このファイルに記載するのは、コースで教える題材に関するリソース（言語のドキュメント、フレームワークのガイド、API リファレンス、チュートリアルなど）であり、Educates プラットフォームのドキュメントではありません。Educates のワークショップ構成、設定、作成規約に関する知識は、educates-course-design と educates-workshop-authoring のスキルで提供されるため、リソースファイルに重複して記載する必要はありません。

要件の確認中は、コースの範囲を把握し、実現可能性を評価するために、コースの題材について調査することがよくあります。**ウェブ検索またはウェブ取得で役立つリソース（ドキュメントページ、チュートリアル、API リファレンス、ガイドなど）が見つかったら、その都度すぐにこのファイルに追加してください。**情報が会話のコンテキストに残ることを前提にせず、後のセッションでも利用できるよう、ファイルに記録してください。

ステップ 1 で見つかったリソースを使って、ファイルを開始します。その後、トピックのブレインストーミング（ステップ 2）、ワークショップの構成（ステップ 3）、詳細な計画（ステップ 4）を通じて、新しいリソースが見つかるたびに内容を充実させていきます。

コースの作成者はいつでもこのファイルを確認・編集し、バージョンの修正、古くなった資料への印付け、推奨する代替資料の追加を行えます。ファイル末尾のキュレーションメモのセクションに、こうした修正を記録します。

ファイルの構成、エントリー形式、メンテナンス規約については、コースリソースのリファレンスを参照してください。

ステップ 2：トピックをブレインストーミングして整理する

このステップは、コースの範囲に応じて調整します。

• 特化型：このステップは省略可能です。ユーザーが 1～3 個のワークショップで扱う内容をすでに決めている場合は、ステップ 3（ワークショップが 1 つの場合はステップ 4）に直接進みます。ユーザーが取り上げるトピックについてブレインストーミングしたい場合や、拡張案を検討したい場合は、網羅性を目指さず、簡潔なトピック一覧を作成します。
• 標準型：ユーザーと協力して、コースで扱うトピックを特定し、将来の拡張案を記録します。目標は、計画された範囲を網羅して拡張案を収集することであり、題材に含まれる可能性のあるすべてを列挙することではありません。
• 包括型：コースで扱う可能性のあるトピックを詳細に洗い出し、コース概要で定義されたモジュールに整理します。目標は網羅性です。後から絞り込むことを前提に、トピックは多めに挙げるほうが適切です。

このステップは、協力しながら反復的に進めます。AI がコースのビジョンに基づいてトピックを提案し、ユーザーが内容を調整、追加、削除、並べ替えます。トピック一覧は項目の棚卸しであり、ワークショップとの 1 対 1 の対応付けではありません。対応付けはステップ 3 で行います。

トピックのブレインストーミング中は、どのようなトピックがあるのか、どのように機能するのか、実践的な演習に適した内容は何かを把握するため、外部ドキュメントを調査することがよくあります。見つかった役立つリソースは、関連するトピック番号を付記してplanning/resources.mdに追加してください。

トピック文書を作成する

次の内容を含む planning/course-topics.md を作成します。

• モジュール別に整理したトピック（複数モジュールのコースの場合）、または番号付きのフラットなリスト（単一モジュールのコースの場合）。各トピックには、参照用の番号付き見出しと、その内容を説明する箇条書きを含めます。
• トピック選定に関する注記 — 次の内容を特定する注釈です。
  • 主に概念的なトピックで、実践的な隣接トピックに統合する必要があるもの
  • 選択科目モデルを使用するコースの場合、コード構造が似ていて選択科目として適しているトピック群
  • 今後の拡張案 — ユーザーが現時点では扱う予定はないものの、後で追加する可能性のあるトピック（特に、焦点を絞ったコースや標準コースで有用です）
  • トピックをワークショップに割り当てる際の指針となるその他の所見

複数のトピックを1つのワークショップにまとめたり、大きなトピックを複数のワークショップに分割したりできます。この割り当てはステップ3で行います。

詳しい指針については、コーストピックのリファレンスを参照してください。

ステップ3：ワークショップの構成を計画する

ステップ2のトピック（または、ステップ2を省略した場合はユーザーのワークショップ案）を、具体的なワークショップに割り当てます。

ワークショップ構成を作成する

モジュールごとに1つのファイルを作成し、planning/course-module-X.md という名前にします。Xは小文字のアルファベットです（例：course-module-a.md、course-module-b.md）。モジュールは番号ではなく、文字（A、B、Cなど）で識別します。単一モジュールの焦点を絞ったコースや標準コースでは、planning/course-module-a.md を作成します。

各ファイルの冒頭には、次の内容を記載します。

• トピックをワークショップに割り当てた方法を説明する簡潔な導入（焦点を絞ったコースの場合は、各ワークショップで扱う内容）
• 各ワークショップの項目に含める内容を定義するワークショップ構成の規約セクション

続いて、各ワークショップについて次の内容を記述します。

• 扱うアイデア — 対象となる course-topics.md のトピック（ステップ2を省略した場合は省略）
• タイプ（選択科目モデルを使用するコースの場合のみ）— コア（必須、順番に受講）または選択科目（任意、前提条件を満たせば任意の順序で受講可能）
• 前提条件 — 先に完了しておく必要があるワークショップ（明示的に記載し、暗示的な表現にしない）。シンプルな順序で進む焦点を絞ったコースの場合は、「前のワークショップ」または「なし」で十分です。
• 学習目標 — ワークショップの完了後に学習者ができるようになること
• 展開 — 冒頭から最後までの学習の流れ
• コード演習 — ワークショップに十分な対話的内容があるか評価できるよう、具体的な実践活動を詳しく記述します。
• 主要なコード例 — 必要となるコードの種類（実装全体ではなく、実現可能性を評価できる程度の内容）

ステップ4でワークショップごとの計画を作成する際、モジュールファイルの各ワークショップ項目に詳細計画へのリンクを追加します。このリンクには、workshop-plans/ サブディレクトリへの相対パスを使用します。

### Workshop A01: Workshop Title

**Detailed plan:** [workshop-plans/lab-a01-workshop-name.md](workshop-plans/lab-a01-workshop-name.md)

**Directory name:** `lab-a01-workshop-name`

ワークショップ名は lab-{code}-{descriptive-name} の形式にします。codeは、モジュールの文字と、2桁のゼロ埋めワークショップ番号を組み合わせたものです（例：a01、a02、b01）。これにより、コース内のワークショップの位置が名前に含まれ、ディレクトリ一覧でファイルがモジュール順、実施順に並ぶとともに、相互参照が明確になります。

焦点を絞ったコースと標準コースでは、モジュールファイルの末尾に今後の拡張案セクションを含め、コースを発展させる方向性として、後から追加できるトピックやワークショップを提案します。これにより、段階的なコース開発を支援します。

詳しい指針については、ワークショップ構成のリファレンスを参照してください。

ステップ4：ワークショップごとの詳細計画を作成する

ステップ3で定義した各ワークショップについて、ワークショップ作成の設計図となる詳細な実施計画を作成します。

計画を作成する前に

ワークショップ作成の知識を読み込む：セッション内で最初の計画を作成する前に、educates-workshop-authoring スキルを呼び出し、Educates のワークショップ構成に関する知識を読み込みます。これはワークショップのファイルを作成するという意味ではありません。作成スキルの知識を利用できる状態にし、計画で正しいクリック可能なアクションの種類、現実的な YAML 設定オプション、適切なページ構成の規則、正確な演習ファイルのレイアウトを使えるようにするという意味です。作成スキルの知識により、計画を実現可能なものにし、単なる理想論にとどめません。

コースのリソースを確認する：ワークショップのテーマに関連する外部ドキュメントや参考資料については、planning/resources.md を読みます。以前の設計段階ですでに見つかった情報をウェブで再検索するのではなく、記載されているリソースを直接利用してください。計画の作成中に追加のリソースを見つけた場合は、関連するワークショップ名を注記して、すぐにファイルへ追加します。コースの作成者が記載したバージョンの修正や推奨される代替資料については、キュレーションのメモのセクションを確認してください。

順次連なるシリーズで前のワークショップがある場合（コアワークショップ、または別のワークショップに続く直線的な順序のワークショップ）：新しい計画を作成する前に、直前のワークショップの計画と、両方のワークショップの概要説明を必ず読んでください。これにより、内容の一貫性を保ち、不要な重複を避けられます。

選択ワークショップの場合：モジュールファイルに記載されたコアの前提条件を読みますが、ほかの選択ワークショップを完了しているとは想定しないでください。

単独のワークショップ、またはコースの最初のワークショップの場合：以前の計画を読む必要はありません。

ワークショップ計画を作成する

計画ファイルは planning/workshop-plans/ に作成し、ワークショップのディレクトリ名に合わせて命名します（例：workshops/lab-a01-first-decorator/ に配置するワークショップの場合は planning/workshop-plans/lab-a01-first-decorator.md）。

各計画は、次の標準的な 8 セクションで構成します。

1. ワークショップのメタデータ — 名前、タイトル、説明、所要時間、難易度、種類、前提条件
2. ワークショップの設定 — 必要なセッションアプリケーションと特別なセットアップ
3. 学習目標 — モジュールファイル（信頼できる情報源）に沿った内容
4. 前のワークショップとのつながり — 学習者がすでに知っていることと、再度教えるべきでない内容。前のワークショップがある場合は十分な内容を記述し、単独のワークショップや最初のワークショップでは省略します。
5. 作成する演習ファイル — exercises/ 以下のすべてのファイルについて、ファイル名、目的、初期内容を記述
6. ワークショップの説明ページ — ページごとの概要、コンテンツの概要、クリック可能なアクションの種類
7. ターミナルの作業ディレクトリの追跡 — 開始ディレクトリと、ワークショップ中の変更
8. 設計メモ — 設計上の判断、その理由、今後のワークショップに向けて意図的に行う準備。特定のテーマに絞ったコースでは、拡張案として、今後のワークショップで今回確立したパターンをどのように活用できるかを記述します。

計画を作成したら、モジュールファイル内のワークショップ項目に 詳細な計画 リンクを追加します（ステップ 3 を参照）。

既知の課題を追跡する

ワークショップの計画を作成した後、既知の課題、未解決の質問、または今後の対応が必要な領域がある場合は、planning/tasks.md にタスクとして追加します。ファイルがまだ存在しない場合は作成してください。

計画時に特定される一般的なタスクは次のとおりです。

• 実装時に検証が必要な設計上の判断
• Design Notes に記載された、追跡が必要な意図的な不足箇所
• 改訂が必要な可能性があると記された演習ファイルやページ
• 計画上の前提を検証すべき領域

モジュールファイル内のワークショップの項目と、計画の Workshop Metadata セクションに Status 行を追加し、tasks.md 内のワークショップのセクションへのリンクを記載します。

ファイル構成、タスクの形式、優先度レベルについては、Task Tracking Reference を参照してください。

全体の構成については Workshop Plan Reference を、ワークショップを順番に進める流れ、意図的な不足箇所、選択制の独立性、その他のガイドラインについては Plan Authoring Guidelines を参照してください。

Step 5: ワークショップを実装する

ワークショップごとの計画ができたら、実際のワークショップファイルを作成するために educates-workshop-authoring スキルに引き継ぎます。

実装を始める前に、設計段階でまとめた外部ドキュメントと参考資料を確認するため、planning/resources.md を読みます。これらのリソースは前のステップで収集し、精査済みです。一からウェブ検索するのではなく、まずこれらを参照してください。コース作成者が記したバージョンの修正情報や推奨する代替案については、整理メモのセクションを確認してください。実装中に新しいリソースを見つけた場合は、ファイルに追加します。

実装する各ワークショップについて、次の手順を行います。

1. planning/workshop-plans/ からワークショップごとの計画を読みます
2. educates-workshop-authoring スキルを呼び出します
3. 計画を設計図として使用します。計画には、演習ファイル、ページ構成、クリック可能なアクションの種類、ターミナルのパターンが指定されています
4. 作成スキルが、Educates 固有の実装の詳細（YAML 設定、クリック可能なアクションの構文、ページ構成、検証チェックリスト）を扱います

ワークショップファイルは planning/ ディレクトリとは分けて、workshops/ ディレクトリに作成します。

タスクの追跡を更新する

ワークショップを実装した後、計画と照らし合わせて結果を確認し、planning/tasks.md を更新します。

• 実装によって解決した既存のタスクには、完了を示す [x] を付けます
• 計画と実際の実装との間にある不足箇所について、新しいタスクを追加します（例：簡略化された演習、先送りされたページ、計画どおりに実装できなかったクリック可能なアクション）
• 外部ライブラリやツールの動作がドキュメントの記載と異なることが実装中に判明した場合は、調査の背景（試したこと、失敗した理由、適用した回避策、該当する場合は上流の参照先）をタスクの子項目として記録します。形式と例については、Task Tracking Reference を参照してください
• 現在の状態を反映するように、モジュールファイルと計画内のワークショップの Status 行を更新します

計画ドキュメントの更新

実装が計画から大きく逸脱した場合は、実際に構築した内容を反映するように計画ドキュメントを更新します。計画には当初の意図だけでなく、実際に構築した設計を記載してください。後続のワークショップでは、前の計画を参照するため、計画が古いままだと誤った前提につながります。

次の場合は、ワークショップ計画ファイル（planning/workshop-plans/lab-*.md）を更新します。

• アプローチや手法を変更した（例：クラスベースから関数ベースに切り替えた）
• ページを追加、削除、並べ替えた、またはトピックを変更した
• 演習ファイルが計画に記載したものと異なる
• 実際に達成可能な内容に応じて学習目標が変わった

ページのファイル名は内容と一致させます。実装中にページのトピックを変更した場合は、ファイル名も内容に合わせて変更し（例：03-old-topic.md → 03-new-topic.md）、計画内のページ一覧も新しいファイル名に更新します。

変更がワークショップの学習目標やストーリー展開に影響する場合は、モジュールファイル（course-module-X.md）内のワークショップ項目も更新し、内容の正確性を保ちます。

順序のあるワークショップでは、後続のワークショップの計画や実装が、変更箇所を参照していないかも確認します。後続ワークショップの「前のワークショップとのつながり」セクション、演習ファイル、ストーリー上の導入部分では、当初のアプローチが前提になっている場合があります。順序全体の一貫性が保たれるよう、確認して更新してください。

ステップ 6：一貫性を確認する

計画ドキュメントと生成されたワークショップの一貫性を定期的に確認します。複数のワークショップを作成した後や、しばらくプロジェクトを離れていた場合に特に有効です。以下の確認項目はコースの範囲に応じて適用し、該当しない項目は省略します。

確認項目

計画ドキュメントの一貫性：

• モジュールファイル（course-module-X.md）に記載されたすべてのワークショップに、workshop-plans/ 内の対応する計画ファイルがある
• ワークショップ項目で参照されているトピックが、course-topics.md に存在する（トピックドキュメントがない場合は省略）
• 計画やワークショップファイルで参照されている前提条件が、定義済みのワークショップとして実際に存在する
• 順序のあるワークショップを含むコースでは、ストーリーのつながりが途切れていない。各ワークショップの概要が次のワークショップへつながっている（単独のワークショップでは省略）

実装の一貫性（作成済みのワークショップが対象）：

• 完了済みワークショップの計画ファイルすべてに対応するディレクトリが、workshops/ 配下にある
• ワークショップのディレクトリ名が計画ファイル内の名前と一致している
• 計画に記載された演習ファイルが、ワークショップの exercises/ ディレクトリに存在する
• ワークショップ計画のページ一覧が、ワークショップの content/ ディレクトリ内にある実際のページファイル（ファイル名、順序、トピック）と一致している
• ページのファイル名が内容を反映している。以前のアプローチで使用していたファイル名が残っていない

相互参照の整合性：

• ワークショップファイル内の「詳細な計画」リンクが、正しいパスで既存のファイルを指している
• 計画ドキュメント間のファイル参照に、古い名前が残っていない

タスク追跡の一貫性（tasks.md が存在する場合）：

• tasks.md のワークショップのステータスが、各ワークショップの実際の状態と一致している
• モジュールファイルの項目と計画ファイル内のステータス行が、tasks.md の正しいアンカーにリンクしている
• 完了済みタスク（[x]）が、解決済みの問題を正確に反映している
• すでに修正された問題に対する古いタスクが残っていない

拡張方針（重点コースと標準コース）：

• モジュールファイルとコース概要に記載された今後の拡張案が引き続き適切で、実際に作成されたワークショップによって不要になっていない

検証結果をタスクとして記録する

検証中に見つかった問題は、会話で報告するだけでなく、planning/tasks.md にタスクとして記録します。これにより、問題を追跡し、後で対処できるようになります。特に、休止期間を挟んでプロジェクトに戻る場合に役立ちます。

• 見つかった問題ごとに、適切な優先度を設定して新しいタスクを追加します
• 検証結果を反映するよう、ワークショップの Status 行を更新します
• 作成したタスクを示しながら、会話で概要を報告します

planning/tasks.md がまだ存在せず、問題が見つかった場合は、新たに作成します。問題が見つからなければ、タスクファイルは必要ありません。

いつでもタスクに取り組む

ユーザーは、いつでも「次に何に取り組めばよいですか？」と尋ねることができます。その場合は、planning/tasks.md を確認し、優先度（まず P1）、ワークショップのステータス（最も状態の悪いものから）、順次依存関係（連鎖の早い段階にあるワークショップから）に基づいて作業を提案します。ユーザーは通常のワークフローの手順以外でも、いつでもタスクを追加できます。その場合は、適切な優先度を設定して追加します。

既存コースへの後付け

このスキルを、すでにワークショップ（workshops/ ディレクトリ内）があるものの計画ドキュメントがない、または計画ドキュメントが不完全なプロジェクトに適用する場合は、既存のワークショップを監査し、計画関連の成果物を整備することを提案します。

既存の作業を検出する

セッションの開始時に、プロジェクトに既存のワークショップ用サブディレクトリを含む workshops/ ディレクトリがある場合は、対応する計画ドキュメントが存在するか確認します。

• 既存の各ワークショップに対応するワークショップ計画ファイルが planning/workshop-plans/ にありますか？
• ワークショップの構成ファイル（planning/course-module-X.md）はありますか？
• planning/tasks.md はありますか？

ワークショップは存在するものの、計画ドキュメントがない、または不完全な場合は、既存のワークショップをレビューし、タスクファイルを含む不足した計画関連の成果物を作成することを積極的に提案します。

既存のワークショップを監査する

既存のワークショップをレビューする際は、それぞれの完全性を評価します。

• ワークショップの構成：workshop.yaml、手順ページ、演習ファイルがありますか？
• 手順ページ：すべてのページが存在し、内容が充実していますか？ それとも、一部がプレースホルダー、または欠落していますか？
• 演習ファイル：演習は手順ページと連携していますか？ それとも不足がありますか？
• クリック可能なアクション：アクションは適切に記述され、機能しますか？
• ナラティブの流れ：順次進むワークショップの場合、ナラティブのつながりは保たれていますか？

評価に基づき、各ワークショップにステータス（ほぼ完成、中程度の修正が必要、未完成、大幅に未完成）を割り当て、見つかった具体的な問題を planning/tasks.md に記入します。各タスクには、該当ファイルを示すソースリンクを含めます。

ワークショップの状態を計画に反映する

既存のワークショップがあるコースの計画ドキュメントを作成または更新する場合は、次の点に留意します。

• ワークショップの構成ファイルには、意図した設計だけでなく、既存のワークショップの実際の状態を反映します。既知の問題があるワークショップには Status 行を含めます。
• 既存のワークショップの個別計画には、ワークショップをゼロから作成するかのように記述するのではなく、すでにあるものと変更が必要なものを記載します。
• コースの概要では、既存の作業に触れ、計画の目的がそれを拡張または改善することであると説明します。

既存のワークショップが作業途中である可能性を考慮してください。目的は、完成品の基準と照らして評価することではなく、現在の状態を正確に把握し、タスク管理を通じて完成へ導くことです。

既存の命名規則への対応

既存のコースで作業する場合は、変更を加える前に、どの命名規則が使われているかを確認します。

規則の判定

既存の planning/course-module-*.md ファイルを確認します。

• 文字ベースの規則（現行）： course-module-a.md のようなファイル名や、lab-a01-workshop-name のようなワークショップ名です。これは現行の規則です。新しい作業にはすべてこの規則を使用してください。
• 数字ベースの規則（旧規則）： course-module-1.md のようなファイル名や、lab-workshop-name のようなワークショップ名（ワークショップコードなし）です。以前の規則です。

新しいコースでは、必ず文字ベースの規則を使用します。新しいコースを数字ベースの規則で開始することはできません。

旧規則のコースでの作業

既存のコースが数字ベースの規則を使用している場合は、一貫してその規則を使い続けてください。コース内で規則を混在させないでください。数字ベースの名前に文字ベースのワークショップ名を追加すると、混乱を招きます。

旧規則のコースを拡張する場合：

• モジュールの番号付けは course-module-N.md のまま続けます
• ワークショップコードなしの lab-workshop-name を引き続き使用します
• その他の現行ガイドライン（構成、相互参照など）には従ってください

数字ベースから文字ベースの規則への移行

移行は、ユーザーから明示的に依頼された場合にのみ行います。作業を進める前に、次の点を警告してください。

• デプロイへの影響： ワークショップ名を変更すると、TrainingPortal の定義、URL、外部参照における名前も変わります。ワークショップ名を参照している既存のデプロイは動作しなくなります。
• リポジトリの履歴： git mv で履歴は保持されますが、名前の変更は後続のすべての参照に影響します。

作業を進める前に、明示的な確認を得てください。

移行の対象は次のとおりです。

ファイル名の変更（履歴を保持するため git mv を使用）：

• planning/course-module-N.md → planning/course-module-X.md（N は対応する文字に置き換えます：1→a、2→b など）
• ワークショップ計画ファイル：planning/workshop-plans/lab-name.md → planning/workshop-plans/lab-X01-name.md
• ワークショップディレクトリ：workshops/lab-name/ → workshops/lab-X01-name/

計画ファイルの内容の更新：

• モジュール見出し：「Module 1」→「Module A」、「Module 2」→「Module B」など
• ワークショップ見出し：「### Workshop 1:」→「### Workshop A01:」。各モジュール内の現在の順序に基づいて割り当てます
• ワークショップ名のフィールド：lab-name → lab-a01-name
• すべての相互参照リンクとアンカー（詳細計画へのリンク、ステータスリンク、タスクアンカー）
• 前提条件：「Workshop 1: Title」→「Workshop A01: Title」
• course-topics.md のトピック番号：モジュール間での連番から、モジュールごとに 1 から始まる番号に変更します。モジュール見出しも文字を使う形式に更新します

ワークショップファイルの内容の更新：

• ワークショップのメタデータ（resources/workshop.yaml）：metadata.name を更新します
• ワークショップのリソース定義：ワークショップ名を更新します
• ワークショップの手順の内容：テキスト内の相互参照を更新します（例：「as shown in Workshop 1」→「as shown in Workshop A01」）

プロジェクトルートのファイルの更新：

• README.md：モジュールへの参照とワークショップ名を更新します
• CLAUDE.md（または同等のファイル）：計画ファイル名やワークショップ名への参照を更新します

移行後、計画ファイルとワークショップの内容に、旧数字ベースの規則への参照が残っていないことを確認してください。

Parts/Spine から Modules/Core への移行

既存のコースリポジトリで古い「parts」と「spine」という用語が使われている場合は、このガイドに従って現行の「modules」と「core」の規則に更新してください。

ファイル名の変更

履歴を保持するため、git mv を使用します。

旧名称	新名称
planning/part-N-workshops.md	planning/course-module-X.md（X は対応する文字です：1→a、2→b など）
planning/workshops.md（存在する場合）	planning/course-module-a.md

計画ファイルの内容を更新する

ファイル名を変更した後、以下の内容を更新します。

planning/course-brief.md:

• Course Structure セクションおよびパートに言及している箇所で、「Part N」→「Module X」（X は対応する文字）
• Navigation Model セクションで「spine」という用語を使用している場合は、「spine」→「core」

planning/course-topics.md:

• セクション見出し：「## Part N —」→「## Module X —」（X は対応する文字）
• トピック番号：すべてのモジュールを通した連番ではなく、各モジュールで1から始めます

planning/course-module-X.md（名前を変更したワークショップ内訳ファイル）：

• セクション見出し：「## Spine Workshops」→「## Core Workshops」
• ワークショップ見出し：「### Workshop N:」→「### Workshop X01:」（モジュールの文字とゼロ埋めした番号を使用）
• ワークショップの種類フィールド：「Type: Spine」→「Type: Core」（「Type — Spine」も「Type — Core」に変更）
• 「spine/elective」への文章中の言及は「core/elective」に変更
• タイトルに「Part N」が含まれている場合は「Module X」に変更

planning/tasks.md:

• セクション見出し：「## Part N:」→「## Module X:」
• ワークショップのセクション見出しにワークショップコードを追加

planning/workshop-plans/ 内のワークショップ計画ファイル：

• Workshop Metadata の種類フィールド：「spine」→「core」
• Name フィールド：lab- の接頭辞の後にワークショップコードを追加します（例：lab-name → lab-a01-name）
• part-N-workshops.md への参照を course-module-X.md に変更
• 「spine」ワークショップへの文章中の言及は「core」ワークショップに変更
• 計画ファイル名にワークショップコードを追加します（例：lab-name.md → lab-a01-name.md）

プロジェクトルートファイルの内容を更新する

README.md:

• セクション見出しの「Course Parts」→「Course Modules」
• 「Part N — Title」→「Module X — Title」
• planning/part-N-workshops.md への参照を planning/course-module-X.md に変更
• 「spine」への参照を「core」に変更

CLAUDE.md（または同等の AI アシスタント向け指示ファイル）：

• 「spine」または「parts」への言及を「core」および「modules」に変更
• 計画ファイル名への言及を更新

ワークショップファイルの内容を更新する

ワークショップのディレクトリ名にワークショップコードを追加します：workshops/lab-name/ → workshops/lab-a01-name/

ワークショップのメタデータとリソースファイルを更新します：

• resources/workshop.yaml 内の metadata.name にワークショップコードを追加
• 該当する場合は、type: spine → type: core
• ワークショップの手順書内の文章による相互参照（例：「Workshop 1 に示すように」→「Workshop A01 に示すように」）

移行後の確認

移行が完了したら、以下を確認します。

• grep -ri "spine" planning/ で結果が返されないこと（用語の変更を説明する意図的な注記は除く）
• grep -ri "part-[0-9]" planning/ で結果が返されないこと
• ls planning/part-* で結果が返されないこと（すべて名前が変更されていること）
• ls planning/workshops.md で結果が返されないこと（course-module-a.md に名前が変更されていること）
• すべてのワークショップ名にワークショップコードが含まれていること（例：lab-name ではなく lab-a01-name）
• 計画ファイル内のすべての相互参照リンクが正しく解決されること（特に、ワークショップ内訳の項目から計画ファイルへのリンク、および計画ファイルから tasks.md へのリンク）

計画ディレクトリの構成

すべての計画ドキュメントは、プロジェクトルートの planning/ ディレクトリに置きます。

planning/
├── course-brief.md             # Step 1: Course vision, scope, and requirements
├── resources.md                # Step 1: External references and documentation
├── course-topics.md            # Step 2: Topics organized by module
├── course-module-a.md          # Step 3: Module A workshop breakdown
├── course-module-b.md          # Step 3: Module B (when applicable)
├── tasks.md                    # Task tracking (created when issues emerge)
└── workshop-plans/             # Step 4: Per-workshop detailed plans
    ├── lab-a01-first-workshop.md
    ├── lab-a02-second-workshop.md
    └── ...

単一モジュールのコースでは、course-module-a.md のみを使用します。モジュールの数にかかわらず、構成は同じです。

プロジェクトルートにある workshops/ ディレクトリ（planning/ と並列）には、ステップ 5 で作成した Educates の実際のワークショップ実装を格納します。

ファイル名の規則と相互参照リンクのパターンについては、計画ディレクトリのリファレンスを参照してください。

リファレンスガイド

特定のトピックについて詳しくは、以下をご覧ください。

• 計画ディレクトリのリファレンス — ディレクトリ構造、ファイル名の規則、相互参照リンクのパターン
• コース概要のリファレンス — コース概要に記載する内容と、各セクションに関するガイダンス
• コースリソースのリファレンス — コース設計中に見つかった外部ドキュメントや参考資料を追跡する方法
• コーストピックのリファレンス — トピックのブレインストーミング、整理、注釈付けの方法
• ワークショップ分割のリファレンス — 目標、前提条件、分類を含めてトピックをワークショップに割り当てる方法
• ワークショップ計画のリファレンス — ワークショップごとの実施計画における標準的な8セクションの構成
• 計画作成ガイドライン — ワークショップの順序立てた進行、意図的な空白、選択科目の独立性、その他の計画作成ガイドラインに関する規則
• タスク追跡のリファレンス — タスクファイルの構造、ステータスの値、優先度、ライフサイクルに関する規則

スキルのバージョン

スキルのバージョンについて尋ねられた場合は、VERSION.txt ファイルを読み、その内容をユーザーに伝えてください。

ヘルプの利用

Educates の詳細については、Educates のドキュメントをご覧ください：https://docs.educates.dev/