はじめに
- ハンズオン本で写経したポーカーゲーム。動くけど、全部の処理は理解しきれていない。特に「HTMLとJSにまたがる処理」が読みづらい。
- そこで、コードを「説明してもらう」のではなく、Claude Code に「動かして中身が見える学習ラボ」を作ってもらった。
- 「読む」が「触って確かめる」に変わり、理解の解像度が一段上がった。
- この進め方を汎用の
CLAUDE.mdにまとめた（記事末尾）。題材が何であれ、同じやり方で“理解用ラボ”を作れる。
1. 課題：「写経は終わった。でも分かってはいない」
ハンズオン形式の本に沿って、ブラウザで動くポーカーゲームを写経しました。クラスはきれいに分かれていて、ちゃんと動きます。
…が、正直に言うと「動かせるけど、中で何が起きているかを説明できない」状態でした。とくに引っかかったのが次の点です。
- 「Drawボタンを押す → 少し待つ → 相手が動く → 勝敗」と進む非同期の順序が頭の中で再生できない。
- そして最大の壁が、処理が HTML と JavaScript にまたがって飛ぶこと。HTMLファイルを眺めてもボタンとカードの“枠”しか書いておらず、実際の動きはJS側。行ったり来たりで、どこで何が起きているのか見失う。
解説文を読めばなんとなくは理解できるものの、手応えとして残らない。これが出発点でした。
2. 発想の転換：説明させるのではなく、“理解用ラボ”を作らせる
LLM にコードを説明させると、その場では分かった気になります。でも、自分で触って確かめていないので定着しません。
逆に、過程が見えて・結果が即返ってくるものがあれば、理解は手で覚えられます。そこで Claude Code にこうお願いしました。
「このポーカーゲームのコードを理解できるようなプロダクトを作って」
出てきたのは、解説テキストではなく触って学べるWebアプリでした。
3. できあがったもの：Poker Code Lab
ゲーム本体には一切手を入れず、別ディレクトリに学習用のWebアプリを作ってもらいました。タブ構成は次のとおりです
| タブ | 何が見えるか |
|---|---|
| ① 全体像 | ファイル/クラスの役割分担と、起動・操作の処理フロー |
| ② データ変換の実演 | 「番号 → 数字・絵柄」の計算を数式1ステップずつで表示 |
| ③ 判定ロジックのトレース | 5枚を選ぶと、役判定がどの順で何を調べて結論を出すかを可視化 |
| ④ 実機デモ＋内部のぞき見 | 実際に遊びながら、山札・手札・相手の判断・勝敗計算を実行ログで表示 |
| ⑤ コード解説 | 本体の実ソースを取得し、各ファイルの「狙い・読みどころ」を注釈 |
| ⑥ HTML↔JS 橋渡し | またぐ処理を可視化（後述。ここが一番効いた） |
4. 効いた設計：可視化の「4つの型」
このラボの本質は、ポーカーそのものではなく 「分かりにくいコードを、種類ごとに可視化する型」 にあります。ここが他のコードにも効く部分です。
- 変換ロジック → スライダー＋数式の段階表示。番号を動かすと、数字と絵柄がどう決まるかが目で追える。
- 評価/判定ロジック → 入力を選ぶと判定過程をトレース。「並べ替え → 強い役から順に検査 → 最初に成立したものを採用」という流れと、“なぜその結論か”が見える。
- 非同期/順序 → ステップ送り＋自動再生。何が・どの順で起きるかを実行ログで再生できる。
- 言語をまたぐ処理 → またぐ箇所（接点）を示す。そして1往復をステップで再生する。
とくに 4 は、自分の最大の悩み「HTMLとJSにまたがって読めない」に直撃でした。
HTML↔JS は「4つの接点」だけで会話している
読みづらさの正体は、HTMLとJSがDOMという共有の黒板を介して会話しているのに、その通り道が見えていないこと。通り道は実は4つだけ、と整理できます。
-
① 名前で発見：HTML の
id/classを、JS が「あの名前の要素」と探して掴む。 - ② イベント（入力）：クリックなどが HTML → JS へ飛び、対応する処理が動く。
-
③ 属性で表示変更（出力）：JS が要素の
srcやclassを書き換え → 画面が変わる。 - ④ メタデータ（紐づけ）：JS が要素に番号などを書き込み、後で「これはどのデータか」を逆引きする。
ラボの⑥タブでは、「カードを選ぶ → ボタンを押す」という1往復を1ステップずつ再生し、いまHTML→JSなのかJS→HTMLなのかを左右で光らせて見せてくれます。
5. AIとの進め方（体験記）
うまくいった協働の流れは、ざっくり次のとおりです。
- まず全コードを読ませて「責務マップ」を作らせた。 どのファイルが何担当か、起動からの流れを1枚に。
- 「つまずきポイント」を特定させ、それぞれをタブに割り当てた。 漠然と「解説して」ではなく、壁の種類ごとにUIを決めたのが良かった。
- 本体は不改変。別ディレクトリに「計装版」を作らせた。 元コードと同じアルゴリズムを、途中経過を出せる形で書き直し、実ソースとも見比べられるように。
-
検証も任せた。 手元にNode等のランタイムが無い環境だったので、macOS 同梱の JavaScriptCore（
osascript -l JavaScript）で構文チェックを通し、ロジックは代表的な手札で期待値と突き合わせて確認してもらった。 - 「HTMLコードと対応させたい」など、追加の要望で深掘りした。 一発で完璧を狙わず、自分の「ここが分からない」を起点に対話で育てていく。これが一番効いた進め方でした。
学びとしては、「説明させる」より「触れる教材を作らせて、つまずき起点で対話的に育てる」ほうが、理解にも記憶にも残るということ。
6. 汎用化：CLAUDE.md にまとめた
「ポーカーだから」ではなく、どんなコードでも同じ型で“理解用ラボ”を作れるはず。そこで進め方を完全汎用の CLAUDE.md に落とし込みました。任意のプロジェクト直下（または ~/.claude/CLAUDE.md）に置けば、Claude Code がこの方針で学習ラボを作ってくれます。
# CLAUDE.md — 未知のコードを「理解するための学習ラボ」を作る
## 目的
既存コード（写経した題材、引き継いだ実装、OSS など）を読むだけで終わらせず、
動かして内部を可視化する小さなWebアプリ（＝学習ラボ）を作り、理解を定着させる。
ゴールは「説明文を生成すること」ではなく「触れる教材を生成すること」。
## 原則
- 説明より実演。「なぜその結論になるか」を “入力 → 過程 → 結果” で見せる。静的な解説文は最小限に。
- 本体は不改変。ラボは必ず別ディレクトリに作る。元コードには一切手を入れない。
- 計装版で中身を見せる。本体ロジックを別ファイルに同じアルゴリズムで再現し、
途中経過（トレース）を返せるようにする。元の実ソースも併記して見比べられるようにする。
- 自己完結。CDN 等の外部依存を避け、オフラインでも動く。サーバが必要なら手順を明記。
## 進め方
1. 責務マップ。全ファイルを読み、各ファイル/クラスの役割と、呼び出しの流れ
（起動 → 主要操作 → 終了）を1枚にまとめる。
2. つまずき特定。理解の壁になりやすい点を洗い出す。典型は
①データ変換 ②評価/判定ロジック ③状態の所在 ④非同期/順序 ⑤層をまたぐ処理（UI↔ロジック, API↔DB 等）。
3. タブ設計。各つまずきに「動かして見える」UI を1つずつ割り当てる。
4. 計装＆検証。本体ロジックを再現して過程を可視化。
ランタイムが無くても構文チェックを通し（例: JS は `osascript -l JavaScript`、各言語の `-c`/パーサ）、
ロジックは代表ケースで期待値と突き合わせる。
5. 対話で深掘り。一発完成を狙わない。利用者の「ここが分からない」を起点にタブを足していく。
## 可視化の型（つまずき種別 → UI）
- 変換ロジック（id→属性, バイト→値, 座標変換 など）
→ 入力スライダー＋数式を1ステップずつ表示し、結果（画像・値）を即時反映。全パターンの対応表も添える。
- 評価 / 判定ロジック（採点, バリデーション, 役判定 など）
→ 入力を選ぶと判定過程をトレース。「並べ替え → 条件を順に検査 → 最初に成立したものを採用」のように、
なぜその結論かを段階表示する。
- 状態機械 / 非同期フロー
→ ステップ送り＋自動再生で順序を可視化。各ステップで「いま何が・どの順で」起きるかを実行ログで見せる。
- 層をまたぐ処理
→ またぐ箇所（接点）を有限個に言い切る（例: UI とロジックは「名前で発見 / イベント / 属性書換 / メタデータ」だけ）。
1往復をステップで再生し、どちら向きに移ったかを左右で光らせる。
- 実ソース × 実行時の差分
→ ファイルの静的な姿と、実行時にコードが書き換える動的な姿を対応表示する
（「この属性はファイルに無く、実行時にコードが付ける」を明示）。
これが「コードを読んでも動きが見えない」を解消する最重要パターン。
## 成果物チェックリスト
- [ ] 別ディレクトリに自己完結したラボ（本体は不改変）
- [ ] 責務マップ＋起動 / 主要フローの図
- [ ] つまずき各点に対応する「触れる」タブ
- [ ] 元の実ソースの併記（できれば取得して注釈）
- [ ] 構文チェック＋代表ケースでのロジック検証
- [ ] README（起動方法・各タブの狙い）
## アンチパターン
- コードをただ要約して「分かった気」で終わる（手が動く教材になっていない）。
- 本体ファイルを書き換えてしまう（差分が混ざり、元コードとの比較ができなくなる）。
- 外部CDN前提で、オフラインや閉じた環境で動かない。
7. まとめ
- 写経で「動くけど分からない」が残ったら、説明させるより“理解用ラボ”を作らせるのが効いた。
- つまずきの種類ごとの可視化の型。とくに「層をまたぐ処理」は、接点を有限個に言い切り、実ソースと実行時の差分を対応させると一気にほどける。
- 進め方は完全汎用の
CLAUDE.mdに切り出した。題材を変えても同じやり方で再現できる。
「読む」だけで詰まったら、「触れる教材を作る」に切り替えてみてください。理解の残り方が変わります。
使用教材
図解！ JavaScriptのツボとコツがゼッタイにわかる本 プログラミング実践編
https://www.shuwasystem.co.jp/book/9784798067247.html