worked-example-walkthrough

具体例の手順解説

目次

1. ワークフロー
2. フレームの構成
3. 適切な例の選び方
4. よくあるパターン
5. ガードレール
6. クイックリファレンス

手順解説は、計算の各段階での状態を示す、番号付きフレームの連なりです。各フレームでは、3つの問いに答えます。現在の状態は？、どの操作によってこの状態になったのか？、学習者は何に注目すべきか？

これは、純粋なテキストで表現できるもののなかで、3Blue1Brownのアニメーションに最も近いものです。学習者は操作を手作業でたどり直すことができ、途中の状態を明示することで、最終結果だけを示す説明では見落とされがちな混乱を防げます。

簡単な例（2×2行列の固有値）：

A = [[4, 1], [2, 3]] の固有値を求めます。

フレーム 1. 状態：A = [[4, 1], [2, 3]] です。det(A − λI) = 0 となる λ を求めます。

フレーム 2. A − λI を作ります。

A - λI = [[4-λ,  1 ],
         [ 2,  3-λ]]

フレーム 3. 行列式を計算します。 det = (4 − λ)(3 − λ) − 1·2 = (12 − 7λ + λ²) − 2 = λ² − 7λ + 10

フレーム 4. λ² − 7λ + 10 = 0 を解きます。 因数分解すると、(λ − 5)(λ − 2) = 0 です。したがって、λ = 5 または λ = 2 です。

フレーム 5. 固有値は 5 と 2 です。簡単な検算をします。trace(A) = 4 + 3 = 7 = 固有値の和 ✓；det(A) = 12 − 2 = 10 = 固有値の積 ✓。

注目すべき点： 特性多項式は det(A − λI) を展開したものにすぎません。固有値を求めるのは、単に根を求めることです。難しいことは何もありません。

5つのフレーム、約80語です。学習者は1分もかからずに、紙の上でこの計算をやり直せます。

ワークフロー

このチェックリストをコピーして、進捗を記録してください。

Walkthrough Progress:
- [ ] Step 1: Pick the smallest possible example that exercises the concept
- [ ] Step 2: Write the goal — what we'll compute and why
- [ ] Step 3: Plan the frames (3-7 typically)
- [ ] Step 4: Write each frame: state, operation, notice
- [ ] Step 5: End with a sanity check or invitation to verify
- [ ] Step 6: Optional — invite the learner to redo with a variant

ステップ 1：概念を扱う、できるだけ小さな例を選ぶ

例は小さくする必要があります。2×2 行列、3 要素のベクトル入力、3 トークンの系列などです。大きな例では、計算に構造が埋もれてしまいます。

また、その例で概念を実際に扱う必要があります。単に自明な例を示すだけでは不十分です。対角行列の固有ベクトルは自明なので、対角行列ではない 2×2 行列を選びます。スカラーのアテンションは自明なので、少なくとも 3 トークンを選びます。

各概念に推奨される例のサイズ一覧については、resources/examples.md を参照してください。

ステップ 2：目標を記述する — 何を、なぜ計算するのか

1 文で記述します。「A = [[4, 1], [2, 3]] の固有値を計算する。」または「ランダムな Q、K、V ベクトルを使い、3 トークンの系列にアテンションを適用する。」という具合です。この目標が、その後のすべての枠組みになります。

ステップ 3：フレームを計画する（通常 3～7 個）

各フレームは 1 つの操作を表します。書き起こす前にフレームの概要を作成してください。そうすることで、「手順を飛ばす」という問題を、文章にする前に見つけられます。

多くの操作でうまく機能するフレーム数の目安：

• 3 フレーム：単純な流れ（変換が 1 つ）
• 5 フレーム：一般的な単一概念の解説（固有値、ソフトマックス、SGD の 1 ステップ）
• 7 フレーム：複合的な解説（すべてのサブステップを示すアテンション）

7 フレームを超えそうな場合は、例が大きすぎる（小さくする）か、操作に複数のサブ操作があり、それぞれに独立した解説が必要です。

ステップ 4：各フレームを記述する：状態、操作、注目点

各フレームには 3 つの要素があります（フレームの構成を参照）：

• **状態：**現在の値を明示して示します。
• **操作：**ここに至るまでに行ったこと、またはこれから行うことです。
• **注目点：**学習者が見落とすかもしれない点を指摘する 1 文です。

「注目点」が、解説を単なる解答例と区別します。解答例は手順を示しますが、解説ではさらに何に注目すべきかも伝えます。

ステップ 5：整合性チェック、または確認の呼びかけで締めくくる

すべての解説は、次のいずれかで締めくくります：

• 整合性チェック：「トレース ✓、行列式 ✓」。
• 一貫性チェック：「結果の形状は予想どおりです」。
• 確認の呼びかけ：「A = [[1, 2], [3, 4]] でも同じ操作を試してみてください。答えは λ ≈ −0.37 と λ ≈ 5.37 になるはずです。」

整合性チェックによって、学習者は結果が正しいと確認できます。また、類似の問題にも応用できる再利用可能な検証方法にもなります。

ステップ 6（任意）：別の条件でやり直すよう学習者に促す

時間に余裕があり、例が短い場合は、小さな変更を加えてやり直すよう促します：

• 「行列は同じで、初期ベクトルを変えます。v = (1, 0) の代わりに v = (0, 1) でやり直してください。」
• 「同じアテンション計算で、1 つのトークンの K をゼロに置き換えます。計算する前に、出力がどう変わるか予測してください。」

条件を変えた例は、計算だけでなく、全体像が理解できているかを確かめます。

フレームの構成

各フレームには 3 つの要素があります。見た目で区別できるようにしてください。

**Frame N.** [Operation: short verb phrase, what we're doing.]
[State: explicit values, in a code block if needed.]
[Notice: one sentence — what to look at.]

状態ブロック

行列、ベクトル、数式にはコードブロックを使います。実際の数値を示し、記号のままにするのは避けてください。大切なのは具体性です。

v = (3, 4)
|v| = √(3² + 4²) = √25 = 5

操作の説明

短い動詞句を 1 行で記します。「計算する…」「適用する…」「代入する…」「解く…」などです。

注目点の文

このフレームで最も重要な特徴を指摘する 1 文です。

• 「交差項が打ち消し合いました。これは A が対称行列だからです。」
• 「2 つ目の固有値が負であることに注目してください。A はその方向に沿って反転します。」
• 「ソフトマックスの重みは 1 行目で最大になっています。トークン 1 のクエリはキー 1 と強く一致しました。」

注目点の文を書く意味がないフレームは、独立したフレームにする必要がないかもしれません。まとめることを検討してください。

適切な例を選ぶ

選ぶ例によって、解説の良し悪しが決まります。例を選ぶ際のヒューリスティクス：

記号ではなく、具体的な小さな数値を使う

a, b, c, d を使った解説は、解説ではなく導出です。目で見て計算できる程度に小さく、パターンが見える程度に変化のある 2、3、1、−1 などの数値を選びましょう。

最も単純なケースは避ける

単位行列、ゼロベクトル、すべて等しいスコアは、あまりに単純で、演算を実際に試せません。チュートリアルの学習者には、演算が実際に意味を持つ場合に何が起きるのかを見せる必要があります。

検証可能な性質を持つ例を選ぶ

対称行列は実固有値を持つため、バグを見つけやすくなります。確率行列は定常分布を持つため、検証しやすくなります。このように検証可能な性質を持つ例を選ぶと、ステップ 5 の健全性チェックに意味が生まれます。

迷ったら、最小の非自明なサイズを使う

• 行列：まずは 2×2。2×2 では概念を示せない場合に限り、3×3 を使います。
• ベクトル：2D または 3D。
• シーケンス：最低 3 トークン（そうすればアテンションが興味深くなります）。パリティが必要なら 4 トークン。
• ネットワーク：バックプロパゲーションのデモでは、最低でも 1 層、入力 2 個、出力 1 個。

概念ごとの推奨例については、resources/examples.md を参照してください。

よくあるパターン

パターン A：単一計算のチュートリアル

固有値の計算、SGD の 1 ステップ、アテンションのフォワードパス 1 回、ベクトルのソフトマックスなど、1 回限りの演算に使います。 長さ：3～5 フレーム。 締めくくり：健全性チェック。

パターン B：反復型チュートリアル

複数回ループするプロセスに使います。複数ステップにわたる勾配降下法、固有ベクトルを求めるべき乗法、拡散サンプリングなどです。 長さ：2～3 回の反復を明示し、その後に「このように続きます…」と示す 5～7 フレーム。 締めくくり：収束についてコメントし、極限値を予想するよう促します。

パターン C：比較型チュートリアル

2 つの演算の違いを示すために使います。行とベクトルの内積としての行列・ベクトル積と、列の線形結合としての行列・ベクトル積、レイヤーノルムとバッチノルム、同じ勾配に対する SGD と Adam などです。 長さ：2 列で並行するフレーム、または 2 回のパス。 締めくくり：両者が等価である理由、または異なる理由を説明する一文を添えます。

各パターンの記入済みチュートリアルについては、resources/examples.md を参照してください。

ガードレール

• 記号ではなく、実際の数値を示します。 Av を使ったチュートリアルは導出であり、[5, 11] を使ったチュートリアルが、学習者向けのチュートリアルです。学習者には値を見せる必要があります。
• 学習者が迷う可能性のある計算を省略しないでください。 「(4−λ)(3−λ) − 2 = λ² − 7λ + 10」は問題ありませんが、「(4−λ)(3−λ) − 2 = (λ−5)(λ−2)」では展開を省略しています。まず多項式を示し、その後に因数分解してください。
• 各フレームで状態を進めます。 状態が前のフレームと同じで、言い換えただけのフレームは無駄です。
• 1 つのフレームでは演算を 1 つだけ使います。 1 つのフレームに 2 つの演算があるなら、それは 2 つのフレームに分けます。
• 計算の中に要点を埋もれさせないでください。 最後に結果を明確に示し、健全性チェックも明示します。
• 計算が長い場合は、Bash の使用を検討してください。 計算が本当に長い場合（例：4×4 の固有値問題）は、Bash で numpy を使って中間状態を求めます。ただし、演算自体はフレームとして示してください。Bash の出力は検証に使うものであり、チュートリアルそのものではありません。

クイックリファレンス

演算	推奨例	フレーム数
行列・ベクトル積	A = [[1, 2], [3, 4]], v = (5, 6)	3
固有値	A = [[4, 1], [2, 3]]	5
既知の λ に対する固有ベクトル	同じ A、λ = 5	4
SVD	A = [[3, 1], [1, 3]]（SVD が簡潔になる対称行列）	6
ソフトマックス	x = (2, 1, -1)	4
交差エントロピー	p = (1, 0, 0), q = (0.7, 0.2, 0.1)	3
SGD の 1 ステップ	損失 x²、開始時の x = 4、η = 0.5	4
アテンションのフォワードパス	3 トークン、d = 2	7
LayerNorm	x = (1, 5, 9)	5
小規模ネットワークのバックプロパゲーション	y = w₂σ(w₁x)、入力 1 個、出力 1 個	6
小規模データセットの PCA	2D の点 4 個	6

各項目の完全な記入済みチュートリアルについては、resources/examples.md を参照してください。