書籍1冊を、触って学べるWeb教材に。
その作成プロセスの全記録

つくったもの

「Kaggleで勝つデータ分析の技術」「BERTによる自然言語処理入門」などの専門書を、 章ごとの単一HTMLファイルとして教材化するシステムです。 各章にはセクション解説・数式（KaTeX）・Pythonコード・確認クイズ・用語集に加え、 混同行列シミュレーターやROC曲線アニメーションなどのCanvasインタラクティブデモが組み込まれています。

教材の原稿はすべて chapter-N.json という構造化データに集約し、 そこからHTMLをPythonスクリプトで自動生成。GitHubにpushすると Cloudflare Pages が自動デプロイし、 スマホからも学習できます。

なぜ作ったか

書籍PDFを読むだけの学習は受動的になりがちで、手を動かす仕組みと進捗の可視化が欲しかったためです。 加えて実務案件（機械学習系）に向けた事前学習を、体系的かつ再利用可能な形で残す狙いもありました。

システム全体フロー

1章の教材ができるまでの流れです。誰が（どのAIが）どの工程を担うかに注目してください。

開発フローの進化 — このプロジェクト最大の学び

最初からこの形だったわけではありません。初期はClaude自身が章HTMLを丸ごと書いていました。 1章あたり2,000行。動きはするものの、トークン消費が激しく、章を増やすほどコストと時間がかさむ構造でした。

転機は「JSONからHTMLへの変換は、実は機械的なテンプレート作業では？」という気づきです。 そこでClaude Codeに、HTML生成を代行するPythonスクリプト（gen_html.py）を作らせました。 LLMは「創造が必要な工程」（原稿の構造化・デモの設計）だけに集中し、機械的な変換はスクリプトに任せる分業です。

もうひとつの工夫: 巨大MDの分割生成パターン

Geminiが抽出したMDが100KBを超える章（3章は116KB）は、1エージェントのコンテキストに収まりません。 そこで2つのサブエージェントに前半セクション／後半セクション＋クイズ・用語集を分担させ、 中間JSONをPythonで結合するパターンを確立しました。以降の大型章はすべてこの方式で処理しています。

AIの役割分担 — Gemini × Claude Code

1つのAIに全部やらせるのではなく、得意分野で分業させています。 分担の境界は「長文の読解・抽出はGemini、構造化・コーディング・ファイル操作はClaude Code」です。

人間の役割は「章の決定」「GeminiへのPDF投下と抽出結果の持ち帰り」「品質の最終確認」の3点に絞られています。

実際のプロンプト（全文）

Claude Code への指示は、その場のチャットではなくプロジェクト直下の CLAUDE.md（指示書ファイル）に書いて運用しています。 毎セッション自動で読み込まれるため、同じ指示を繰り返す必要がありません。その主要部分を掲載します。

① CLAUDE.md「HTML生成の絶対ルール」

v2フローを絶対ルールとして明文化したものです。これにより翌日以降のセッションでも、 指示しなくても正しいフローに乗ります。

## ★ HTML生成の絶対ルール（最重要）

**HTMLは必ず `gen_html.py` で生成する。LLMがHTMLを直接書いてはならない。**

```bash
python3 text_kaggle_win/gen_html.py text_kaggle_win/chapter-N.json
```

- このスクリプトは任意の chapter-N.json を受け取り、chapter-N.html を出力する
- React / KaTeX / Prism.js / ダークモード / サイドバー / クイズ / 用語集 をすべて含む
- インタラクティブデモ（RankGauss・Target Encoding OOF・Wide-Long Format）は実装済み
- 未知の visual_descriptions は ui_instruction テキストを表示するプレースホルダーにフォールバック
- `/kaggle-chapter-html` スキルは廃止。スクリプトに一本化。

② CLAUDE.md「作業記録の自律更新ルール」

作業ログも人間が書くのではなく、Claude Codeが節目ごとに自動追記する仕組みにしています。 本ページの「開発フローの進化」の記述も、この自動記録された WORKLOG.md が情報源です。

## 作業記録ルール（自律更新・必須）

以下の節目で、ユーザーの指示を待たず **自律的に** WORKLOG.md に追記すること：

- JSONの更新完了（どの章が完了したか）
- HTMLの生成完了（どの章が完了したか）
- gen_html.py の機能追加・修正
- エラーの解決（何が起きて何で解決したか）
- 新しい作業パターンの確立

**更新対象ファイル**: `data_science/WORKLOG.md`

運用の仕組み — 再現するためのコツ

自作スキル（スラッシュコマンド）で定型作業をワンコマンド化

Claude Code の「スキル」機能で、繰り返し作業を再利用可能なコマンドにしています。 注目は廃止したスキルも「廃止」と明記して残していること。 CLAUDE.md に廃止理由まで書いておくことで、将来のセッションが古いフローに戻るのを防ぎます。

CLAUDE.md による「自己文書化」

ディレクトリ構成・ワークフロー・絶対ルール・廃止情報をすべて CLAUDE.md に集約。 Claude Code はセッション開始時にこれを読むため、プロジェクトの説明を毎回し直す必要がありません。 「AIへの指示書をコードと一緒にバージョン管理する」のがポイントです。

教材原稿のスキーマ（chapter-N.json）

原稿を以下の構造に統一することで、ジェネレーターが機械的にHTML化できます。

{
  "chapter_number": 5,
  "chapter_title": "...",
  "overview": "...",
  "sections": [
    {
      "section_id": "...",
      "title": "...",
      "concept_summary": "...",          // 概念の要約
      "detailed_explanations": [...],    // 詳細解説
      "key_characteristics": [...],      // 重要ポイント
      "author_opinions_and_warnings": [...],
      "tables": [...],
      "equations": [...],                // LaTeX数式
      "code_examples": [...],            // Pythonコード
      "visual_descriptions": [...]       // Canvasデモの指定
    }
  ],
  "quiz": [...],                         // 確認クイズ
  "glossary": [...]                      // 用語集
}

教材の技術構成

生成される教材HTMLは単一ファイル・ビルド不要で動きます。 CDNのライブラリを読み込むだけなので、生成物をそのまま配布・ホスティングできます。

継続学習を支える仕掛け（study-tools.js ほか）

• テキストハイライト・付箋メモ・ブックマーク — 紙の本でやることをWeb教材上で再現
• セクション読了ボタン・クイズスコア記録 — ダッシュボードに章ごとの進捗バーを表示
• 🔥 連続学習ストリーク・「前回の続きから」 — 学習の習慣化を後押し
• Gemini質問ボタン — 選択したテキストをそのままGeminiに投げて深掘り

まとめ — 持ち帰れる3つの学び

実物はこちらから触れます → materials-ds.pages.dev