Math Study Note

数理の学習用ノート（md + 図解 HTML）

このスキルが解く問題

研究が進むと、同じ記号（$p$, $q$, $H$, $D_{KL}$）が対象の違う層で使われ、 複数のノートに分散する。その結果、当人でさえ「何を測りたくて、この測り方は何なのか」が 分からなくなる。個々のノートは正しいのに、筋が通らない。

このスキルは、散在した数式を1本のノートに再構成してその筋を復元する。 新しい結果を作るのではなく、既にある結果の間の論理の橋を明示的に書くのが仕事。

成果物

md を先に作り、合意が取れてから HTML にする。md が正本で、数式を直すときは md 側を直す。

ワークフロー

Phase 0: 棚卸し（省略禁止）

何が既存文書にあり、何が無いかを grep で確定する。 ここを飛ばすと既存の記述を 重複させたり、実際には書かれていない式を「あるはず」と誤認する。

# 対象の記号・概念が既存文書のどこにあるか
grep -rn 'H(p)\|クロスエントロピー\|D_{KL}' <notes_dir>
grep -n '^#\{1,3\} ' <該当ノート>      # 目次を取って層を判定

確定させること:

1. 各文書がどの層を扱っているか（下記「層の分離」）
2. 層の間の橋（chain rule 等）がどこかに書かれているか
3. 欠けている式は何か — これが新しいノートの存在理由になる
4. 本ノートが土台にする主張は、実装で裏を取る。既存ノートに書かれていても、 そのまま信じない。「この図の右のバーは A である」のような記述は、図を生成している コードを読んで確認する。棚卸しは「どこに何があるか」だけでなく「それは正しいか」まで
5. repo に用語集（glossary.md 等）があれば読み、用語はそこから借りる。 手法名と操作の呼び名を割らない（手法が attributed 版 なら操作も attribute する）

なぜ 4 が要るか: 誤った前提を1つ引き継ぐと、その上に積んだ分析・図・修正がすべて 巻き添えになる。「既存ノートにそう書いてあった」は根拠にならない（過去の自分も同じ 手順を踏んだとは限らない）。裏取りの範囲は本ノートが依拠する主張だけでよい。

Phase 0 の結論は「本ノートで新しく明文化するもの」として §11 に列挙する。 ユーザーが「これは既にあるのでは」と疑ったときに答えられる状態にしておく。

Phase 1: 構成の合意

references/structure.md の11節テンプレートに沿って節立てを提示し、合意を取る。 勝手に全文を書き始めない（構成が合っていないと全部書き直しになる）。

Phase 2: md か HTML かを決めて、1本だけ書く

両方は作らない。 同じ内容が2箇所にあると必ず片方が古くなり、どちらが正かの判断が 読者に丸投げされる（更新のたびに二重に直すコストも乗る）。

HTML を選ぶ場合は references/structure.md の節構成をそのまま使う。数式の厳密性ルール （後述）はどちらでも守る。数式を含む図は SVG にしない（後述）。

Phase 4: 検証

# repo にノート規約チェッカーがあれば必ず通す（例）
uv run python scripts/check_notes_convention.py

規約チェッカーが無い repo では、少なくともファイル名規約・相対リンクの解決・ 数式のレンダリングを手で確認する。

• 数式が全てレンダリングされるか（生の $ が残っていないか）
• 図の中の数式も描画されているか
• 相対リンクが解決するか
• 880px 幅と 375px 幅で横スクロールが出ないか
• 図とキャプションが一致するか。図を作り直したら、そのキャプションを必ず読み直す。 設計を変えた図（バーの意味・軸・分割）は、キャプションが古い図を説明したまま残りやすい
• 貼ったが本文で論じていない図が無いか。図があるのに議論で使われていないなら、 読み取れることをキャプションに書くか、図を落とす
• 文献表の各項目が本文のどこかで引かれているか（後述「文献の引き方」）

構成の核: 層の分離

このスキルの最重要の型。 混乱の主因は記号の共有なので、本文より前に層の地図を置く。

層ごとに何が言えて何が言えないかを表で示す。「層1の語彙だけでは層2の話は読めない」と 明記する。層の間の矢印には「何をして降りたのか」（chain rule、粗視化、周辺化）を必ず書く。

対象が確率でない場合も同型に使える（例: 全体 → 局所 → 近似、仕様 → 実装 → 実測）。

数式の厳密性ルール

1. 恒等変形を省略しない。 結果だけ書くと読者は式を信用できない。1行の変形でも 「何をしたか」の注記を各行に添える（.derive クラス）。
2. 仮定を数え上げる。「仮定は絶対連続性と『$p$ は◯◯な過程』の2点だけ」のように 個数で言う。読者が確認可能になる。
3. 等号と不等号を区別して書く。「$= D_{KL}$（等号）」「$\ge$（下界）」を明示。 等号で言える箇所は本スキルの色規則で teal にする。
4. 期待値の添字を省略しない。 $\mathbb{E}_{x\sim p}[\cdot]$ の $p$ を落とすと 分解の成立条件が見えなくなる。
5. 単位を明示する。 per-byte / per-token / per-record のどれかで、数値の意味が変わる。
6. 誇張しない言い方に直す。「完全に分離できる」→「◯◯成分を厳密に下から押さえられる」。
7. 直感と数式を両方書く。 日本語の直感 → 数式で厳密化、の順。片方だけにしない。

「破れ」を隠さない

手法の失敗・未証明ギャップを表で対比して書くのが本スキルの型。

• 2つの実装を並べる場合: 近似版 = plum、厳密版 = teal で対比（.compare）
• 各版の破れを箇条書きで数える（会計の失敗 / 交絡 / 未証明ギャップ）
• 未実測・未実施・未検証には必ず pill を付ける（.pill.todo）
• 最後に「言えること」（teal）と「言えないこと」（shu）を分けたブロックを置く

これを省くと、暫定値が確定値として引用される事故が起きる。

視覚設計

references/html-template.html に CSS 一式がある。要点:

• 3書体（明朝見出し × ゴシック本文 × 等幅ラベル）＋ 28px 方眼の背景
• コンテンツ幅 880px、節の先頭に 01 / MAP 形式の sec-label
• 色は主張の強度に割り当てる（装飾ではない）:

禁止: 未実測値を teal で囲む（teal は「等号で主張できる」の印なので嘘になる）。

数式を含む図は SVG にしない（重要）

SVG の <text> 要素では KaTeX が効かない。 SVG で図を描くと、図内の数式が −log qᵢ(xᵢ) のような Unicode 近似表記になり、本文の数式と見た目が揃わない。

したがって:

• 箱・入れ子・バー・矢印は HTML/CSS で組む（div + grid + border）。数式は $...$ で書けば 本文と同じ KaTeX でレンダリングされ、色も親から継承される
• 副産物としてレスポンシブになる（SVG の viewBox 固定は小画面で文字が縮む）
• SVG が要るのは、実測データのプロット（figs/*.png を参照）や数式を含まない純粋な図形のみ

テンプレートに以下の図コンポーネントがある:

入れ子図と項リストは色で対応させる。 どの領域がどの項に対応するか色で追えるようにする。

実測データのプロット（figs/*.png）

概念図は上のとおり HTML/CSS で組むが、実測データのプロットは別（matplotlib 等）。 ここには本スキルの細則を置かない。次の順で外部に委ねる。

1. repo に図の規約があれば、それが優先（DESIGN.md の図の節、scripts/palette.py 等）。 フォント・印刷経路・過去図の凍結規約は repo ごとに違う
2. 無ければ dataviz skill を読んでから作る。「チャートのコードを1行書く前に、 色を選ぶ前に読め」が同 skill の原則。パレットは同梱の validate_palette.js を必ず通す
3. 作った規約は repo 側に残す（次に図を触る人が同じ判断をやり直さなくて済む）

HTML ノートの CSS 変数をプロットにそのまま流用しない。 あれは細い罫線と小さなバッジの ために選ばれたトーンで、図の大面積の塗りに使うと彩度と色覚分離の検査に落ちる。色相の 意味の対応（「厳密に言える量は teal 系」等）だけを保ち、値は検証済みパレットから採る。 学術・印刷向けの既定は Okabe-Ito（色覚バリアフリーの標準）。

図番号とキャプション

番号は文書順の通し番号にする

枝番（図3b・図4a）や ′ を作らない。 図を1枚足すと既存の番号がずれるので、 枝番で逃げたくなるが、そこから崩れる。実際に起きた壊れ方:

• 誤りのあった図を削除した結果、図4a/4b/4c が 4a/4b に繰り上がり、親のない枝番が残った
• 別の実測から作った図に既存図の枝番（図3b）を付け、無関係な図が親子に見えた
• 前の版から番号の重複（図5 が2つ）を引き継いだまま気づかなかった

図を足したら通しで振り直し、他のファイルからの参照も掃引する（handover・設計文書・ 関連ノート）。振り直しは面倒だが、枝番の解読はもっと面倒である。

キャプションには4つを、それぞれ行頭から書く

図は貼れば伝わるものではない。なぜその図を作ったのかは、作った本人にしか書けない。

0. 図タイトル（画像に入れないなら、ここが図の唯一の名前）
1. 何を見たい図か（問い）— 「〜を比べたもの」ではなく「〜かどうかを見るため」
2. なぜこの形にしたか（形式の理由）— 積み上げなら「合計が実測値に一致する恒等式を 見せるため」。自明なら省略してよい
3. 図から何が読めるか（知見）— 数値そのものではなく、その数値が何を意味するか。 「CORD 0.174」ではなく「CORD が最下位で、全体の順位と入れ替わっている」

そのあとに出自と留保を添える（実測日・再生成日・数値が不変であること・下界であること）。 節番号だけの参照で済ませない。「§07 で並べた2つの実装」ではなく「attributed 版と forced 版（本節の冒頭で並べた2つの実装）」のように、指しているものを語で言う。

4つを地の文に埋めない。長いキャプションほど「読めること」の位置が読者に見つからなくなる。

文献の引き方

文献表に載せた文献は、必ず本文のどこかで引く。 引かれない文献は「なぜ挙げたのか」を 説明できないので、落とすか本文で使う。文献表だけが立派で本文から一度も参照されない、 という状態が最も起きやすい。

本文の参照は 著者 + 年 + 短い論文名を書く。[1] のような番号だけの参照は使わない ——読者が末尾との往復を強いられ、その場で何の話をしているか分からない。

• 定義・定理・手法を導入した箇所でこそ引く。「この枠組みは既存のもの」「この難しさは 既知」をその場で示せると、読者は安心して先へ進める
• 何のために引くのかを1文添える。「$G_i$ の完備性」のような括弧書きを文献表側だけに 置くと、本文を読んでいる人には届かない
• HTML なら文献表の各項目に id を振り、本文から飛べるようにする。ただし 本文だけ読んでも意味が取れるように、著者名と論文名はその場に書く

やらないこと

• 新しい結果・新しい実測値を作る（このスキルは既存結果の再構成のみ）
• 過去のノートを編集・上書きする（凍結。作り直しは今日の日付の新ファイル）
• 対話要素（シミュレーター等）を入れる（研究ノートは静的・自己完結）
• ダークモード対応（印刷・PDF 化して渡す経路があるため明るい紙面に固定）

チェックリスト

• Phase 0 の棚卸しを実施し、§11 に「本ノートで新しく明文化したもの」を列挙した
• 層の地図が本文より前にある
• 恒等変形の各行に注記がある
• 仮定を個数で数え上げている
• 「言えること」（teal）と「言えないこと」（shu）が分離されている
• 未実測・未実施に .pill.todo が付いている
• 図の中の数式が SVG text になっていない
• md か HTML のどちらか一方だけを作った
• 図番号が文書順の通し番号になっている（枝番・重複が無い）
• 各図のキャプションに「何を見たい図か」「読めること」がある
• 図を作り直した図は、キャプションを読み直した
• 文献表の全項目が本文のどこかで引かれている
• 参照マップに既存文書の file:line がある
• repo のノート規約チェッカーが通る