chore(readme): 読み進め方ガイドを章変化に動的対応させる（ルート定義 YAML + build.py 自動生成）

[watanabe-kohei-jp]

背景

PR #35 / Issue #32 で README に「読み進め方（推奨ルート）」セクションを追加した。が、章ファイル名（00-about/, 01-claude-code-intro/, 02-setup/, 03-claude-md/）が README 内にハードコード されており、以下のケースで必ず壊れる：

• Issue 教材の章構成を見直す（新 03「LLM の仕組み」を追加、現 03-claude-md を 04 にリネーム） #27 の章構成見直し（章番号リネーム）
• 新章追加（例: 03-llm-fundamentals/）
• 章の削除・統廃合

そのたびに README を手で直すのは持続可能ではないし、直し忘れたら受講者が壊れたリンクを踏む。

目的（目的層）

README の「読み進め方（推奨ルート）」セクションを、章ファイルの追加・リネーム・削除に追従できる構造 に変える。ガイドの編集と章ファイルの変更を 1 箇所にまとめ、不整合は CI / ビルドで検出する。

手段（手段層）

ユーザー選択: ルート定義 YAML + 部分自動生成 で進める。

構成

1. data/reading-routes.yml （人間が編集するソース）

   routes:
     - id: beginner
       label: ルート A — はじめての方
       duration_min: 30
       audience: 「Claude Code をまだ触ったことがない／聞いたことはあるけど使っていない」
       goal: Claude Code を自分の PC で動かして、ちょっとした質問を投げられる状態。
       chapters:
         - id: 00-about
           note: "**必読**。なぜこの形（HTML × Git × AI）の教材なのか、思想を 9 枚で。"
         - id: 01-claude-code-intro
           note: "Claude Code とは何か、何ができるか"
         - id: 02-setup
           note: "手元にインストールして触ってみる"
     - id: claude-user
       ...
     - id: builder
       ...

2. README.md に AUTOGEN マーカー

   <!-- AUTOGEN:reading-routes -->
   （ここを build.py が再生成）
   <!-- /AUTOGEN:reading-routes -->

3. build.py 拡張

   • 既存の find_chapters() で実在章リストを取得
   • data/reading-routes.yml を読み、各 chapter.id が実在するかチェック（不整合は exit 1）
   • Markdown を組み立てて README の AUTOGEN マーカー間を置換
   • 既存の python build.py を実行するだけで README も同期される

4. CI（既存ワークフロー追加 or 新規）

   • python build.py --check（再生成して diff が出たら fail）モードを追加
   • これで「YAML だけ直して README を build し忘れた PR」を検出

スコープ

• ✅ ルート定義 YAML 化
• ✅ build.py の部分再生成サポート
• ✅ 章 ID 実在チェック
• ✅ CI による drift 検出
• ❌ 章メタによる完全自動振り分け（persona ラベルで章をルートに自動配置）→ 必要なら別 Issue
• ❌ 「### 読み方のスタイル（3 パターン）」セクション → 静的のまま（章ファイル名に依存しない）
• ❌ 「## 何が読めるか」テーブル → 別 Issue 候補（同じ仕組みで自動化可能だがスコープ膨張回避）

判断軸

観点	判断
依存追加	pyyaml を入れるか、JSON で済ますか。build.py の既存依存は標準ライブラリのみ。JSON にして依存を増やさない方針が無難
章 ID の表記	ディレクトリ名そのまま（00-about 等）。find_chapters() の戻り値と直接突き合わせ可能
AUTOGEN マーカーの可視性	HTML コメントなので GitHub レンダリングでは見えない。読者には影響なし
README に書く章名・所要時間の正本	YAML が正本。README は派生。Single Source of Truth

受け入れ条件

• data/reading-routes.json（または .yml）を編集 → python build.py で README の該当セクションが更新される
• YAML 内の章 ID が実在しない場合、build.py が exit 1（エラー内容に該当 ID を表示）
• PR docs(readme): 読み進め方ガイド（推奨ルート3パターン）を追加 #35 マージ後の現状 README と等価な出力を生成できる
• CI で「YAML を直したのに build し忘れた」状態を検出できる
• ## 何が読めるか テーブルや「読み方のスタイル（3 パターン）」セクションには影響しない

関連

• Issue docs: この資料の読み進め方を具体的に案内する導線を追加する #32 / PR docs(readme): 読み進め方ガイド（推奨ルート3パターン）を追加 #35（読み進め方ガイドの追加）— 本 Issue はその継続
• Issue 教材の章構成を見直す（新 03「LLM の仕組み」を追加、現 03-claude-md を 04 にリネーム） #27（章構成見直し）— 本対応が完了していれば、章再編時の README 手修正が不要になる

[watanabe-kohei-jp]

PR #36 と重複のためクローズ判断

PR #36 (feat(automation): auto-sync listings from NN-slug/index.html) が main にマージされ、本 Issue のスコープ大部分（README 章テーブルの動的化）が実装済みとなりました。

PR #36 は 各章 index.html の <meta> を真実源とする 方針で、本 Issue で計画していた data/reading-routes.json 中心の設計とは異なります。真実源を 2 系統持つのは不健全なので、当初計画は撤回します。

残された価値

「## 読み進め方（推奨ルート）」セクションの動的化は PR #36 ではカバーされていません。これは別 Issue を立てて、scripts/sync_listings.py の仕組みに乗る形で再計画します。

本 Issue はクローズします。後続 Issue は scripts/sync_listings.py 拡張として作成予定。