02 計画と設計

学習者向けレッスン 02 計画と設計 に対応するファシリテーター向けの手引きです。

所要時間

約 90 分で、そのほとんどが無人ではありません。これは、バックグラウンドで走るスクリプトでは なく、個人またはペアでのワークシート作業を軸に組まれた唯一のモジュールです。Step 1 （プロファイリングスクリプト）が唯一の自動化された部分で、数分で終わります。それ以外の すべて — Step 2 の 5 つのワークシートと Step 3 の migration-plan.md — が実際に 90 分を 費やす場所です。このモジュールの中に休憩を入れないでください。会場が休憩を必要とする場合は、 ワークシートの途中ではなく、モジュール 03 との境目で取ってください。

トークトラック

• まず、このモジュールが何ではないかから始めてください。これはモジュール 03 の「本当の」移行の 前に置かれた遅延ではありません。ClickHouse への移行が期待した性能に届かない最も多い理由は、 チューニングの問題ではなくアーキテクチャの問題です。チームが先にデータを動かし、設計を 後回しにするのです。
• 90 分を費やす根拠として最も強力な主張なので、これは直接名指しで伝えてください。これは パートナーが最も飛ばしたくなるモジュールです。モジュール 03 の setup.sh は migration-plan.md が欠けていたり不完全だったりしても警告するだけで、決してブロックしない からです。
• それでもパートナーが飛ばした場合に何が起きるかを説明してください。モジュール 03 では機械的に 成功します。fact_trips は ReplacingMergeTree として立ち上がり、データも移動します。 しかし、なぜ単なる MergeTree ではなくそのエンジンなのかは分からず、ORDER BY キーが クエリのワークロードからどう導かれたのかも分からず、dbt の設定にある delete_insert と FINAL も認識できず、モジュール 05 のベンチマークでの高速化を顧客に説明したり再現したり することもできません。
• Worked Example（実例）のリファレンスページは、パートナーが自分の計画を試みた後にのみ 指し示してください。それは考え抜く前に写すためのテンプレートではなく、健全性チェックです。

よくある失敗

• Step 1 のプロファイリングスクリプト実行時に ACCOUNT_USAGE が使えない。 これには Snowflake アカウント作成後の 1〜3 時間の伝播待ち、または ACCOUNTADMIN ロールのいずれかが 必要です。スクリプトは自動的に INFORMATION_SCHEMA にフォールバックし、計測できなかった ものを記録します。これはクラッシュではなく優雅な機能低下ですが、パートナーは フォールバックが起きたことに気付かないかもしれません。自動プロファイルが内容に乏しく見える 場合は、Snowflake UI で手作業で実行できる scripts/02_query_history.sql を案内してください。
• パートナーが migration-plan.md の Completion Checklist を任意のものとして扱う。 そうではありません。モジュール 03 の setup.sh はそれを読み取り、チェックが入っていない ボックスは、ファイル自体は存在していても実質的にこのモジュールが飛ばされたというシグナルです。
• TODO: モジュール 01 や 03 と違い、このモジュール自身の README にはトラブルシューティングの セクションがありません。ワークシート部分を実際の会場で実施したら、リハーサルの結果からここを 埋めてください。

リセット手順

• profile_report.md（Step 1 の出力）は gitignore されており、実行ごとにパートナー自身の ライブ Snowflake アカウントから新しく生成されます。古かったり誤っているように見えたら、 単に ./scripts/01_profile_snowflake.sh を再実行してください。破棄するものはありません。
• 5 つのワークシートはサイト上で記入し、回答は即時に採点されて参加者のブラウザ （localStorage）に保存されます。リポジトリには保存されません。migration-plan.md は 引き続きリポジトリ内で直接編集します。このモジュールはどちらのクラウドにも何も プロビジョニングしないため、teardown.sh も、手を伸ばすべきセットアップのフラグも ありません。
• 参加者がワークシートを壊れた状態にしてしまった場合は、git の checkout ではなく、その ワークシート自身の「Clear answers」操作を案内してください。回答は git に触れたことがない ため、checkout では解決しません。