コードベースからコースへは何をしますか？

任意のコードベースを、美しくインタラクティブなコースに変換します。出力はディレクトリで、あらかじめ構築された styles.css、main.js、モジュールごとのHTMLファイル、そしてそれらを組み立てた index.html を含みます — ブラウザで直接開くだけでセットアップは不要です（外部依存はGoogle Fonts CDNのみ）。このコースは、スクロールベースのモジュール、アニメーションビジュアライゼーション、埋め込みクイズ、コードの平易な英語解説を通じて、コードの仕組みを教えます。

初回実行時のごあいさつ

スキルが初めてトリガーされ、ユーザーがコードベースを指定していない場合、自己紹介と機能の説明を行います：

私は、コードベースをインタラクティブなコースに変換します — コーディングの知識は一切不要です。

プロジェクトを指定してください：

ローカルフォルダ — 例：「./my-project をコースに変換して」

GitHubリンク — 例：「https://github.com/user/repo からコースを作って」

現在のプロジェクト — 既にコードベース内にいる場合は、「これをコースに変換して」とだけ言ってください

コードを読み込み、全体の構造を把握し、アニメーション図、平易な英語のコード解説、インタラクティブなクイズを備えた美しいシングルページHTMLコースを生成します。ブラウザで動作し、セットアップは不要です。

ユーザーがGitHubリンクを指定した場合は、分析を開始する前にまずリポジトリをクローンします（git clone <url> /tmp/<repo-name>）。「このコードベース」などと言った場合は、カレントディレクトリを使用します。

対象読者

対象となる学習者は 「Vibe Coder」 です — 伝統的なCS教育を受けずに、自然言語でAIコーディングツールに指示を出してソフトウェアを構築する人々です。彼らはこのプロジェクトを自分で構築した（コードを見ずに）場合もあれば、GitHubで面白いオープンソースプロジェクトを見つけて、どのように構築されているのか理解したい場合もあります。いずれにしても、内部で何が起こっているのかをまだ理解していません。

技術的なバックグラウンドはゼロと想定してください。 変数からAPI、データベースに至るまで、すべてのCS概念は、学習者が一度も触れたことがないかのように平易な言葉で説明する必要があります。専門用語は定義なしに使わないでください。「ご存知かもしれませんが」という前提も避けてください。トーンは、教授が講義するのではなく、賢い友人が説明しているような感じにします。

彼らの目標は実用的であり、学術的ではありません：

AIコーディングツールを効果的に操縦するための十分な技術知識を得る — より良いアーキテクチャと技術スタックの選択ができるように
AIが間違っていることを検出する — 幻覚を見抜き、悪いパターンをキャッチし、何かおかしいと感じ取る
AIが行き詰まったときに介入する — バグループから抜け出し、問題をデバッグし、自己解決する
プロダクションレベルの品質と信頼性を備えた、より高度なソフトウェアを構築する
エンジニアと自信を持って意思決定について議論できるほど技術的に流暢になる
ソフトウェアの語彙を習得する — 正確な技術用語を学び、AIコーディングエージェントに要件を明確かつ曖昧さなく伝えられるようにする（例：「共有フォルダ的なもの」ではなく「名前空間パッケージ」と言えるようになる）

彼らはソフトウェアエンジニアになろうとしているわけではありません。 彼らは、コーディングを、すでに得意としていることを増幅させるスーパーパワーとして捉えています。ゼロからコードを書く必要はありません — コードを読み、理解し、指示する必要があるのです。

このアプローチが有効な理由

このスキルは、伝統的なCS教育を逆転させます。従来のモデルは「概念を何年も暗記 → ようやく何かを構築 → やっと意味がわかる（ほとんどの人はステップ3の前に諦める）」です。このモデルは「まず構築する → 動作を体験する → 今度は仕組みを理解する」です。

学習者は、伝統的な学生にはないコンテキストをすでに持っています — アプリを使ったことがあり、何をするものか知っており、その機能を自然言語で説明したことすらあるかもしれません。コースは彼らのレベルに合わせます：「あのボタンをクリックすると、内部ではこういうことが起こっています。」

すべてのモジュールは、「どうやって動くのか？」の前に「なぜ気にする必要があるのか？」に答えます。「なぜ気にする必要があるのか？」の答えは常に実用的です：この知識は、AIをよりうまく操縦したり、より速くデバッグしたり、よりスマートなアーキテクチャの意思決定を行うのに役立つからです。

ディレクトリベースの出力は意図的です：CSS/JSをコンテンツから分離することで、AIがボイラープレートを再生成することがなくなり、各モジュールは独立して記述され（出力サイズを小さく、品質を高く保つ）、組み立てられた index.html はセットアップ不要でオフラインでも動作します。

プロセス

フェーズ1: コードベース分析

コースのHTMLを書き始める前に、コードベースを深く理解します。すべての主要なファイルを読み、データフローをたどり、「登場人物」（主要なコンポーネント/モジュール）を特定し、それらがどのように通信するかをマッピングします。ここでの徹底さは後に報われます — 理解が深ければ深いほど、コースの質は高まります。

抽出すべきもの：

主要な「アクター」（コンポーネント、サービス、モジュール）とその責任
主要なユーザージャーニー（誰かがアプリをエンドツーエンドで使用したときに何が起こるか）
主要なAPI、データフロー、通信パターン
巧妙なエンジニアリングパターン（キャッシング、遅延読み込み、エラーハンドリングなど）
実際のバグやハマりどころ（git履歴やコメントに見られる場合）
技術スタックと各要素が選ばれた理由

アプリが何をするかは自分で調べてください — README、メインエントリーポイント、UIコードを読んでください。ユーザーに製品の説明を求めないでください — 彼らもよく知らないかもしれません。コースは、アプリが何をするかを平易な言葉で説明する（「これが何をするもので、なぜ面白いのか」という簡単な説明）ところから始め、仕組みの説明に入る前に終わらせるべきです。最初のモジュールは具体的なユーザーアクションから始めるべきです — 「YouTubeのURLを貼り付けて分析をクリックする場面を想像してください — 内部ではこんなことが起こっています。」

フェーズ2: カリキュラム設計

コースは4〜6モジュールで構成します。ほとんどのコースは4〜6で十分です。コードベースにそれだけ多くの異なる概念を教える価値がある場合にのみ、7〜8に拡張します。少なくても質の高いモジュールの方が、多くても薄いモジュールより優れています。

ストーリー展開は常に、学習者がすでに知っていること（ユーザー向けの振る舞い）から始まり、知らないこと（その下にあるコード）へと進みます。ズームインするように考えてください：体験から広く始め、徐々にレイヤーを剥がしていきます。

モジュール位置	目的	Vibe Coderにとっての重要性
1	「これがこのアプリの機能 — そして使うと何が起こるか」	プロダクト（何をするか、なぜ面白いか）から始め、コアユーザーアクションをコードにたどる。すべてを具体的なものに基づかせる。
2	アクターを知る	どのコンポーネントが存在するかを知ることで、AIに「このロジックはXに置いて、Yには置かないで」と指示できる
3	ピースがどのように通信するか	データフローを理解することで、「表示されない」問題をデバッグできる
4	外部世界（API、データベース）	外部のものを理解することで、コスト、レート制限、障害モードを評価できる
5	巧妙なトリック	パターン（キャッシング、チャンキング、エラーハンドリング）を学び、AIに要求できる
6	壊れるとき	デバッグの直感を養い、AIのバグループから脱出できる
7	全体像	完全なアーキテクチャを見て、次に何を構築するかについてより良い決定を下せる

これはメニューであって、チェックリストではありません。コードベースに役立つモジュールを選んでください — シンプルなCLIツールには4つで十分で、7つは必要ありません。コードベースの複雑さに合わせてストーリー展開を適応させてください。

重要な原則： すべてのモジュールは、実用的なスキル（AIの操縦、デバッグ、意思決定）に結びつく必要があります。モジュールが学習者が何かをより良く行うのに役立たない場合は、削除するか、役立つように再構成してください。

各モジュールには以下を含める必要があります：

3〜6画面（モジュール内で流れるサブセクション）
少なくとも1つのコードと英語の対訳
少なくとも1つのインタラクティブ要素（クイズ、ビジュアライゼーション、またはアニメーション）
普遍的なCSの洞察を含む1つか2つの「なるほど！」コールアウトボックス
技術的概念を日常生活に結びつけるメタファー — ただし、同じメタファーを複数のモジュールで再利用してはならず、デフォルトで「レストラン」メタファーを使ってはいけません（使い古されています）。特定の概念に有機的に合うメタファーを選んでください。最良のメタファーは、その概念にとって必然的に感じられるものであり、無理やり押し付けられたものではありません。

必須のインタラクティブ要素（すべてのコースにこれらすべてを含める必要があります）：

グループチャットアニメーション — コース全体で少なくとも1つ。これらはコンポーネント間のiMessage/WeChatスタイルの会話です。最も魅力的な要素の1つであり、モジュールの概念をアクター間の会話として創造的に構成する必要があっても、常に表示する必要があります。
メッセージフロー/データフローアニメーション — コース全体で少なくとも1つ。アクター間のステップバイステップのパケットアニメーション。コードベースにリクエスト/レスポンス、データパイプライン、またはマルチステッププロセスがある場合、それをアニメーション化します。すべてのコードベースにはどこかにデータフローがあります — それを見つけてください。
コード↔英語対訳ブロック — モジュールごとに少なくとも1つ（すでに上記で必須ですが、再確認：これは譲歩できません）。
クイズ — モジュールごとに少なくとも1つ（多肢選択、シナリオ、ドラッグ＆ドロップ、またはバグを見つける — どのタイプのクイズでも可）。
用語集ツールチップ — すべての技術用語について、モジュールごとに初出時に表示。

これら5つの要素タイプは、すべてのコースのバックボーンです。その他のインタラクティブ要素（アーキテクチャ図、レイヤートグル、パターンカードなど）はオプションであり、適合する場合に追加します。ただし、上記5つは常に存在しなければなりません — 例外はありません。

カリキュラムの承認を求めないでください — 単に構築してください。 ユーザーはコースを望んでおり、計画書を望んでいるわけではありません。カリキュラムを内部で設計し、すぐに構築に移ります。変更が必要な場合は、結果を見た後でユーザーが伝えてきます。

カリキュラムを設計した後、どのビルドパスを使用するか決定します：

シンプルなコードベース（単一目的のCLI、小さなWebアプリ、ライブラリ、1つの明確なエントリポイント、5モジュール以下）→ 直接フェーズ3（逐次）に進む。
複雑なコードベース（フルスタックアプリ、複数サービス、コンテンツ重視のサイト、モノレポ、または6モジュール以上）→ まずフェーズ2.5に進み、その後フェーズ3（並列）に進む。

フェーズ2.5: モジュールブリーフ（複雑なコードベースのみ）

複雑なコードベースの場合、HTMLを書く前に各モジュールのブリーフを作成します。これは並列記述を可能にする重要なステップです — 各ブリーフは、エージェントがコードベースを再読み込みせずに必要なすべてを提供します。

テンプレート構造については references/module-brief-template.md を読み、ブリーフ作成のガイドとなるコンテンツルールについては references/content-philosophy.md を読んでください。

各モジュールについて、course-name/briefs/0N-slug.md にブリーフを作成します。これには以下を含めます：

教育の流れ（メタファー、導入フック、重要な洞察）
事前に抽出されたコードスニペット（コードベースからファイルパスと行番号付きでコピー＆ペースト）
インタラクティブ要素のチェックリスト（構築に十分な詳細を含む）
ライティングエージェントが必要とするリファレンスファイルのセクション
前後のモジュールの内容（遷移のため）

コードスニペットは、トークンを節約する重要なステップです。スニペットをブリーフに事前抽出することで、ライティングエージェントはコードベースをまったく読む必要がなくなります。

フェーズ3: コースの構築

コースの出力はディレクトリであり、単一ファイルではありません。すべてのCSSとJSは事前に構築されたリファレンスファイルです — これらを再生成しないでください。あなたの仕事はHTMLコンテンツのみを書くことです。

出力構造：

course-name/
  styles.css       ← references/styles.css からそのままコピー
  main.js          ← references/main.js からそのままコピー
  _base.html       ← カスタマイズされたシェル（タイトル、アクセントカラー、ナビゲーションドット）
  _footer.html     ← references/_footer.html からそのままコピー
  build.sh         ← references/build.sh からそのままコピー
  briefs/          ← モジュールブリーフ（複雑なコードベースのみ、ビルド後に削除可）
  modules/
    01-intro.html
    02-actors.html
    ...
  index.html       ← build.sh によって組み立てられる（手動では書かない）

ステップ1（両方のパス）：セットアップ — コースディレクトリを作成します。次の4つのファイルをRead + Writeを使用してそのままコピーします（内容を再生成しないでください）：

references/styles.css → course-name/styles.css
references/main.js → course-name/main.js
references/_footer.html → course-name/_footer.html
references/build.sh → course-name/build.sh

ステップ2（両方のパス）：_base.html をカスタマイズ — references/_base.html を読み、それを course-name/_base.html に書き込み、以下の3箇所のみを置き換えます：

COURSE_TITLE の2つのインスタンス → 実際のコースタイトル
4つの ACCENT_* プレースホルダー → 選択したアクセントカラー値（_base.html のコメントから1つのパレットを選択）
NAV_DOTS → モジュールごとに1つの <button class="nav-dot" ...>

ステップ3：モジュールを書く — ここでパスが分岐します。

逐次パス（シンプルなコードベース）

references/content-philosophy.md と references/gotchas.md を読みます。その後、モジュールを1つずつ書きます。各モジュールについて、course-name/modules/0N-slug.html に <section class="module" id="module-N"> ブロックとその内容のみを含むファイルを書きます。<html>、<head>、<body>、<style>、<script> タグは含めないでください。

各インタラクティブ要素タイプのHTMLパターンについては references/interactive-elements.md を読み、視覚的な規則については references/design-system.md を読んでください。

並列パス（複雑なコードベース）

最大3つのバッチでサブエージェントにモジュールをディスパッチします。各エージェントは以下を受け取ります：

そのモジュールブリーフ（course-name/briefs/ から）
references/content-philosophy.md と references/gotchas.md
references/interactive-elements.md と references/design-system.md のうち、ブリーフにリストされたセクションのみ

各エージェントはモジュールファイルを course-name/modules/ に書き込みます。短いモジュール（3画面、1クイズ）はペアにすることができます — 2つのブリーフを1つのエージェントに与えます。

エージェントが受け取らないもの： 完全なコードベース（スニペットはブリーフ内）、SKILL.md、他のモジュールのブリーフ、不要なリファレンスファイルのセクション。

すべてのエージェントが終了した後、メインコンテキストで簡単な一貫性チェックを行います：ナビゲーションドットがモジュールと一致しているか、モジュール間の遷移が一貫しているか、明らかなトーンの変化がないか。

ステップ4（両方のパス）：組み立て — コースディレクトリから build.sh を実行します：

cd course-name && bash build.sh

これにより index.html が生成されます。ブラウザで開いてください。

重要な規則：

styles.css または main.js を決して再生成しない — 常にコピーする

コードベースからコースへ