codebase-to-course

Codebase-to-Course

あらゆるコードベースを、魅力的でインタラクティブな単一ページの HTML コースに変換します。出力は、スクロールに応じて進むモジュール、アニメーション付きの図解、コードを平易な言葉に置き換えた解説を通じて、コードの仕組みを学べる、依存関係のない自己完結型の HTML ファイルです（Google Fonts を除く）。

初回起動時の案内

スキルが初めて呼び出され、ユーザーがまだコードベースを指定していない場合は、自己紹介し、何ができるかを説明します。

コードの知識がなくても、どんなコードベースでも仕組みを学べるインタラクティブなコースにできます。

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

• ローカルフォルダー — 例：「./my-project をコースにして」
• GitHub のリンク — 例：「https://github.com/user/repo からコースを作って」
• 現在のプロジェクト — すでにコードベースを開いている場合は、「これをコースにして」と伝えるだけです

コードを読み、全体がどうつながっているかを把握したうえで、アニメーション付きの図解や、コードを平易な言葉で説明する解説を含む、美しい単一ページの HTML コースを生成します。すべてブラウザーで動作するため、セットアップは不要です。

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

対象となる学習者

対象となるのは、自然言語で AI コーディングツールに指示してソフトウェアを作る「バイブコーダー」です。従来のコンピューターサイエンス教育を受けていない人を指します。自分でこのプロジェクトを作ったものの、コードを見ていない人もいれば、GitHub で興味深いオープンソースプロジェクトを見つけ、その作り方を知りたい人もいます。いずれの場合も、内部で何が起きているのかはまだ理解していません。

技術的な予備知識は一切ないものとします。 変数から API、データベースまで、コンピューターサイエンスの概念はすべて、初めて触れる人にもわかる平易な言葉で説明する必要があります。定義なしに専門用語を使わないでください。「ご存じのとおり」といった表現も避けてください。教授の講義ではなく、聡明な友人が説明するような口調にしてください。

目標は学術的なものではなく、実践的なものです。

• AI コーディングツールを効果的に導くために、より良いアーキテクチャや技術スタックを選べるだけの技術知識を身につける
• AI の誤りを見抜く — 幻覚を見抜き、悪いパターンに気づき、問題の兆候を察知する
• AI が行き詰まったときに介入する — バグのループから抜け出し、問題をデバッグし、自力で前進できるようにする
• 本番レベルの品質と信頼性を備えた、より高度なソフトウェアを作る
• エンジニアと自信を持って意思決定について話し合える、十分な技術的な知識と理解力を身につける
• ソフトウェアの語彙を身につける — 要件を AI コーディングエージェントに明確かつ曖昧さなく伝えられるよう、正確な技術用語を学ぶ（例：「共有フォルダーみたいなもの」ではなく、「名前空間パッケージ」という言葉を使えるようになる）

ソフトウェアエンジニアを目指しているわけではありません。 コーディングを、自分がすでに得意なことをさらに伸ばすための強力な手段にしたいのです。ゼロからコードを書く必要はありません。コードを読み、理解し、指示することが必要なのです。

このアプローチが機能する理由

このスキルでは、従来のコンピューターサイエンス教育を逆転させます。従来のモデルは、何年も概念を暗記する → いずれ何かを作る → ようやくその意義がわかる、というものでした（ほとんどの人はステップ3に至る前に挫折します）。このモデルでは、まず何かを作る → 動作するところを体験する → 仕組みを理解する、という順序になります。

学習者には、従来の学生にはない前提があります。アプリを使ったことがあり、何ができるかを知っていて、機能について自然言語で説明したことさえあるかもしれません。このコースでは、学習者の今いる地点から始めます。「いつもクリックしているあのボタン、クリックしたときに内部で何が起きるのかを見てみましょう。」

各モジュールでは、「仕組みはどうなっているか？」の前に、**「なぜ知る必要があるのか？」**に答えます。その答えは常に実践的です。この知識があれば、AI をより適切に導き、デバッグを迅速に行い、より賢明なアーキテクチャ上の判断ができるからです。

単一ファイルという制約には意図があります。HTML ファイルが1つなら、セットアップは不要で、すぐに共有でき、オフラインでも動作し、設計上の判断を簡潔に保つ必要があります。

---

プロセス（4つのフェーズ）

フェーズ1：コードベースの分析

コースの HTML を書く前に、コードベースを深く理解しましょう。主要なファイルをすべて読み、データの流れをたどり、「登場人物」（主要なコンポーネントやモジュール）を特定して、それらがどのように連携するかを把握します。ここでの徹底した分析は、後で必ず役立ちます。理解が深いほど、コースの質も高まります。

抽出する情報：

• 主な「役者」（コンポーネント、サービス、モジュール）とその役割
• 主要なユーザージャーニー（ユーザーがアプリを最初から最後まで使うときに起きること）
• 主要な API、データの流れ、通信パターン
• 優れたエンジニアリングパターン（キャッシュ、遅延読み込み、エラー処理など）
• 実際にあったバグや注意点（Git の履歴やコメントから確認できる場合）
• 技術スタックと、それぞれの要素が選ばれた理由

README、主要なエントリーポイント、UI コードを読んで、アプリが何をするのかを自分で把握してください。ユーザーに製品について説明を求めないでください。ユーザー自身も詳しくない可能性があります。コースでは、仕組みの解説に入る前に、平易な言葉でアプリが何をするのかを説明するところから始めます（「これは何をするもので、なぜ興味深いのか」を簡潔に紹介します）。最初のモジュールは具体的なユーザー操作から始めましょう。「YouTube の URL を貼り付けて［分析］をクリックしたと想像してください。内部では何が起きるのでしょうか。」

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

コースは 5～8 個のモジュールで構成します。全体の流れは、必ず学習者がすでに知っていること（ユーザー向けの動作）から始まり、まだ知らないこと（その下にあるコード）へと進みます。ズームインするように、まず全体的な体験から始めて、段階的に層を掘り下げていきます。

モジュールの位置	目的	バイブコーダーにとって重要な理由
1	「このアプリでできること、そして使ったときに起こること」	まずプロダクト（何ができるか、なぜ興味深いか）から始め、次に、ユーザーの主要な操作をコードまでたどります。具体的なものを起点にすることで、すべての内容に土台ができます。
2	登場する要素を知る	どのコンポーネントがあるかを把握し、AI に「このロジックは Y ではなく X に配置して」と伝えられるようにします。
3	要素どうしの連携方法	データフローを理解し、「表示されない」という問題をデバッグできるようにします。
4	外部の仕組み（API、データベース）	外部要素を把握し、コスト、レート制限、障害モードを評価できるようにします。
5	工夫された仕組み	パターン（キャッシュ、チャンク分割、エラー処理）を学び、AI にその実装を依頼できるようにします。
6	問題が起きたとき	デバッグの直感を養い、AI のバグ修正ループから抜け出せるようにします。
7	全体像	アーキテクチャ全体を把握し、次に何を作るかについて、より良い判断ができるようにします。

すべてのコードベースで 7 つすべてが必要なわけではありません。シンプルな CLI ツールなら、4～5 個のモジュールだけで十分かもしれません。マイクロサービスアプリなら、8 個必要かもしれません。コードベースの複雑さに応じて全体の流れを調整し、学習者が AI をより適切に導き、デバッグするうえで実際に役立つモジュールを判断してください。

重要な原則： すべてのモジュールを、実践的なスキル（AI への指示、デバッグ、意思決定）につなげてください。学習者が何かをより上手にできるようにならないモジュールは、削除するか、役立つ内容になるまで再構成してください。

各モジュールには、次の内容を含めてください。

• 3～6 個の画面（モジュール内で流れに沿った小区分）
• コードと英語の対訳を少なくとも 1 つ
• インタラクティブな要素（ビジュアライゼーションまたはアニメーション）を少なくとも 1 つ
• 普遍的な CS の知見を伝える「なるほど！」の吹き出しボックスを 1～2 個
• 技術的な概念を日常生活に結びつける比喩。ただし、同じ比喩をモジュール間で再利用してはならず、「レストラン」の比喩を安易に使ってはなりません（使い古されています）。概念に自然に合う比喩を選んでください。最良の比喩は、無理に当てはめるのではなく、その概念にとって必然的に感じられるものです。

必須のインタラクティブ要素（すべてのコースに、次のすべてを必ず含めてください）：

• グループチャットアニメーション — コース全体で少なくとも 1 つ。コンポーネント間の iMessage／WeChat 風の会話です。特に魅力的な要素なので、モジュールの概念を登場要素間の会話として創造的に表現する必要があっても、必ず含めてください。
• メッセージフロー／データフローアニメーション — コース全体で少なくとも 1 つ。登場要素間を移動するパケットを段階的にアニメーションで表現します。コードベースにリクエスト／レスポンス、データパイプライン、複数段階のプロセスがある場合は、アニメーションにしてください。どのコードベースにも、どこかにデータフローがあります。それを見つけてください。
• コード ↔ 英語の対訳ブロック — モジュールごとに少なくとも 1 つ（上記ですでに求めていますが、改めて強調します。これは必須です）。
• 用語集のツールチップ — 技術用語は、モジュール内で最初に登場する箇所すべてに付けてください。

これら 5 種類の要素が、すべてのコースの中核になります。そのほかのインタラクティブ要素（アーキテクチャ図、レイヤー切り替え、パターンカードなど）は任意で、内容に合う場合に追加してください。ただし、上記の 5 種類は必ずすべて含めてください。例外はありません。

カリキュラムを承認に回してはいけません。カリキュラムを設計したら、そのまま作成してください。 ユーザーが求めているのはコースであり、計画書ではありません。内部でカリキュラムを設計し、そのまま HTML の生成に進んでください。変更が必要であれば、結果を見たあとで伝えてもらえます。

フェーズ 3：コースの作成

CSS と JavaScript を埋め込んだ単一の HTML ファイルを生成します。CSS デザイントークン、タイポグラフィ、カラーシステムの詳細については、references/design-system.md を確認してください。あらゆる種類のインタラクティブ要素の実装パターンについては、references/interactive-elements.md を確認してください。

構築の順序（タスクごと）：

1. まずは基盤を作成 — すべてのモジュールセクション（空の状態）、完全な CSS デザインシステム、進捗状況を追跡するナビゲーションバー、スクロールスナップ動作、キーボード操作、スクロールをトリガーとするアニメーションを備えた HTML の枠組みを作成します。このステップの後には、スクロールして見て回れる動作する骨組みができているはずです。

2. モジュールを一つずつ作成 — 各モジュールのコンテンツ、コードの翻訳、インタラクティブ要素を追加します。8 つのモジュールすべてを一度に書こうとしないでください。品質が低下します。モジュール 1 を作成して動作を確認し、次にモジュール 2 を作成する、というように進めます。

3. 仕上げ — すべてのモジュールを作成した後、トランジション、モバイル対応、見た目の一貫性を最終確認します。

重要な実装ルール：

• ファイルは完全に自己完結している必要があります（外部依存は Google Fonts CDN のみ）
• CSS の scroll-snap-type: y proximity を使用します（mandatory は使用しないでください。長いモジュール内でユーザーが動けなくなります）
• セクションには 100vh のフォールバックを指定したうえで、min-height: 100dvh を使用します
• GPU パフォーマンスのため、アニメーションは transform と opacity のみに限定します
• すべての JS を IIFE で囲み、スクロールリスナーには passive: true を使用し、requestAnimationFrame でスロットリングします
• ドラッグ＆ドロップのタッチ操作、キーボード操作（矢印キー）、ARIA 属性に対応します

フェーズ 4：レビューして開く

コースの HTML ファイルを生成した後、ユーザーがレビューできるようにブラウザーで開きます。作成した内容を説明し、コンテンツ、デザイン、インタラクティブ性についてフィードバックを求めます。

---

コンテンツの方針

これらの原則が、優れたコースとありきたりなチュートリアルを分けます。コンテンツに関するあらゆる判断の指針として活用してください。

説明よりも視覚化を優先する

文章のかたまりは、読者の注意をそらします。コースは教科書よりもインフォグラフィックに近いものにします。以下のルールを厳守してください。

テキストの制限：

• テキストブロックあたり最大 2～3 文 にします。4 文目を書こうとしていたら、そこで止めて、代わりに視覚的な表現に変換します。
• テキストブロックは、コンテンツの幅を超えたり、約 4 行を超える高さになったりしてはなりません。そうなる場合は、視覚要素を使って分割します。
• すべての画面で 少なくとも 50% を視覚要素（図、コードブロック、カード、アニメーション、バッジなど、段落以外のあらゆるもの）にします。

テキストを視覚表現に変換：

• 3 項目以上のリスト → アイコン付きカード（パターンカード、機能カードなど）
• 手順の連続 → 矢印付きフロー図または番号付きステップカード
• 「コンポーネント A がコンポーネント B と通信する」→ アニメーション付きデータフローまたはグループチャットの図
• 「このファイルは X を行い、あのファイルは Y を行う」→ 注釈付きの視覚的なファイルツリーまたはアイコンと一言説明のバッジ
• コードの動作を説明する →（コードについての段落ではなく）コードと英語の対訳ブロック
• 2 つのアプローチを比較する → 視覚的な違いを明確にした横並びのカラム

視覚的な余白：

• 要素の間には十分な余白を設けます（セクション間に --space-8 から --space-12）
• 全幅の視覚要素と幅の狭いテキストブロックを交互に配置し、リズムを作ります
• すべてのモジュールに、画面内で大きな存在感を示し、核心となるコンセプトをひと目で伝える、図、アニメーション、またはインタラクティブ要素のいずれかを「ヒーロービジュアル」として最低 1 つ含めます

コード ↔ 英語の翻訳

すべてのコードスニペットには、英語の平易な説明を並べて表示します。左パネル：プロジェクトの実際のコードをシンタックスハイライト付きで表示します。右パネル：各行が何をするのかを、平易な英語で行ごとに説明します。これは、技術に詳しくない学習者にとって、最も価値のある学習ツールです。

重要：コードに横スクロールバーを表示しないでください。 すべてのコードに white-space: pre-wrap を使用して、スクロールするのではなく折り返すようにしてください。これは IDE ではなく、技術に詳しくない人向けのコースです。インデント構造を保つことよりも、読みやすさを優先してください。

重要：元のコードをそのまま使用してください。 コードベースのコードスニペットを変更、簡略化、切り詰めてはいけません。学習者が実際のファイルを開いたときに、学んだ内容とまったく同じコードが見つかることが信頼につながります。コードを編集して短くするのではなく、概念をうまく説明できる、自然に短くて歯切れのよいコードスニペット（5～10 行）をコードベースから選んでください。どのコードベースにも、簡潔で自己完結した箇所があるものです。長い関数を切り刻むのではなく、そうした箇所を見つけてください。

画面ごとに概念は1つ

文字の壁を作らないでください。モジュール内の各画面では、概念を1つだけ教えてください。もっとスペースが必要なら、詰め込まずに画面を追加してください。

まず比喩、それから実際のコード

新しい概念はすべて、日常生活の比喩を使って紹介してください。その直後に、「コードでは、次のようになります……」と実際の内容に結び付けてください。比喩が直感的な理解を促し、コードが現実に即した説明をします。

重要：比喩を使い回さないでください。 何にでも「レストラン」を使うのはやめてください。これは最もありがちな安易なやり方です。それぞれの概念には、その概念に自然に合った独自の比喩が必要です。データベースはカード目録のある図書館、認証は身分証を確認する用心棒、イベントループは航空管制官、メッセージパッシングは郵便システム、API のレート制限は収容人数の上限があるナイトクラブにたとえられます。最も思い付きやすい比喩ではなく、概念を腑に落とす比喩を選んでください。コース内で「レストラン」や「キッチン」を2回以上使っていることに気付いたら、いったん立ち止まって考え直してください。

たどりながら学ぶ

学習者がアプリで毎日すでに行っている操作をしたとき、実際に何が起きるかを追い、データの流れを最初から最後までたどってください。「クリックするあのボタンをご存じですよね？ クリックした後、データがたどる経路を見てみましょう……」というように説明します。学習者は結果をすでに体験しているので、その裏側の仕組みを見られるのです。大好きな映画のメイキングドキュメンタリーを見るようなものです。

記憶に残るものにする

一般的なコンピューターサイエンスの気付きを伝えるには、「なるほど！」というコールアウトボックスを使ってください。無理のない範囲でユーモアを取り入れてください（無理強いは禁物です）。コンポーネントに個性を持たせ、図の中の抽象的な箱ではなく、物語の「登場人物」として描いてください。

用語集ツールチップ — 用語を一つも取りこぼさない

あらゆる技術用語（API、DOM、コールバック、ミドルウェアなど）は、各モジュールで初めて登場する際に、破線の下線付きツールチップを表示します。デスクトップではホバー、モバイルではタップすると、英語で書かれた1〜2文の平易な定義が表示されます。学習者が用語を調べるためにページを離れる必要がないようにします。「技術に詳しくない人向け」とうたうだけのコースと、実際にそうなっているコースの違いはここにあります。

ツールチップは、徹底的に付けてください。 技術に詳しくない人がその単語を知らない可能性が1％でもあるなら、ツールチップを付けてください。次のものも対象です。

• 知らないかもしれないソフトウェア名（Blender、GIMP、Audacityなど）
• 開発者が日常的に使う用語（REPL、JSON、フラグ、CLI、API、SDKなど）
• プログラミングの概念（関数、変数、辞書、クラス、モジュールなど）
• インフラ関連の用語（PATH、pip、名前空間、エントリーポイントなど）
• 略語 — 初めて登場する略語には必ずツールチップを付けてください

語彙こそが学びです。 学習者がAIコーディングエージェントとのやり取りに必要な、正確な技術用語を身に付けることは、重要な目標の一つです。各ツールチップでは、学習者自身が指示にその用語を使えるように教えてください。たとえば、「フラグとは、コマンドの動作を変えるために追加するオプションです。たとえば「--json」を追加すると、プレーンテキストの代わりに構造化データを取得できます。AIに指示するときは、「詳細な出力を表示するフラグを追加してください」と伝えます。」

カーソル: 用語には cursor: help ではなく cursor: pointer を使ってください。疑問符のカーソルは無機質な印象ですが、ポインターならクリックできることが伝わり、親しみやすくなります。

ツールチップのはみ出し対策: 翻訳ブロックなど、overflow: hidden が指定されたコンテナーではツールチップが切れてしまいます。対策として、ツールチップのJSでは position: fixed を使い、コンテナー内のCSS position: absolute に依存するのではなく、getBoundingClientRect() から座標を計算する必要があります。ツールチップは用語要素内ではなく、document.body に追加してください。これにより、祖先要素の overflow によってツールチップが切れることを防げます。

デザインの指針

ビジュアルデザインは、美しい開発者のノートのように感じられるものにしてください。温かく、親しみやすく、個性があるデザインです。トークンシステムの全容は references/design-system.md を参照してください。ここでは、必ず守るべき原則を紹介します。

• 温かみのあるパレット：オフホワイトの背景（古びた紙のような色）、温かみのあるグレーを使い、冷たい白や青は使わないでください
• 印象的なアクセントカラー：自信のあるアクセントカラーを一色使います（朱色、コーラル、ティールなど。紫のグラデーションは使わないでください）
• 個性的なタイポグラフィ：見出しには個性のあるディスプレイフォントを使います（Bricolage Grotesque、または同様の太い幾何学的な書体を使用し、Inter、Roboto、Arial、Space Groteskは絶対に使わないでください）。本文には読みやすいサンセリフ体（DM Sansなど）、コードにはJetBrains Monoを使います
• ゆとりのある余白：各モジュールに余裕を持たせます。画面あたりの短い段落は最大3〜4つにしてください
• 背景を交互に切り替える：視覚的なリズムを生むため、偶数・奇数のモジュールで、温かみのある2種類の背景色を交互に使います
• 暗いコードブロック：深いインディゴチャコール（#1E1E2E）を背景に、Catppuccin風の構文ハイライトを使ったIDEスタイルにします
• 強すぎない奥行き：控えめで温かみのある影を使い、黒いドロップシャドウは使わないでください

---

注意点 — よくある失敗

ここに挙げるのは、コースの制作中に実際に発生した問題です。コースを完成とする前に、一つずつ確認してください。

ツールチップの切り取り

コードの折り返しのため、翻訳ブロックでは overflow: hidden を使います。用語要素内でツールチップに position: absolute を使うと、コンテナーによって切れてしまいます。対策: ツールチップには position: fixed を使い、document.body に追加する必要があります。位置は getBoundingClientRect() から計算してください。これは参照ファイルですでに指定されていますが、あらゆるビルドで最も頻繁に発生する不具合です。

ツールチップが足りない

最もよくある失敗は、ツールチップが不足していることです。技術に詳しくない学習者は、REPL、JSON、フラグ、エントリーポイント、PATH、pip、名前空間、関数、クラス、モジュール、PR、E2E、さらには Blender／GIMP のようなソフトウェア名さえ知りません。経験則： 技術に詳しくない友人との日常会話に出てこない用語には、ツールチップを付けてください。迷ったら、多すぎるくらいに付けましょう。ただし、ユーザーが自分の専門分野ですでによく知っている用語には付けないでください（例：AI 分野の人にとっての AI／ML の概念）。

文字の壁

コースがインフォグラフィックではなく、教科書のように見えます。これは、視覚的な区切りなしに2～3文を超えて書くと起こります。各画面の少なくとも50％を視覚要素にしてください。3項目以上のリストはすべてカードに、あらゆる手順はステップカードまたはフロー図に、コードの説明はすべてコード↔英語の対訳ブロックに変換してください。

比喩の使い回し

何にでも「レストラン」や「キッチン」を使うことです。各モジュールには、その概念にぴったりで、自然に感じられる独自の比喩が必要です。同じ比喩を二度使いそうになったら、いったん止めて、その概念に自然に合うものを探してください。

コードの変更

コードベースにあるコードスニペットを短くしたり、簡略化したり、「整理」したりすることです。学習者が実際のファイルを開いたとき、まったく同じコードが見えるようにしてください。コードを短くするために編集するのではなく、要点を示せる、コードベース内の自然に短いスニペット（5～10行）を選んでください。

スクロールスナップは必須

scroll-snap-type: y mandatory を使うと、ユーザーが長いモジュール内に閉じ込められてしまいます。必ず proximity を使ってください。

モジュールの品質低下

すべてのモジュールを一度に書こうとすると、後半のモジュールが薄く、急ごしらえになります。モジュールを一つずつ作成し、次に進む前にそれぞれを確認してください。

インタラクティブ要素の不足

テキストとコードブロックだけで、インタラクティブ要素がないモジュールです。各モジュールには、データフローアニメーション、グループチャット、アーキテクチャ図、ドラッグ＆ドロップのうち、少なくとも一つが必要です。これらは飾りではありません。技術に詳しくない学習者が情報を理解するための手段です。

---

参考ファイル

references/ ディレクトリには、詳細な実装仕様が含まれています。該当するフェーズに進んだら参照してください。

• references/design-system.md — CSS カスタムプロパティ、カラーパレット、タイポグラフィのスケール、余白のシステム、シャドウ、アニメーション、スクロールバーのスタイル設定を網羅しています。CSS を書く前に読んでください。
• references/interactive-elements.md — コード↔英語の対訳、グループチャットのアニメーション、メッセージフローの可視化、アーキテクチャ図、パターンカード、コールアウトボックスなど、すべてのインタラクティブ要素の実装パターンを説明しています。インタラクティブ要素を作る前に読んでください。