# Math Study Note

> 研究の数理（測定設計・定理・手法の破れ）を、本人や共同研究者が数式を追って理解できる 学習用ノートに落とすスキル。md か 図解 HTML（KaTeX + HTML/CSS 図）の**どちらか1本**で作る。 既存ノートに散在した数式を「何を測りたいか → なぜ素朴には測れないか → だからこの測り方になる」 の一本の筋に再構成し、記号の層を最初に分離する構成を取る。 以下で起動: 「数理をまとめて」「学習用ノートを作って」「この式の筋を通して」 「何を測っているのか分からなくなった」「解説ノートにして」「study note を作って」 ※分野全体の教材群を生成するのは research-study-guide が担当。本 skill は 単一トピックの数理を1本のノートに凝縮する場合に使う。 ※原稿の文章推敲や論文本体の執筆は対象外（別の執筆系 skill が担当）。

- Skill: `yosukeiida/math-study-note` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add yosukeiida/math-study-note`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yosukeiida/math-study-note/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: YosukeIida (https://skillmd.com/u/yosukeiida)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yosukeiida/math-study-note

---


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

## このスキルが解く問題

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

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

## 成果物

| ファイル | 役割 |
|---|---|
| `notes/YYYYMMDD_<topic>_study_note.md` | **正本**。数式・表・参照マップ。git diff で追える |
| `notes/YYYYMMDD_<topic>_study_note.html` | 図解版。KaTeX で数式描画、図は HTML/CSS で組む |

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

## ワークフロー

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

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

```bash
# 対象の記号・概念が既存文書のどこにあるか
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** | 図・数式・対比が多く、読み手が1枚で通読する資料。`references/html-template.html` をベースにする |
| **md** | 数式が少ない、または本文の diff を追いたい（レビュー・共同編集が前提）。repo の md 慣習に従う |

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

### Phase 4: 検証

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

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

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

## 構成の核: 層の分離

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

| 層 | 変数 | 条件付け | そこで言える式 |
|---|---|---|---|
| 層1 | 対象全体（レコード・文書） | 大域的な side information | 主定理・情報量の等式 |
| 層2 | 位置ごとの要素（トークン） | 直前までの履歴 | 位置ごとの分解・定理 |
| 層3 | 粗視化した確率変数 | 同じ履歴 | 弱めた要求の下での等式 |

**層ごとに何が言えて何が言えないかを表で示す。**「層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`
- **色は主張の強度に割り当てる**（装飾ではない）:

| 色 | 意味 |
|---|---|
| indigo `#2B4C7E` | 主系統。定義・本文の骨格 |
| teal `#2B7A78` | **厳密に言えること**。等号で主張できる量 |
| plum `#8A4B9E` | 対比・近似版の手法 |
| amber `#E8A33D` / `#B57F22` | 用語の初出・注目・残差項 |
| shu `#C43C3C` | **注意・言えないこと・測定の破れ** |

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

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

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

したがって:

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

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

| クラス | 用途 |
|---|---|
| `.layer-map` | 層の地図（3段 + 右に使用場面 + 間に矢印） |
| `.barfig` | 「測れる量 / 内訳が不明」のバー対比 |
| `.dist` + `.bars` | 2つの分布の棒グラフ対比（div の height で描く） |
| `.nestfig` + `.nest` | 集合の入れ子（$V \supseteq G \supseteq S \supseteq \{x\}$） |
| `.terms` + `.term-box` | 分解の各項を色分けして並べる |

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

## 実測データのプロット（`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 のノート規約チェッカーが通る